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}