001/*
002 * Copyright 2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.revetsec.oauth;
018
019import com.revetsec.json.JsonObject;
020import com.revetsec.json.JsonValue;
021import org.jspecify.annotations.NonNull;
022import org.jspecify.annotations.Nullable;
023
024import javax.annotation.concurrent.Immutable;
025import java.time.Instant;
026import java.util.Map;
027import java.util.Optional;
028import java.util.Set;
029
030import static java.util.Objects.requireNonNull;
031
032/**
033 * One token-endpoint success. It carries raw tokens, not a verified identity. Unknown JSON members can be inspected
034 * through safe accessors; all token and error members, including {@code id_token}, are excluded from them.
035 *
036 * @author <a href="https://www.revetkn.com">Mark Allen</a>
037 * @since 1.0.0
038 */
039@Immutable
040public final class TokenResponse {
041        private final @NonNull AccessToken accessToken;
042        private final @Nullable RefreshToken refreshToken;
043        private final @Nullable Set<@NonNull String> grantedScopes;
044        private final @Nullable String scope;
045        private final @NonNull Instant receivedAt;
046        private final @NonNull JsonObject safeParameters;
047        private final @NonNull Map<@NonNull String, @NonNull String> applicationData;
048
049        TokenResponse(@NonNull AccessToken accessToken, @Nullable RefreshToken refreshToken,
050                        @Nullable String scope, @Nullable Set<@NonNull String> grantedScopes,
051                        @NonNull Instant receivedAt, @NonNull JsonObject safeParameters) {
052                this.accessToken = requireNonNull(accessToken);
053                this.refreshToken = refreshToken;
054                this.scope = scope;
055                this.grantedScopes = grantedScopes == null ? null : Set.copyOf(grantedScopes);
056                this.receivedAt = requireNonNull(receivedAt);
057                this.safeParameters = requireNonNull(safeParameters);
058                this.applicationData = Map.of();
059        }
060
061        private TokenResponse(@NonNull TokenResponse original,
062                        @NonNull Map<@NonNull String, @NonNull String> applicationData) {
063                this.accessToken = original.accessToken;
064                this.refreshToken = original.refreshToken;
065                this.grantedScopes = original.grantedScopes;
066                this.scope = original.scope;
067                this.receivedAt = original.receivedAt;
068                this.safeParameters = original.safeParameters;
069                this.applicationData = Map.copyOf(applicationData);
070        }
071
072        @NonNull TokenResponse withApplicationData(@NonNull Map<@NonNull String, @NonNull String> value) {
073                return new TokenResponse(this, value);
074        }
075
076        /**
077         * Returns the raw access token.
078         *
079         * @return the token
080         * @since 1.0.0
081         */
082        public @NonNull AccessToken getAccessToken() { return this.accessToken; }
083
084        /**
085         * Returns a replacement refresh token when supplied. If absent, callers retain their previous token.
086         *
087         * @return the replacement
088         * @since 1.0.0
089         */
090        public @NonNull Optional<@NonNull RefreshToken> getRefreshToken() {
091                return Optional.ofNullable(this.refreshToken);
092        }
093
094        /**
095         * Returns the authorization server's scope member exactly when it supplied one. Use
096         * {@link #getGrantedScopes()} for the request-specific fallback when it was absent.
097         *
098         * @return the response's scope member
099         * @since 1.0.0
100         */
101        public @NonNull Optional<@NonNull String> getScope() { return Optional.ofNullable(this.scope); }
102
103        /**
104         * Returns granted scopes. When the response omitted scope, this request's scopes are used; no client-wide defaults
105         * are inferred for a refresh request that omitted scope.
106         *
107         * @return the scopes when known
108         * @since 1.0.0
109         */
110        public @NonNull Optional<@NonNull Set<@NonNull String>> getGrantedScopes() {
111                return Optional.ofNullable(this.grantedScopes);
112        }
113
114        /**
115         * Returns the access-token expiry, when supplied.
116         *
117         * @return expiry
118         * @since 1.0.0
119         */
120        public @NonNull Optional<@NonNull Instant> getExpiresAt() { return this.accessToken.getExpiresAt(); }
121
122        /**
123         * Returns the instant at which this token request began. Expiry is anchored to this instant.
124         *
125         * @return request start
126         * @since 1.0.0
127         */
128        public @NonNull Instant getReceivedAt() { return this.receivedAt; }
129
130        /**
131         * Returns the application data authenticated in the pending browser authorization, after code completion. It is
132         * empty for other grants. The application must still allowlist any value used as a redirect destination.
133         *
134         * @return immutable application data
135         * @since 1.0.0
136         */
137        public @NonNull Map<@NonNull String, @NonNull String> getApplicationData() {
138                return this.applicationData;
139        }
140
141        /**
142         * Returns one unknown non-token JSON member.
143         *
144         * @param name exact member name
145         * @return its value
146         * @since 1.0.0
147         */
148        public @NonNull Optional<@NonNull JsonValue> getParameter(@NonNull String name) {
149                return this.safeParameters.find(name);
150        }
151
152        /**
153         * Returns unknown non-token JSON members only.
154         *
155         * @return a safe JSON object
156         * @since 1.0.0
157         */
158        public @NonNull JsonObject toJsonObject() { return this.safeParameters; }
159
160        /**
161         * Redacts all tokens and parameters.
162         *
163         * @return a redacted description
164         * @since 1.0.0
165         */
166        @Override
167        public @NonNull String toString() { return "TokenResponse{tokens=<redacted>}"; }
168}