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.server;
018
019import com.google.errorprone.annotations.CheckReturnValue;
020import org.jspecify.annotations.NonNull;
021import org.jspecify.annotations.Nullable;
022import javax.annotation.concurrent.Immutable;
023import javax.annotation.concurrent.NotThreadSafe;
024import java.net.URI;
025import java.util.List;
026import java.util.Map;
027import java.util.Optional;
028import java.util.Set;
029
030/**
031 * Immutable application-owned client registration. Identifiers and redirects retain their exact spelling.
032 * This configuration grants no user identity or permission. HTTP redirects are admitted only for the exact
033 * literal loopbacks 127.0.0.1/[::1] or localhost; their use still requires the server's separate explicit opt-ins.
034 * Introspection authority is independent of authorization-code scopes and requires confidential Basic verification.
035 * Carrier bounds admit the server's maximum configurable capacities; the server applies its configured limits.
036 * Security-field or configuration-version changes reject old interaction/code/refresh bindings but do not
037 * themselves revoke already-issued access tokens. Use trusted grant/subject/issuer management revocation
038 * when permanent invalidation is required; restoring an earlier binding can otherwise restore its use.
039 * Construction performs no callback or I/O.
040 *
041 * @author <a href="https://www.revetkn.com">Mark Allen</a>
042 * @since 1.0.0
043 */
044@Immutable
045public final class OAuthServerClientRegistration {
046        private final @NonNull String clientId;
047        private final @NonNull List<@NonNull URI> redirectUris;
048        private final @NonNull OAuthServerClientAuthentication authentication;
049        private final @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> allowedScopesByResource;
050        private final boolean refreshTokenPermitted;
051        private final boolean authorizationCodePermitted;
052        private final @NonNull Set<@NonNull String> introspectionResources;
053        private final @Nullable String clientName;
054        private final @NonNull String configurationVersion;
055        private OAuthServerClientRegistration(@NonNull Builder builder, @NonNull String version,
056                        @NonNull List<@NonNull URI> redirects,
057                        @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> resources) {
058                this.clientId = builder.clientId; this.redirectUris = List.copyOf(redirects); this.authentication = builder.authentication;
059                this.allowedScopesByResource = Map.copyOf(resources); this.refreshTokenPermitted = builder.refreshTokenPermitted;
060                this.authorizationCodePermitted = builder.authorizationCodePermitted;
061                this.introspectionResources = builder.introspectionResources; this.clientName = builder.clientName;
062                this.configurationVersion = version;
063        }
064        /**
065         * Starts a public-client registration permitting authorization codes and no refresh tokens.
066         * @param clientId the exact nonempty identifier, at most 4096 UTF-16 code units
067         * @return the builder
068         * @throws NullPointerException if clientId is null
069         * @throws IllegalArgumentException if clientId is invalid
070         * @since 1.0.0
071         */
072        @CheckReturnValue
073        public static @NonNull Builder withClientId(@NonNull String clientId) { return new Builder(clientId); }
074        /**
075         * Returns the exact client identifier.
076         * @return the configured value
077         * @since 1.0.0
078         */
079        public @NonNull String getClientId() { return this.clientId; }
080        /**
081         * Returns an immutable redirect list in configured order; URI spelling is unchanged.
082         * @return the configured value
083         * @since 1.0.0
084         */
085        public @NonNull List<@NonNull URI> getRedirectUris() { return this.redirectUris; }
086        /**
087         * Returns the trusted authentication policy.
088         * @return the configured value
089         * @since 1.0.0
090         */
091        public @NonNull OAuthServerClientAuthentication getAuthentication() { return this.authentication; }
092        /**
093         * Returns the immutable exact resource/scope registry.
094         * @return the configured value
095         * @since 1.0.0
096         */
097        public @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> getAllowedScopesByResource() { return this.allowedScopesByResource; }
098        /**
099         * Returns whether this client permits refresh, subject to server and application approval.
100         * @return the configured value
101         * @since 1.0.0
102         */
103        public @NonNull Boolean isRefreshTokenPermitted() { return this.refreshTokenPermitted; }
104        /**
105         * Returns whether this client may request authorization codes.
106         * @return the configured value
107         * @since 1.0.0
108         */
109        public @NonNull Boolean isAuthorizationCodePermitted() { return this.authorizationCodePermitted; }
110        /**
111         * Returns the explicit resources whose tokens this client may introspect.
112         * @return the configured value
113         * @since 1.0.0
114         */
115        public @NonNull Set<@NonNull String> getIntrospectionResources() { return this.introspectionResources; }
116        /**
117         * Returns optional display text, which applications must escape before rendering.
118         * @return the configured value
119         * @since 1.0.0
120         */
121        public @NonNull Optional<@NonNull String> getClientName() { return Optional.ofNullable(this.clientName); }
122        /**
123         * Returns the application version binding for rechecking changed configuration.
124         * @return the configured value
125         * @since 1.0.0
126         */
127        public @NonNull String getConfigurationVersion() { return this.configurationVersion; }
128        /**
129         * Redacts identifiers, callbacks and registration values from diagnostics.
130         * @return a fixed description
131         * @since 1.0.0
132         */
133        @Override public @NonNull String toString() { return "OAuthServerClientRegistration{configuration=<redacted>}"; }
134        /**
135         * Replacing, snapshotting registration builder. Null setters reset defaults or clear required values.
136         * @author <a href="https://www.revetkn.com">Mark Allen</a>
137         * @since 1.0.0
138         */
139        @NotThreadSafe
140        @CheckReturnValue
141        public static final class Builder {
142                private final @NonNull String clientId;
143                private @Nullable List<@NonNull URI> redirectUris;
144                private @NonNull OAuthServerClientAuthentication authentication = OAuthServerClientAuthentication.publicClientInstance();
145                private @Nullable Map<@NonNull String, @NonNull Set<@NonNull String>> allowedScopesByResource;
146                private boolean refreshTokenPermitted;
147                private boolean authorizationCodePermitted = true;
148                private @NonNull Set<@NonNull String> introspectionResources = Set.of();
149                private @Nullable String clientName;
150                private @Nullable String configurationVersion;
151                private Builder(@NonNull String clientId) {
152                        this.clientId = OAuthServerConfiguration.text(clientId, OAuthServerConfiguration.MAXIMUM_CLIENT_ID_LENGTH);
153                }
154                /**
155                 * Snapshots at most 64 distinct exact redirects. Null clears the required browser setting.
156                 * @param value the replacement value, or null to reset
157                 * @return this builder
158                 * @since 1.0.0
159                 */
160                public @NonNull Builder redirectUris(@Nullable List<@NonNull URI> value) {
161                        this.redirectUris = value == null || (value.isEmpty() && !this.authorizationCodePermitted) ? null : OAuthServerConfiguration.redirects(value);
162                        return this;
163                }
164                /**
165                 * Replaces authentication; null resets to public authentication.
166                 * @param value the replacement value, or null to reset
167                 * @return this builder
168                 * @since 1.0.0
169                 */
170                public @NonNull Builder authentication(@Nullable OAuthServerClientAuthentication value) {
171                        this.authentication = value == null ? OAuthServerClientAuthentication.publicClientInstance() : value;
172                        return this;
173                }
174                /**
175                 * Snapshots exact resource/scopes. Null clears the required browser setting; empty scope sets are allowed.
176                 * @param value the replacement value, or null to reset
177                 * @return this builder
178                 * @since 1.0.0
179                 */
180                public @NonNull Builder allowedScopesByResource(@Nullable Map<@NonNull String, @NonNull Set<@NonNull String>> value) {
181                        this.allowedScopesByResource = value == null || (value.isEmpty() && !this.authorizationCodePermitted) ? null
182                                        : OAuthServerConfiguration.resources(value, OAuthServerConfiguration.MAXIMUM_RESOURCES);
183                        return this;
184                }
185                /**
186                 * Sets refresh permission; null resets to false.
187                 * @param value the replacement value, or null to reset
188                 * @return this builder
189                 * @since 1.0.0
190                 */
191                public @NonNull Builder refreshTokenPermitted(@Nullable Boolean value) {
192                        this.refreshTokenPermitted = Boolean.TRUE.equals(value);
193                        return this;
194                }
195                /**
196                 * Sets code permission; null resets to true. False clears browser redirects/scopes; re-enabling requires replacement.
197                 * @param value the replacement value, or null to reset
198                 * @return this builder
199                 * @since 1.0.0
200                 */
201                public @NonNull Builder authorizationCodePermitted(@Nullable Boolean value) {
202                        this.authorizationCodePermitted = value == null || value;
203                        if (!this.authorizationCodePermitted) { this.redirectUris = null; this.allowedScopesByResource = null; }
204                        return this;
205                }
206                /**
207                 * Snapshots explicit introspection authority; null resets to empty. Confidential authentication is required at build.
208                 * @param value the replacement value, or null to reset
209                 * @return this builder
210                 * @since 1.0.0
211                 */
212                public @NonNull Builder introspectionResources(@Nullable Set<@NonNull String> value) {
213                        this.introspectionResources = value == null ? Set.of() : OAuthServerConfiguration.introspectionResources(value);
214                        return this;
215                }
216                /**
217                 * Sets optional display text, at most 4096 UTF-16 code units; null clears it.
218                 * @param value the replacement value, or null to reset
219                 * @return this builder
220                 * @since 1.0.0
221                 */
222                public @NonNull Builder clientName(@Nullable String value) {
223                        this.clientName = value == null ? null : OAuthServerConfiguration.text(value, OAuthServerConfiguration.MAXIMUM_TEXT_LENGTH);
224                        return this;
225                }
226                /**
227                 * Sets the required nonempty application configuration version, at most 4096 UTF-16 code units; null clears it.
228                 * Change this value when secret-verifier or key semantics change; callbacks are not fingerprinted.
229                 * Version equality binds existing interactions and grants. It is not a monotonic revocation epoch;
230                 * rolling it back can restore old bindings unless management revocation also invalidated them.
231                 * @param value the replacement value, or null to reset
232                 * @return this builder
233                 * @since 1.0.0
234                 */
235                public @NonNull Builder configurationVersion(@Nullable String value) {
236                        this.configurationVersion = value == null ? null : OAuthServerConfiguration.text(value, OAuthServerConfiguration.MAXIMUM_TEXT_LENGTH);
237                        return this;
238                }
239                /**
240                 * Builds without invoking application callbacks or performing I/O.
241                 * @return the immutable registration
242                 * @throws IllegalStateException if version or required browser configuration is missing
243                 * @throws IllegalArgumentException if introspection authority has public authentication
244                 * @since 1.0.0
245                 */
246                public @NonNull OAuthServerClientRegistration build() {
247                        String version = this.configurationVersion;
248                        if (version == null) throw new IllegalStateException("A client configuration version is required.");
249                        List<URI> redirects = this.redirectUris;
250                        Map<String, Set<String>> resources = this.allowedScopesByResource;
251                        if (this.authorizationCodePermitted && (redirects == null || resources == null))
252                                throw new IllegalStateException("Authorization-code client configuration is required.");
253                        if (!this.introspectionResources.isEmpty() && !this.authentication.isConfidential()) throw OAuthServerConfiguration.invalid();
254                        return new OAuthServerClientRegistration(this, version, !this.authorizationCodePermitted || redirects == null ? List.of() : redirects,
255                                        !this.authorizationCodePermitted || resources == null ? Map.of() : resources);
256                }
257                /**
258                 * Redacts mutable registration configuration from diagnostics.
259                 * @return a fixed description
260                 * @since 1.0.0
261                 */
262                @Override public @NonNull String toString() { return "OAuthServerClientRegistration.Builder{configuration=<redacted>}"; }
263        }
264}