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}