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 org.jspecify.annotations.NonNull; 020import org.jspecify.annotations.Nullable; 021 022import com.google.errorprone.annotations.CheckReturnValue; 023import javax.annotation.concurrent.Immutable; 024import javax.annotation.concurrent.NotThreadSafe; 025import java.net.URI; 026import java.util.List; 027import java.util.Map; 028import java.util.Optional; 029import java.util.Set; 030 031 032/** 033 * Per-authorization options. Scope and resource setters replace the complete list for this request; they never add 034 * silently to a client's defaults. Application data is authenticated as pending state but is never a safe redirect 035 * destination without the application's own validation. 036 * 037 * @author <a href="https://www.revetkn.com">Mark Allen</a> 038 * @since 1.0.0 039 */ 040@Immutable 041public final class AuthorizationRequestOptions { 042 private static final Set<String> RESERVED = Set.of("response_type", "client_id", "redirect_uri", "state", 043 "nonce", "code_challenge", "code_challenge_method", "scope", "resource", "response_mode", "prompt", 044 "max_age", "login_hint", "acr_values", "request", "request_uri", "dpop_jkt", "authorization_details"); 045 private final @NonNull Set<@NonNull String> scopes; 046 private final boolean scopesOverridden; 047 private final @NonNull List<@NonNull URI> resources; 048 private final boolean resourcesOverridden; 049 private final @NonNull ResponseMode responseMode; 050 private final @Nullable String prompt; 051 private final @Nullable String loginHint; 052 private final @NonNull Map<@NonNull String, @NonNull String> applicationData; 053 private final @NonNull Map<@NonNull String, @NonNull String> additionalParameters; 054 055 private AuthorizationRequestOptions(@NonNull Builder builder) { 056 this.scopes = Set.copyOf(builder.scopes); 057 this.scopesOverridden = builder.scopesOverridden; 058 this.resources = List.copyOf(builder.resources); 059 this.resourcesOverridden = builder.resourcesOverridden; 060 this.responseMode = builder.responseMode; 061 this.prompt = builder.prompt; 062 this.loginHint = builder.loginHint; 063 this.applicationData = Map.copyOf(builder.applicationData); 064 this.additionalParameters = Map.copyOf(builder.additionalParameters); 065 } 066 067 /** 068 * Starts a request with query callback delivery and no overrides. 069 * 070 * @return the builder 071 * @since 1.0.0 072 */ 073 public static @NonNull Builder builder() { 074 return new Builder(); 075 } 076 077 /** 078 * Returns the complete scope override, empty when no scopes were requested. 079 * 080 * @return the scopes 081 * @since 1.0.0 082 */ 083 public @NonNull Set<@NonNull String> getScopes() { 084 return this.scopes; 085 } 086 087 boolean scopesOverridden() { return this.scopesOverridden; } 088 boolean resourcesOverridden() { return this.resourcesOverridden; } 089 090 /** 091 * Returns ordered RFC 8707 resource indicators. 092 * 093 * @return the resources 094 * @since 1.0.0 095 */ 096 public @NonNull List<@NonNull URI> getResources() { 097 return this.resources; 098 } 099 100 /** 101 * Returns the trusted callback delivery mode requested for this flow. 102 * 103 * @return the mode 104 * @since 1.0.0 105 */ 106 public @NonNull ResponseMode getResponseMode() { 107 return this.responseMode; 108 } 109 110 /** 111 * Returns the requested prompt, if any. 112 * 113 * @return the prompt 114 * @since 1.0.0 115 */ 116 public @NonNull Optional<@NonNull String> getPrompt() { 117 return Optional.ofNullable(this.prompt); 118 } 119 120 /** 121 * Returns the login hint, if any. Treat it as user data when logging. 122 * 123 * @return the login hint 124 * @since 1.0.0 125 */ 126 public @NonNull Optional<@NonNull String> getLoginHint() { 127 return Optional.ofNullable(this.loginHint); 128 } 129 130 /** 131 * Returns application data to authenticate in pending state. 132 * 133 * @return the data 134 * @since 1.0.0 135 */ 136 public @NonNull Map<@NonNull String, @NonNull String> getApplicationData() { 137 return this.applicationData; 138 } 139 140 /** 141 * Returns additional nonreserved authorization parameters. 142 * 143 * @return the parameters 144 * @since 1.0.0 145 */ 146 public @NonNull Map<@NonNull String, @NonNull String> getAdditionalParameters() { 147 return this.additionalParameters; 148 } 149 150 /** 151 * The trusted callback delivery mode. 152 * 153 * @author <a href="https://www.revetkn.com">Mark Allen</a> 154 * @since 1.0.0 155 */ 156 @Immutable 157 public enum ResponseMode { 158 /** URL query response, normally delivered by GET. */ 159 QUERY, 160 /** UTF-8 form body response, delivered by POST. */ 161 FORM_POST 162 } 163 164 /** 165 * Mutable request-option builder. 166 * 167 * @author <a href="https://www.revetkn.com">Mark Allen</a> 168 * @since 1.0.0 169 */ 170 @NotThreadSafe 171 @CheckReturnValue 172 public static final class Builder { 173 private @NonNull Set<@NonNull String> scopes = Set.of(); 174 private boolean scopesOverridden; 175 private @NonNull List<@NonNull URI> resources = List.of(); 176 private boolean resourcesOverridden; 177 private @NonNull ResponseMode responseMode = ResponseMode.QUERY; 178 private @Nullable String prompt; 179 private @Nullable String loginHint; 180 private @NonNull Map<@NonNull String, @NonNull String> applicationData = Map.of(); 181 private @NonNull Map<@NonNull String, @NonNull String> additionalParameters = Map.of(); 182 183 private Builder() { 184 } 185 186 /** 187 * Replaces the complete requested scope set. 188 * 189 * @param value scopes, or null which restores inheritance 190 * @return this builder 191 * @since 1.0.0 192 */ 193 public @NonNull Builder scopes(@Nullable Set<@NonNull String> value) { 194 this.scopes = value == null ? Set.of() : Set.copyOf(value); 195 this.scopesOverridden = value != null; 196 for (String scope : this.scopes) 197 if (scope.isEmpty() || scope.chars().anyMatch(c -> c <= 0x20 || c == 0x22 || c == 0x5C || c >= 0x7F)) 198 throw new IllegalArgumentException("A scope contains invalid characters."); 199 return this; 200 } 201 202 /** 203 * Replaces the complete ordered resource list. 204 * 205 * @param value resources, or null which restores inheritance 206 * @return this builder 207 * @since 1.0.0 208 */ 209 public @NonNull Builder resources(@Nullable List<@NonNull URI> value) { 210 this.resources = value == null ? List.of() : List.copyOf(value); 211 this.resourcesOverridden = value != null; 212 for (URI resource : this.resources) 213 if (!resource.isAbsolute() || resource.getFragment() != null) 214 throw new IllegalArgumentException("A resource indicator must be absolute and fragment-free."); 215 return this; 216 } 217 218 /** 219 * Sets the requested callback delivery mode. 220 * 221 * @param value the mode, or null which restores the default 222 * @return this builder 223 * @since 1.0.0 224 */ 225 public @NonNull Builder responseMode(@Nullable ResponseMode value) { 226 this.responseMode = value == null ? ResponseMode.QUERY : value; 227 return this; 228 } 229 230 /** 231 * Sets an optional prompt. 232 * 233 * @param value the prompt, or null to omit 234 * @return this builder 235 * @since 1.0.0 236 */ 237 public @NonNull Builder prompt(@Nullable String value) { 238 this.prompt = value; 239 return this; 240 } 241 242 /** 243 * Sets an optional login hint. 244 * 245 * @param value the hint, or null to omit 246 * @return this builder 247 * @since 1.0.0 248 */ 249 public @NonNull Builder loginHint(@Nullable String value) { 250 this.loginHint = value; 251 return this; 252 } 253 254 /** 255 * Replaces the complete application-data map. 256 * 257 * @param value the data, or null which restores the default 258 * @return this builder 259 * @since 1.0.0 260 */ 261 public @NonNull Builder applicationData(@Nullable Map<@NonNull String, @NonNull String> value) { 262 this.applicationData = value == null ? Map.of() : Map.copyOf(value); 263 return this; 264 } 265 266 /** 267 * Replaces the complete additional-parameter map. Reserved OAuth names, including authorization_details, are rejected. 268 * 269 * @param value the parameters, or null which restores the default 270 * @return this builder 271 * @since 1.0.0 272 */ 273 public @NonNull Builder additionalParameters(@Nullable Map<@NonNull String, @NonNull String> value) { 274 Map<String, String> copy = value == null ? Map.of() : Map.copyOf(value); 275 for (String name : copy.keySet()) 276 if (RESERVED.contains(name) || name.isEmpty()) 277 throw new IllegalArgumentException("An additional authorization parameter has a reserved name."); 278 this.additionalParameters = copy; 279 return this; 280 } 281 282 /** 283 * Builds the immutable options. 284 * 285 * @return the options 286 * @since 1.0.0 287 */ 288 public @NonNull AuthorizationRequestOptions build() { 289 return new AuthorizationRequestOptions(this); 290 } 291 } 292}