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 org.jspecify.annotations.NonNull;
020import javax.annotation.concurrent.Immutable;
021import java.util.Map;
022import java.util.Set;
023
024/**
025 * Issuer-created grant facts supplied to the application's continuing authorization policy.
026 * This type has no application factory or builder and contains no raw code or refresh credential.
027 * Policies must deny any grant type they do not recognize, including types added in a later release.
028 * Future client-credentials issuance uses a separate policy interface and namespaced client subjects.
029 * The grant management handle is sensitive; release it only to trusted application management code.
030 *
031 * @author <a href="https://www.revetkn.com">Mark Allen</a>
032 * @since 1.0.0
033 */
034@Immutable
035public final class OAuthGrantContext {
036        private final @NonNull String subject;
037        private final @NonNull String clientId;
038        private final @NonNull String grantType;
039        private final @NonNull String grantValue;
040        private final @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> authorizedScopesByResource;
041        private final boolean refreshTokenPermitted;
042        private OAuthGrantContext(@NonNull String subject, @NonNull String clientId, @NonNull String grantType,
043                        @NonNull String grantValue, @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> resources,
044                        boolean refreshTokenPermitted) {
045                this.subject = subject; this.clientId = clientId; this.grantType = grantType; this.grantValue = grantValue;
046                this.authorizedScopesByResource = Map.copyOf(resources); this.refreshTokenPermitted = refreshTokenPermitted;
047        }
048        // Called only after the engine has validated and bound these facts. Value checks do not authenticate a grant.
049        static @NonNull OAuthGrantContext fromCheckedGrant(@NonNull String subject, @NonNull String clientId,
050                        @NonNull String grantType, @NonNull String grantValue,
051                        @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> resources, boolean refreshTokenPermitted) {
052                OAuthServerConfiguration.text(subject, OAuthServerConfiguration.MAXIMUM_SUBJECT_LENGTH);
053                OAuthServerConfiguration.text(clientId, OAuthServerConfiguration.MAXIMUM_CLIENT_ID_LENGTH);
054                OAuthServerConfiguration.text(grantType, OAuthServerConfiguration.MAXIMUM_TEXT_LENGTH);
055                OAuthServerConfiguration.text(grantValue, OAuthServerConfiguration.MAXIMUM_TEXT_LENGTH);
056                if (!grantType.equals("authorization_code") && !grantType.equals("refresh_token")) throw OAuthServerConfiguration.invalid();
057                return new OAuthGrantContext(subject, clientId, grantType, grantValue,
058                                OAuthServerConfiguration.resources(resources, 1), refreshTokenPermitted);
059        }
060        /**
061         * Returns the checked issuer-local subject.
062         * @return the configured value
063         * @since 1.0.0
064         */
065        public @NonNull String getSubject() { return this.subject; }
066        /**
067         * Returns the exact checked client identifier.
068         * @return the configured value
069         * @since 1.0.0
070         */
071        public @NonNull String getClientId() { return this.clientId; }
072        /**
073         * Returns the operation being checked, currently authorization_code or refresh_token.
074         * Policies must deny unrecognized types, including future additions.
075         * @return the configured value
076         * @since 1.0.0
077         */
078        public @NonNull String getGrantType() { return this.grantType; }
079        /**
080         * Explicitly releases the sensitive grant handle for trusted application management; never log it.
081         * @return the configured value
082         * @since 1.0.0
083         */
084        public @NonNull String getGrantValue() { return this.grantValue; }
085        /**
086         * Returns the immutable complete checked resource/scope grant.
087         * @return the configured value
088         * @since 1.0.0
089         */
090        public @NonNull Map<@NonNull String, @NonNull Set<@NonNull String>> getAuthorizedScopesByResource() { return this.authorizedScopesByResource; }
091        /**
092         * Returns whether the checked grant permits refresh.
093         * @return the configured value
094         * @since 1.0.0
095         */
096        public @NonNull Boolean isRefreshTokenPermitted() { return this.refreshTokenPermitted; }
097        /**
098         * Redacts all grant facts and the management handle from diagnostics.
099         * @return a fixed description
100         * @since 1.0.0
101         */
102        @Override public @NonNull String toString() { return "OAuthGrantContext{grant=<redacted>}"; }
103}