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 org.jspecify.annotations.Nullable;
021import com.google.errorprone.annotations.CheckReturnValue;
022import javax.annotation.concurrent.Immutable;
023import java.util.Optional;
024import static java.util.Objects.requireNonNull;
025import com.revetsec.oauth.VerifiedAccessToken;
026import com.revetsec.oauth.AccessTokenValidationException;
027import com.revetsec.oauth.BearerError;
028import com.revetsec.jose.JoseException;
029/**
030 * A library-created outcome. Applications cannot mint outcomes or proofs. Future variants require a rejecting
031 * switch default. Diagnostics disclose no interaction, credential, identity or claims. Infrastructure failures
032 * remain exceptions and cannot be reported as credential rejection.
033 * @since 1.0.0
034 */
035@Immutable
036public abstract sealed class OAuthIssuerAccessTokenResult permits OAuthIssuerAccessTokenResult.Succeeded, OAuthIssuerAccessTokenResult.Rejected {
037        OAuthIssuerAccessTokenResult() {}
038        static @NonNull OAuthIssuerAccessTokenResult fromSucceeded(@NonNull VerifiedAccessToken token,
039                        @NonNull String grantValue) {
040                requireNonNull(token); OAuthStoreFormat.nonce(grantValue);
041                return new Succeeded(token, grantValue);
042        }
043        static OAuthIssuerAccessTokenResult.@NonNull Rejected fromRejection(OAuthServerException.@NonNull Reason reason,
044                AccessTokenValidationException.@Nullable Reason accessTokenReason, JoseException.@Nullable Reason joseReason) {
045                requireNonNull(reason).requireKind(OAuthServerException.Kind.VALIDATION);
046                return new Rejected(reason,accessTokenReason,joseReason);
047        }
048        /** Returns a fixed redacted description.
049         * @return fixed redacted description
050         * @since 1.0.0
051         */
052        @Override public final @NonNull String toString() { return "OAuthIssuerAccessTokenResult{<redacted>}"; }
053        /** The library-created Succeeded outcome.
054         * @since 1.0.0
055         */
056        @Immutable public static final class Succeeded extends OAuthIssuerAccessTokenResult {
057                private final @NonNull VerifiedAccessToken token;
058                private final @NonNull String grantValue;
059                private Succeeded(@NonNull VerifiedAccessToken token, @NonNull String grantValue) {
060                        this.token=token; this.grantValue=grantValue;
061                }
062                /** Returns the checked access-token proof after authoritative issuer status validation.
063                 * @return token
064                 * @since 1.0.0
065                 */
066                @CheckReturnValue public @NonNull VerifiedAccessToken getAccessToken() { return this.token; }
067                /**
068                 * Explicitly releases the sensitive issuer-local grant management handle checked by the same authoritative
069                 * admission as the access-token proof. Scope application lookup keys to the issuer or deployment as well as
070                 * this value; the bare string is not globally authoritative or permission to act. Never log it.
071                 * @return the checked issuer-local grant handle
072                 * @since 1.0.0
073                 */
074                @CheckReturnValue public @NonNull String getGrantValue() { return this.grantValue; }
075        }
076        /** A fixed rejection with no proof, request, credential, identity, claims or exception object.
077         * @since 1.0.0
078         */
079        @Immutable public static final class Rejected extends OAuthIssuerAccessTokenResult {
080                private final OAuthServerException.@NonNull Reason reason;
081                private final AccessTokenValidationException.@Nullable Reason accessTokenReason;
082                private final JoseException.@Nullable Reason joseReason;
083                private Rejected(OAuthServerException.@NonNull Reason reason, AccessTokenValidationException.@Nullable Reason accessTokenReason,
084                        JoseException.@Nullable Reason joseReason) { this.reason=reason; this.accessTokenReason=accessTokenReason; this.joseReason=joseReason; }
085                /** Returns the fixed issuer rejection reason, not an external error string.
086                 * @return fixed reason
087                 * @since 1.0.0
088                 */
089                @CheckReturnValue public OAuthServerException.@NonNull Reason getReason() { return this.reason; }
090                /** Returns a fixed M5 profile reason, when applicable.
091                 * @return optional fixed resource-profile reason
092                 * @since 1.0.0
093                 */
094                @CheckReturnValue public @NonNull Optional<AccessTokenValidationException.@NonNull Reason> getAccessTokenReason() { return Optional.ofNullable(this.accessTokenReason); }
095                /** Returns a fixed JOSE reason, when applicable.
096                 * @return optional fixed JOSE reason
097                 * @since 1.0.0
098                 */
099                @CheckReturnValue public @NonNull Optional<JoseException.@NonNull Reason> getJoseReason() { return Optional.ofNullable(this.joseReason); }
100                /** Returns a safe bearer error; provider or store outages never enter this result.
101                 * @return safe bearer error
102                 * @since 1.0.0
103                 */
104                @CheckReturnValue public @NonNull BearerError getBearerError() { return this.reason==OAuthServerException.Reason.MALFORMED_REQUEST ? BearerError.INVALID_REQUEST : BearerError.INVALID_TOKEN; }
105        }
106}