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}