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 * Scope, resource and additional form options for one token request. An absent scope set means the refresh request
034 * omits scope; it does not inherit client defaults. A caller refreshing a token must request only a subset of the
035 * original grant because this object does not know that grant.
036 *
037 * @author <a href="https://www.revetkn.com">Mark Allen</a>
038 * @since 1.0.0
039 */
040@Immutable
041public final class TokenRequestOptions {
042        private static final Set<String> RESERVED = Set.of("grant_type", "code", "redirect_uri", "code_verifier",
043                        "refresh_token", "client_assertion", "client_assertion_type", "client_id", "client_secret", "scope", "resource", "token", "token_type_hint", "authorization_details");
044        private final @Nullable Set<@NonNull String> scopes;
045        private final @NonNull List<@NonNull URI> resources;
046        private final boolean resourcesOverridden;
047        private final @NonNull Map<@NonNull String, @NonNull String> additionalParameters;
048
049        private TokenRequestOptions(@NonNull Builder builder) {
050                this.scopes = builder.scopes;
051                this.resources = builder.resources;
052                this.resourcesOverridden = builder.resourcesOverridden;
053                this.additionalParameters = builder.additionalParameters;
054        }
055
056        /**
057         * Starts a builder with no scope override or resources.
058         *
059         * @return builder
060         * @since 1.0.0
061         */
062        public static @NonNull Builder builder() { return new Builder(); }
063
064        /**
065         * Returns the complete requested scope set if explicitly supplied.
066         *
067         * @return scopes
068         * @since 1.0.0
069         */
070        public @NonNull Optional<@NonNull Set<@NonNull String>> getScopes() {
071                return Optional.ofNullable(this.scopes);
072        }
073
074        /**
075         * Returns ordered RFC 8707 resource indicators.
076         *
077         * @return resources
078         * @since 1.0.0
079         */
080        public @NonNull List<@NonNull URI> getResources() { return this.resources; }
081
082        boolean resourcesOverridden() { return this.resourcesOverridden; }
083
084        /**
085         * Returns additional nonreserved form parameters.
086         *
087         * @return parameters
088         * @since 1.0.0
089         */
090        public @NonNull Map<@NonNull String, @NonNull String> getAdditionalParameters() {
091                return this.additionalParameters;
092        }
093
094        /**
095         * Mutable builder for one token request.
096         *
097         * @author <a href="https://www.revetkn.com">Mark Allen</a>
098         * @since 1.0.0
099         */
100        @NotThreadSafe
101        @CheckReturnValue
102        public static final class Builder {
103                private @Nullable Set<@NonNull String> scopes;
104                private @NonNull List<@NonNull URI> resources = List.of();
105                private boolean resourcesOverridden;
106                private @NonNull Map<@NonNull String, @NonNull String> additionalParameters = Map.of();
107
108                private Builder() {
109                }
110
111                /**
112                 * Replaces the complete scope set for this request. Null omits the scope field.
113                 *
114                 * @param value scopes or null
115                 * @return this builder
116                 * @since 1.0.0
117                 */
118                public @NonNull Builder scopes(@Nullable Set<@NonNull String> value) {
119                        Set<String> copy = value == null ? null : Set.copyOf(value);
120                        if (copy != null)
121                                for (String scope : copy)
122                                        if (scope.isEmpty() || scope.chars().anyMatch(c -> c <= 0x20 || c == 0x22 || c == 0x5C || c >= 0x7F))
123                                                throw new IllegalArgumentException("A scope contains invalid characters.");
124                        this.scopes = copy;
125                        return this;
126                }
127
128                /**
129                 * Replaces the complete ordered resource list.
130                 *
131                 * @param value resources, or null which restores inheritance
132                 * @return this builder
133                 * @since 1.0.0
134                 */
135                public @NonNull Builder resources(@Nullable List<@NonNull URI> value) {
136                        this.resources = value == null ? List.of() : List.copyOf(value);
137                        for (URI resource : this.resources)
138                                if (!resource.isAbsolute() || resource.getFragment() != null)
139                                        throw new IllegalArgumentException("A resource indicator must be absolute and fragment-free.");
140                        this.resourcesOverridden = value != null;
141                        return this;
142                }
143
144                /**
145                 * Replaces the additional nonreserved form parameters; authorization_details is reserved.
146                 *
147                 * @param value parameters, or null which restores the default
148                 * @return this builder
149                 * @since 1.0.0
150                 */
151                public @NonNull Builder additionalParameters(@Nullable Map<@NonNull String, @NonNull String> value) {
152                        Map<String, String> copy = value == null ? Map.of() : Map.copyOf(value);
153                        for (String name : copy.keySet())
154                                if (name.isEmpty() || RESERVED.contains(name))
155                                        throw new IllegalArgumentException("A token request parameter has a reserved name.");
156                        this.additionalParameters = copy;
157                        return this;
158                }
159
160                /**
161                 * Builds immutable options.
162                 *
163                 * @return options
164                 * @since 1.0.0
165                 */
166                public @NonNull TokenRequestOptions build() { return new TokenRequestOptions(this); }
167        }
168}