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}