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.util.Map;
025import java.util.Optional;
026import java.util.Set;
027
028/**
029 * Trusted application authorization decision; it is not a verified authentication or token proof.
030 * An allowed decision has one exact resource and an issuer-local subject. An explicit empty scope set is
031 * representable for policy denial and never authorizes a zero-scope credential. The issuer must enforce the
032 * interaction/client/server subsets and continuing subject identity before issuance. Applications authenticate
033 * users and protect their login/consent submissions and sessions themselves.
034 *
035 * @author <a href="https://www.revetkn.com">Mark Allen</a>
036 * @since 1.0.0
037 */
038@Immutable
039public final class OAuthAuthorizationDecision {
040        private static final @NonNull OAuthAuthorizationDecision DENIED = new OAuthAuthorizationDecision(null, Map.of(), false);
041        private final @Nullable String subject;
042        private final @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> authorizedScopesByResource;
043        private final boolean refreshTokenPermitted;
044        private OAuthAuthorizationDecision(@Nullable String subject,
045                        @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> resources, boolean refreshTokenPermitted) {
046                this.subject = subject; this.authorizedScopesByResource = Map.copyOf(resources); this.refreshTokenPermitted = refreshTokenPermitted;
047        }
048        /**
049         * Returns an explicit application denial, without a subject or grant.
050         * @return the denied decision
051         * @since 1.0.0
052         */
053        @CheckReturnValue
054        public static @NonNull OAuthAuthorizationDecision deniedInstance() { return DENIED; }
055        /**
056         * Starts a decision for an application-authenticated issuer-local subject.
057         * @param subject the exact nonempty subject, at most 1024 UTF-16 code units
058         * @return the builder
059         * @throws NullPointerException if subject is null
060         * @throws IllegalArgumentException if subject is invalid
061         * @since 1.0.0
062         */
063        @CheckReturnValue
064        public static @NonNull Builder withSubject(@NonNull String subject) { return new Builder(subject); }
065        /**
066         * Returns whether the application explicitly denied authorization.
067         * @return the configured value
068         * @since 1.0.0
069         */
070        public @NonNull Boolean isDenied() { return this.subject == null; }
071        /**
072         * Returns the application subject, absent for explicit denial.
073         * @return the configured value
074         * @since 1.0.0
075         */
076        public @NonNull Optional<@NonNull String> getSubject() { return Optional.ofNullable(this.subject); }
077        /**
078         * Returns the immutable complete resource/scope decision.
079         * @return the configured value
080         * @since 1.0.0
081         */
082        public @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> getAuthorizedScopesByResource() { return this.authorizedScopesByResource; }
083        /**
084         * Returns application refresh permission, subject to the server and client policies.
085         * @return the configured value
086         * @since 1.0.0
087         */
088        public @NonNull Boolean isRefreshTokenPermitted() { return this.refreshTokenPermitted; }
089        /**
090         * Redacts all decision values from diagnostics.
091         * @return a fixed description
092         * @since 1.0.0
093         */
094        @Override public @NonNull String toString() { return "OAuthAuthorizationDecision{decision=<redacted>}"; }
095        /**
096         * Replacing decision builder. Null scope maps clear a required setting; null refresh permission resets false.
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 final @NonNull String subject;
104                private @Nullable Map<@NonNull String, @NonNull Set<@NonNull String>> authorizedScopesByResource;
105                private boolean refreshTokenPermitted;
106                private Builder(@NonNull String subject) {
107                        this.subject = OAuthServerConfiguration.text(subject, OAuthServerConfiguration.MAXIMUM_SUBJECT_LENGTH);
108                }
109                /**
110                 * Snapshots a complete one-resource decision. An empty scope set is retained; null clears the required map.
111                 * @param value the replacement value, or null to reset
112                 * @return this builder
113                 * @since 1.0.0
114                 */
115                public @NonNull Builder authorizedScopesByResource(@Nullable Map<@NonNull String, @NonNull Set<@NonNull String>> value) {
116                        this.authorizedScopesByResource = value == null ? null : OAuthServerConfiguration.resources(value, 1);
117                        return this;
118                }
119                /**
120                 * Sets application refresh permission; null resets to false.
121                 * @param value the replacement value, or null to reset
122                 * @return this builder
123                 * @since 1.0.0
124                 */
125                public @NonNull Builder refreshTokenPermitted(@Nullable Boolean value) {
126                        this.refreshTokenPermitted = Boolean.TRUE.equals(value);
127                        return this;
128                }
129                /**
130                 * Builds a trusted app decision without authentication or I/O.
131                 * @return the immutable decision
132                 * @throws IllegalStateException if the resource/scope map is missing
133                 * @since 1.0.0
134                 */
135                public @NonNull OAuthAuthorizationDecision build() {
136                        Map<String, Set<String>> resources = this.authorizedScopesByResource;
137                        if (resources == null) throw new IllegalStateException("An authorization resource/scope decision is required.");
138                        return new OAuthAuthorizationDecision(this.subject, resources, this.refreshTokenPermitted);
139                }
140                /**
141                 * Redacts mutable decision values from diagnostics.
142                 * @return a fixed description
143                 * @since 1.0.0
144                 */
145                @Override public @NonNull String toString() { return "OAuthAuthorizationDecision.Builder{decision=<redacted>}"; }
146        }
147}