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.internal.Limits;
020import com.revetsec.internal.encoding.EncodingException;
021import com.revetsec.internal.encoding.StrictUtf8;
022import com.revetsec.internal.json.JsonCodec;
023import com.revetsec.internal.json.JsonLimits;
024import com.revetsec.internal.json.JsonParseException;
025import com.revetsec.json.JsonArray;
026import com.revetsec.json.JsonBoolean;
027import com.revetsec.json.JsonObject;
028import com.revetsec.json.JsonString;
029import com.revetsec.json.JsonValue;
030import org.jspecify.annotations.NonNull;
031import org.jspecify.annotations.Nullable;
032
033import com.google.errorprone.annotations.CheckReturnValue;
034import javax.annotation.concurrent.Immutable;
035import javax.annotation.concurrent.NotThreadSafe;
036import java.net.URI;
037import java.util.LinkedHashSet;
038import java.util.Map;
039import java.util.Optional;
040import java.util.Set;
041
042import static java.util.Objects.requireNonNull;
043
044/**
045 * Known authorization-server metadata. A remote document's issuer must match the configured issuer exactly. A
046 * manual instance is application configuration, not proof from a remote server. The {@link OAuthClient} builder
047 * checks every known requestable endpoint against its outbound URI policy before use.
048 *
049 * @author <a href="https://www.revetkn.com">Mark Allen</a>
050 * @since 1.0.0
051 */
052@Immutable
053public final class AuthorizationServerMetadata {
054        private final @NonNull String issuer;
055        private final @NonNull URI authorizationEndpoint;
056        private final @NonNull URI tokenEndpoint;
057        private final @Nullable URI jwksUri;
058        private final @Nullable URI introspectionEndpoint;
059        private final @Nullable URI revocationEndpoint;
060        private final @Nullable Set<@NonNull String> codeChallengeMethodsSupported;
061        private final @Nullable Set<@NonNull String> tokenEndpointAuthMethodsSupported;
062        private final @Nullable Set<@NonNull String> introspectionEndpointAuthMethodsSupported;
063        private final @Nullable Set<@NonNull String> tokenEndpointAuthSigningAlgValuesSupported;
064        private final @Nullable Set<@NonNull String> revocationEndpointAuthMethodsSupported;
065        private final @Nullable Set<@NonNull String> revocationEndpointAuthSigningAlgValuesSupported;
066        private final @Nullable Set<@NonNull String> introspectionEndpointAuthSigningAlgValuesSupported;
067        private final boolean authorizationResponseIssuerSupported;
068        private final boolean remotelyDiscovered;
069
070        private AuthorizationServerMetadata(@NonNull Builder builder, boolean remotelyDiscovered) {
071                this.issuer = builder.issuer;
072                this.authorizationEndpoint = requireNonNull(builder.authorizationEndpoint);
073                this.tokenEndpoint = requireNonNull(builder.tokenEndpoint);
074                this.jwksUri = builder.jwksUri;
075                this.introspectionEndpoint = builder.introspectionEndpoint;
076                this.revocationEndpoint = builder.revocationEndpoint;
077                this.codeChallengeMethodsSupported = builder.codeChallengeMethodsSupported;
078                this.tokenEndpointAuthMethodsSupported = builder.tokenEndpointAuthMethodsSupported;
079                this.introspectionEndpointAuthMethodsSupported = builder.introspectionEndpointAuthMethodsSupported;
080                this.tokenEndpointAuthSigningAlgValuesSupported = builder.tokenEndpointAuthSigningAlgValuesSupported;
081                this.revocationEndpointAuthMethodsSupported = builder.revocationEndpointAuthMethodsSupported;
082                this.revocationEndpointAuthSigningAlgValuesSupported = builder.revocationEndpointAuthSigningAlgValuesSupported;
083                this.introspectionEndpointAuthSigningAlgValuesSupported = builder.introspectionEndpointAuthSigningAlgValuesSupported;
084                this.authorizationResponseIssuerSupported = builder.authorizationResponseIssuerSupported;
085                this.remotelyDiscovered = remotelyDiscovered;
086        }
087
088        /**
089         * Starts a manual metadata builder for an AS without discovery.
090         *
091         * @param issuer the deployment's exact issuer identifier
092         * @return the builder
093         * @since 1.0.0
094         */
095        public static @NonNull Builder withIssuer(@NonNull String issuer) {
096                return new Builder(issuer);
097        }
098
099        /**
100         * Parses bounded metadata and reports a fixed document or issuer rejection as a value.
101         * @param expectedIssuer configured trust issuer
102         * @param json metadata JSON text
103         * @return the metadata parsing outcome
104         * @throws NullPointerException if an argument is null
105         * @since 1.0.0
106         */
107        @com.google.errorprone.annotations.CheckReturnValue
108        public static @NonNull AuthorizationServerMetadataParseResult fromJsonResult(@NonNull String expectedIssuer,
109                        @NonNull String json) {
110                requireNonNull(expectedIssuer); requireNonNull(json);
111                withIssuer(expectedIssuer);
112                try { return AuthorizationServerMetadataParseResult.succeeded(parse(expectedIssuer, json)); }
113                catch (OAuthException rejected) {
114                        if (rejected.getReason() != OAuthException.Reason.DOCUMENT_MALFORMED
115                                        && rejected.getReason() != OAuthException.Reason.ISSUER_MISMATCH) throw rejected;
116                        return AuthorizationServerMetadataParseResult.rejected(rejected.getReason());
117                }
118        }
119
120        /**
121         * Parses a strict, bounded metadata JSON document and compares its issuer exactly.
122         *
123         * @param expectedIssuer the configured issuer
124         * @param json the JSON text
125         * @return the metadata
126         * @since 1.0.0
127         */
128        private static @NonNull AuthorizationServerMetadata parse(@NonNull String expectedIssuer,
129                        @NonNull String json) {
130                requireNonNull(expectedIssuer);
131                requireNonNull(json);
132                try {
133                        byte[] bytes = StrictUtf8.encode(json);
134                        JsonValue parsed = JsonCodec.parse(bytes,
135                                        JsonLimits.protocolDocument(Limits.HTTP_RESPONSE_BODY_SIZE.getDefaultIntValue()));
136                        if (!(parsed instanceof JsonObject object))
137                                throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED);
138                        Map<String, JsonValue> members = object.getMembers();
139                        String actualIssuer = requiredString(members, "issuer");
140                        if (!expectedIssuer.equals(actualIssuer))
141                                throw OAuthValidationException.fromReason(OAuthException.Reason.ISSUER_MISMATCH);
142                        Builder builder = withIssuer(expectedIssuer)
143                                        .authorizationEndpoint(URI.create(requiredString(members, "authorization_endpoint")))
144                                        .tokenEndpoint(URI.create(requiredString(members, "token_endpoint")));
145                        if (members.containsKey("jwks_uri")) builder = builder.jwksUri(URI.create(requiredString(members, "jwks_uri")));
146                        if (members.containsKey("introspection_endpoint")) builder = builder.introspectionEndpoint(URI.create(requiredString(members, "introspection_endpoint")));
147                        if (members.containsKey("revocation_endpoint"))
148                                builder = builder.revocationEndpoint(URI.create(requiredString(members, "revocation_endpoint")));
149                        if (members.containsKey("code_challenge_methods_supported"))
150                                builder = builder.codeChallengeMethodsSupported(stringSet(members.get("code_challenge_methods_supported")));
151                        if (members.containsKey("token_endpoint_auth_methods_supported"))
152                                builder = builder.tokenEndpointAuthMethodsSupported(stringSet(members.get("token_endpoint_auth_methods_supported")));
153                        if (members.containsKey("introspection_endpoint_auth_methods_supported")) builder = builder.introspectionEndpointAuthMethodsSupported(stringSet(members.get("introspection_endpoint_auth_methods_supported")));
154                        if (members.containsKey("token_endpoint_auth_signing_alg_values_supported")) builder = builder.tokenEndpointAuthSigningAlgValuesSupported(stringSet(members.get("token_endpoint_auth_signing_alg_values_supported")));
155                        if (members.containsKey("revocation_endpoint_auth_methods_supported")) builder = builder.revocationEndpointAuthMethodsSupported(stringSet(members.get("revocation_endpoint_auth_methods_supported")));
156                        if (members.containsKey("revocation_endpoint_auth_signing_alg_values_supported")) builder = builder.revocationEndpointAuthSigningAlgValuesSupported(stringSet(members.get("revocation_endpoint_auth_signing_alg_values_supported")));
157                        if (members.containsKey("introspection_endpoint_auth_signing_alg_values_supported")) builder = builder.introspectionEndpointAuthSigningAlgValuesSupported(stringSet(members.get("introspection_endpoint_auth_signing_alg_values_supported")));
158                        if (members.containsKey("authorization_response_iss_parameter_supported")) {
159                                JsonValue value = members.get("authorization_response_iss_parameter_supported");
160                                if (!(value instanceof JsonBoolean booleanValue))
161                                        throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED);
162                                builder = builder.authorizationResponseIssuerSupported(booleanValue.getValue());
163                        }
164                        return builder.buildDiscovered();
165                } catch (EncodingException | JsonParseException | IllegalArgumentException exception) {
166                        throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED);
167                }
168        }
169
170        private static @NonNull String requiredString(@NonNull Map<@NonNull String, @NonNull JsonValue> members, @NonNull String name) {
171                JsonValue value = members.get(name);
172                if (!(value instanceof JsonString text) || text.getValue().isEmpty())
173                        throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED);
174                return text.getValue();
175        }
176
177        private static @NonNull Set<@NonNull String> stringSet(@NonNull JsonValue value) {
178                if (!(value instanceof JsonArray array))
179                        throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED);
180                Set<String> strings = new LinkedHashSet<>();
181                for (JsonValue element : array.getElements()) {
182                        if (!(element instanceof JsonString text) || text.getValue().isEmpty()
183                                        || !strings.add(text.getValue()))
184                                throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED);
185                }
186                return Set.copyOf(strings);
187        }
188
189        /**
190         * Returns the exact issuer identifier.
191         *
192         * @return issuer
193         * @since 1.0.0
194         */
195        public @NonNull String getIssuer() { return this.issuer; }
196
197        /**
198         * Returns the authorization endpoint.
199         *
200         * @return endpoint
201         * @since 1.0.0
202         */
203        public @NonNull URI getAuthorizationEndpoint() { return this.authorizationEndpoint; }
204
205        /**
206         * Returns the token endpoint.
207         *
208         * @return endpoint
209         * @since 1.0.0
210         */
211        public @NonNull URI getTokenEndpoint() { return this.tokenEndpoint; }
212
213    /** Returns the optional jwks_uri.
214     * @return endpoint when configured or advertised
215     * @since 1.0.0
216     */
217    public @NonNull Optional<@NonNull URI> getJwksUri() { return Optional.ofNullable(this.jwksUri); }
218    /** Returns the optional introspection_endpoint.
219     * @return endpoint when configured or advertised
220     * @since 1.0.0
221     */
222    public @NonNull Optional<@NonNull URI> getIntrospectionEndpoint() { return Optional.ofNullable(this.introspectionEndpoint); }
223        /**
224         * Returns the revocation endpoint, when one was advertised or configured.
225         *
226         * @return endpoint
227         * @since 1.0.0
228         */
229        public @NonNull Optional<@NonNull URI> getRevocationEndpoint() {
230                return Optional.ofNullable(this.revocationEndpoint);
231        }
232
233        /**
234         * Returns advertised PKCE methods, or empty when the metadata field was absent.
235         *
236         * @return methods if advertised
237         * @since 1.0.0
238         */
239        public @NonNull Optional<@NonNull Set<@NonNull String>> getCodeChallengeMethodsSupported() {
240                return Optional.ofNullable(this.codeChallengeMethodsSupported);
241        }
242
243        /**
244         * Returns advertised token endpoint client authentication methods, or empty when absent.
245         *
246         * @return methods if advertised
247         * @since 1.0.0
248         */
249        public @NonNull Optional<@NonNull Set<@NonNull String>> getTokenEndpointAuthMethodsSupported() {
250                return Optional.ofNullable(this.tokenEndpointAuthMethodsSupported);
251        }
252
253    /** Returns introspection endpoint methods separately from token endpoint methods.
254     * @return advertised methods, or empty when absent
255     * @since 1.0.0
256     */
257    public @NonNull Optional<@NonNull Set<@NonNull String>> getIntrospectionEndpointAuthMethodsSupported() { return Optional.ofNullable(this.introspectionEndpointAuthMethodsSupported); }
258        /**
259         * Returns the optional token_endpoint_auth_signing_alg_values_supported role policy, retaining absent versus empty and unknown names.
260         * @return advertised or configured names when present
261         * @since 1.0.0
262         */
263        public @NonNull Optional<@NonNull Set<@NonNull String>> getTokenEndpointAuthSigningAlgValuesSupported() { return Optional.ofNullable(this.tokenEndpointAuthSigningAlgValuesSupported); }
264        /**
265         * Returns the optional revocation_endpoint_auth_methods_supported role policy, retaining absent versus empty and unknown names.
266         * @return advertised or configured names when present
267         * @since 1.0.0
268         */
269        public @NonNull Optional<@NonNull Set<@NonNull String>> getRevocationEndpointAuthMethodsSupported() { return Optional.ofNullable(this.revocationEndpointAuthMethodsSupported); }
270        /**
271         * Returns the optional revocation_endpoint_auth_signing_alg_values_supported role policy, retaining absent versus empty and unknown names.
272         * @return advertised or configured names when present
273         * @since 1.0.0
274         */
275        public @NonNull Optional<@NonNull Set<@NonNull String>> getRevocationEndpointAuthSigningAlgValuesSupported() { return Optional.ofNullable(this.revocationEndpointAuthSigningAlgValuesSupported); }
276        /**
277         * Returns the optional introspection_endpoint_auth_signing_alg_values_supported role policy, retaining absent versus empty and unknown names.
278         * @return advertised or configured names when present
279         * @since 1.0.0
280         */
281        public @NonNull Optional<@NonNull Set<@NonNull String>> getIntrospectionEndpointAuthSigningAlgValuesSupported() { return Optional.ofNullable(this.introspectionEndpointAuthSigningAlgValuesSupported); }
282        /**
283         * Returns whether metadata advertised RFC 9207 issuer response support.
284         *
285         * @return whether support was advertised
286         * @since 1.0.0
287         */
288        public @NonNull Boolean isAuthorizationResponseIssuerSupported() {
289                return this.authorizationResponseIssuerSupported;
290        }
291
292        /**
293         * Returns whether this instance came from a checked remote metadata document.
294         *
295         * @return whether discovered
296         * @since 1.0.0
297         */
298        public @NonNull Boolean isRemotelyDiscovered() { return this.remotelyDiscovered; }
299
300        /**
301         * Builds manually configured metadata.
302         *
303         * @author <a href="https://www.revetkn.com">Mark Allen</a>
304         * @since 1.0.0
305         */
306        @NotThreadSafe
307        @CheckReturnValue
308        public static final class Builder {
309                private final @NonNull String issuer;
310                private @Nullable URI authorizationEndpoint;
311                private @Nullable URI tokenEndpoint;
312                private @Nullable URI jwksUri;
313                private @Nullable URI introspectionEndpoint;
314                private @Nullable URI revocationEndpoint;
315                private @Nullable Set<@NonNull String> codeChallengeMethodsSupported;
316                private @Nullable Set<@NonNull String> tokenEndpointAuthMethodsSupported;
317                private @Nullable Set<@NonNull String> introspectionEndpointAuthMethodsSupported;
318                private boolean authorizationResponseIssuerSupported;
319
320                private @Nullable Set<@NonNull String> tokenEndpointAuthSigningAlgValuesSupported;
321
322                /**
323                 * Replaces the complete token_endpoint_auth_signing_alg_values_supported role policy, preserving an empty set.
324                 * @param value names, or null to restore absence
325                 * @return this builder
326                 * @since 1.0.0
327                 */
328                public @NonNull Builder tokenEndpointAuthSigningAlgValuesSupported(@Nullable Set<@NonNull String> value) {
329                        this.tokenEndpointAuthSigningAlgValuesSupported = value == null ? null : AccessTokenClaims.names(value, false); return this;
330                }
331
332                private @Nullable Set<@NonNull String> revocationEndpointAuthMethodsSupported;
333
334                /**
335                 * Replaces the complete revocation_endpoint_auth_methods_supported role policy, preserving an empty set.
336                 * @param value names, or null to restore absence
337                 * @return this builder
338                 * @since 1.0.0
339                 */
340                public @NonNull Builder revocationEndpointAuthMethodsSupported(@Nullable Set<@NonNull String> value) {
341                        this.revocationEndpointAuthMethodsSupported = value == null ? null : AccessTokenClaims.names(value, false); return this;
342                }
343
344                private @Nullable Set<@NonNull String> revocationEndpointAuthSigningAlgValuesSupported;
345
346                /**
347                 * Replaces the complete revocation_endpoint_auth_signing_alg_values_supported role policy, preserving an empty set.
348                 * @param value names, or null to restore absence
349                 * @return this builder
350                 * @since 1.0.0
351                 */
352                public @NonNull Builder revocationEndpointAuthSigningAlgValuesSupported(@Nullable Set<@NonNull String> value) {
353                        this.revocationEndpointAuthSigningAlgValuesSupported = value == null ? null : AccessTokenClaims.names(value, false); return this;
354                }
355
356                private @Nullable Set<@NonNull String> introspectionEndpointAuthSigningAlgValuesSupported;
357
358                /**
359                 * Replaces the complete introspection_endpoint_auth_signing_alg_values_supported role policy, preserving an empty set.
360                 * @param value names, or null to restore absence
361                 * @return this builder
362                 * @since 1.0.0
363                 */
364                public @NonNull Builder introspectionEndpointAuthSigningAlgValuesSupported(@Nullable Set<@NonNull String> value) {
365                        this.introspectionEndpointAuthSigningAlgValuesSupported = value == null ? null : AccessTokenClaims.names(value, false); return this;
366                }
367
368                private Builder(@NonNull String issuer) {
369                        if (requireNonNull(issuer).isEmpty())
370                                throw new IllegalArgumentException("An issuer must not be empty.");
371                        this.issuer = issuer;
372                }
373
374                /**
375                 * Sets the authorization endpoint.
376                 *
377                 * @param value endpoint, or null to restore the unset default
378                 * @return this builder
379                 * @since 1.0.0
380                 */
381                public @NonNull Builder authorizationEndpoint(@Nullable URI value) {
382                        this.authorizationEndpoint = value;
383                        return this;
384                }
385
386                /**
387                 * Sets the token endpoint.
388                 *
389                 * @param value endpoint, or null to restore the unset default
390                 * @return this builder
391                 * @since 1.0.0
392                 */
393                public @NonNull Builder tokenEndpoint(@Nullable URI value) {
394                        this.tokenEndpoint = value;
395                        return this;
396                }
397
398        /** Sets optional jwks_uri.
399         * @param value endpoint, or null to omit
400         * @return this builder
401         * @since 1.0.0
402         */
403        public @NonNull Builder jwksUri(@Nullable URI value) { this.jwksUri = value; return this; }
404        /** Sets optional introspection_endpoint.
405         * @param value endpoint, or null to omit
406         * @return this builder
407         * @since 1.0.0
408         */
409        public @NonNull Builder introspectionEndpoint(@Nullable URI value) { this.introspectionEndpoint = value; return this; }
410                /**
411                 * Sets an optional revocation endpoint.
412                 *
413                 * @param value endpoint, or null to restore the unset default, or null to omit
414                 * @return this builder
415                 * @since 1.0.0
416                 */
417                public @NonNull Builder revocationEndpoint(@Nullable URI value) {
418                        this.revocationEndpoint = value;
419                        return this;
420                }
421
422                /**
423                 * Sets the complete advertised PKCE method set. Null denotes absent metadata.
424                 *
425                 * @param value methods, or null
426                 * @return this builder
427                 * @since 1.0.0
428                 */
429                public @NonNull Builder codeChallengeMethodsSupported(@Nullable Set<@NonNull String> value) {
430                        this.codeChallengeMethodsSupported = value == null ? null : Set.copyOf(value);
431                        return this;
432                }
433
434                /**
435                 * Sets the complete advertised client authentication method set. Null denotes absent metadata.
436                 *
437                 * @param value methods, or null
438                 * @return this builder
439                 * @since 1.0.0
440                 */
441                public @NonNull Builder tokenEndpointAuthMethodsSupported(@Nullable Set<@NonNull String> value) {
442                        this.tokenEndpointAuthMethodsSupported = value == null ? null : Set.copyOf(value);
443                        return this;
444                }
445
446        /** Sets introspection endpoint client authentication methods.
447         * @param value methods, or null to restore absence
448         * @return this builder
449         * @since 1.0.0
450         */
451        public @NonNull Builder introspectionEndpointAuthMethodsSupported(@Nullable Set<@NonNull String> value) { this.introspectionEndpointAuthMethodsSupported = value == null ? null : AccessTokenClaims.names(value, false); return this; }
452                /**
453                 * Sets whether RFC 9207 issuer response support was advertised.
454                 *
455                 * @param value whether advertised, or null which restores the default
456                 * @return this builder
457                 * @since 1.0.0
458                 */
459                public @NonNull Builder authorizationResponseIssuerSupported(@Nullable Boolean value) {
460                        this.authorizationResponseIssuerSupported = Boolean.TRUE.equals(value);
461                        return this;
462                }
463
464                /**
465                 * Builds manually configured metadata.
466                 *
467                 * @return metadata
468                 * @since 1.0.0
469                 */
470                public @NonNull AuthorizationServerMetadata build() {
471                        if (this.authorizationEndpoint == null || this.tokenEndpoint == null)
472                                throw new IllegalStateException("Authorization and token endpoints are required.");
473                        return new AuthorizationServerMetadata(this, false);
474                }
475
476                private @NonNull AuthorizationServerMetadata buildDiscovered() {
477                        if (this.authorizationEndpoint == null || this.tokenEndpoint == null)
478                                throw OAuthResponseException.fromReason(OAuthException.Reason.DOCUMENT_MALFORMED);
479                        return new AuthorizationServerMetadata(this, true);
480                }
481        }
482}