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}