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 com.revetsec.ErrorCategory;
020import com.revetsec.RevetsecException;
021import com.revetsec.jose.JoseException;
022import org.jspecify.annotations.NonNull;
023import org.jspecify.annotations.Nullable;
024import javax.annotation.concurrent.Immutable;
025import javax.annotation.concurrent.NotThreadSafe;
026import java.util.Optional;
027import static java.util.Objects.requireNonNull;
028
029/**
030 * A local bearer credential verdict, with fixed reasons and no token, claims or lower-layer exception retained.
031 * Infrastructure failures retain their own exception types; they must not be turned into invalid_token.
032 * Applications catch this exception; only Revetsec constructs it. No scope permission is granted by parsing.
033 *
034 * @author <a href="https://www.revetkn.com">Mark Allen</a>
035 * @since 1.0.0
036 */
037@NotThreadSafe
038public final class AccessTokenValidationException extends RevetsecException {
039        private static final long serialVersionUID = 1L;
040        /** The fixed local credential verdict.
041         * @serial
042         */
043        private final @NonNull Reason reason;
044        /** Optional lower-layer reason; never a lower-layer exception or credential.
045         * @serial
046         */
047        private final JoseException.@Nullable Reason joseReason;
048        private AccessTokenValidationException(@NonNull Reason reason, JoseException.@Nullable Reason joseReason) {
049                super(requireNonNull(reason) == Reason.MALFORMED_REQUEST ? ErrorCategory.MALFORMED_INPUT
050                                : ErrorCategory.VALIDATION_FAILURE, false, reason.message, null);
051                this.reason = reason; this.joseReason = joseReason;
052        }
053        static @NonNull AccessTokenValidationException fromReason(@NonNull Reason reason) {
054                return new AccessTokenValidationException(reason, null);
055        }
056        static @NonNull AccessTokenValidationException fromJoseReason(JoseException.@NonNull Reason reason) {
057                return new AccessTokenValidationException(Reason.JWT_REJECTED, requireNonNull(reason));
058        }
059        /**
060         * Returns the fixed local failure reason.
061         * @return the reason
062         * @since 1.0.0
063         */
064        public @NonNull Reason getReason() { return this.reason; }
065        /**
066         * Returns invalid_request for malformed presentation, otherwise invalid_token.
067         * @return the bearer error
068         * @since 1.0.0
069         */
070        public @NonNull BearerError getBearerError() {
071                return this.reason == Reason.MALFORMED_REQUEST ? BearerError.INVALID_REQUEST : BearerError.INVALID_TOKEN;
072        }
073        /**
074         * Returns a lower-layer JWT reason, without retaining its exception or input.
075         * @return the JOSE reason, if applicable
076         * @since 1.0.0
077         */
078        public @NonNull Optional<JoseException.@NonNull Reason> getJoseReason() {
079                return Optional.ofNullable(this.joseReason);
080        }
081        /**
082         * The failed credential check. Later releases may add values; switches need a default branch.
083         * @author <a href="https://www.revetkn.com">Mark Allen</a>
084         * @since 1.0.0
085         */
086        @Immutable
087        public enum Reason {
088                /** The bearer credential presentation is malformed. */
089                MALFORMED_REQUEST("The bearer credential presentation is malformed."),
090                /** The access token failed JWT validation. */
091                JWT_REJECTED("The access token failed JWT validation."),
092                /** An access token claim is invalid. */
093                INVALID_CLAIM("An access token claim is invalid."),
094                /** A required access token claim is missing. */
095                REQUIRED_CLAIM_MISSING("A required access token claim is missing."),
096                /** An untyped access token contains an identity-token claim. */
097                UNTYPED_IDENTITY_CLAIM_PRESENT("An untyped access token contains an identity-token claim."),
098                /** The access token is inactive. */
099                INACTIVE("The access token is inactive."),
100                /** The access token issuer does not match. */
101                ISSUER_MISMATCH("The access token issuer does not match."),
102                /** The access token has no required audience. */
103                AUDIENCE_MISSING("The access token has no required audience."),
104                /** The access token audience does not match. */
105                AUDIENCE_MISMATCH("The access token audience does not match."),
106                /** The access token has expired. */
107                EXPIRED("The access token has expired."),
108                /** The access token was issued in the future. */
109                ISSUED_IN_FUTURE("The access token was issued in the future."),
110                /** The access token is not yet valid. */
111                NOT_YET_VALID("The access token is not yet valid."),
112                /** The access token requires proof of key possession. */
113                CONFIRMATION_NOT_VERIFIED("The access token requires proof of key possession."),
114                /** The access token type is invalid. */
115                TOKEN_TYPE_INVALID("The access token type is invalid."),
116                /** The access token scope is invalid. */
117                SCOPE_INVALID("The access token scope is invalid.");
118                private final @NonNull String message;
119                Reason(@NonNull String message) { this.message = message; }
120        }
121}