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.RevetsecException;
026import com.revetsec.ErrorCategory;
027import javax.annotation.concurrent.NotThreadSafe;
028
029/**
030 * The sealed issuer exception family. Fixed reasons and messages contain no request or application data.
031 * External causes and suppressed exceptions are never retained. Transience is not permission to retransmit
032 * a code, refresh or revocation request. An unknown commit outcome is always nontransient and needs reconciliation.
033 * @since 1.0.0
034 */
035@NotThreadSafe
036public abstract sealed class OAuthServerException extends RevetsecException permits OAuthServerValidationException,
037        OAuthServerStoreException, OAuthServerTransportException, OAuthServerConfigurationException, OAuthServerSigningException {
038        private static final long serialVersionUID=1L;
039        /** The fixed classification.
040         * @serial
041         */
042        private final @NonNull Reason reason;
043        OAuthServerException(@NonNull Reason reason, boolean transientFailure) {
044                super(requireNonNull(reason).category,transientFailure,reason.message,null); this.reason=reason;
045        }
046        /** Returns the fixed issuer reason; it is not an external OAuth error string.
047         * @return fixed issuer reason
048         * @since 1.0.0
049         */
050        @CheckReturnValue public final @NonNull Reason getReason() { return this.reason; }
051        /** Returns a fixed description without causes, credentials or application data.
052         * @return fixed description
053         * @since 1.0.0
054         */
055        @SuppressWarnings("OverrideThrowableToString") // The exact redacted diagnostic is part of the public safety contract.
056        @Override public final @NonNull String toString() { return "OAuthServerException{"+this.reason+"}"; }
057        enum Kind { VALIDATION, STORE, TRANSPORT, CONFIGURATION, SIGNING }
058        /** Fixed classifications; a later release may add values. Callers must include a default branch rather than
059         * switching exhaustively. Different reasons may deliberately share the same safe wire error.
060         * @since 1.0.0
061         */
062        @Immutable public enum Reason {
063                /** The OAuth server request is malformed. */
064                MALFORMED_REQUEST(Kind.VALIDATION,ErrorCategory.MALFORMED_INPUT,"The OAuth server request is malformed."),
065                /** The OAuth server request method is not supported. */
066                METHOD_NOT_ALLOWED(Kind.VALIDATION,ErrorCategory.UNSUPPORTED,"The OAuth server request method is not supported."),
067                /** The OAuth server grant type is not supported. */
068                UNSUPPORTED_GRANT_TYPE(Kind.VALIDATION,ErrorCategory.UNSUPPORTED,"The OAuth server grant type is not supported."),
069                /** The OAuth server response type is not supported. */
070                UNSUPPORTED_RESPONSE_TYPE(Kind.VALIDATION,ErrorCategory.UNSUPPORTED,"The OAuth server response type is not supported."),
071                /** The OAuth server client is not recognized. */
072                UNKNOWN_CLIENT(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server client is not recognized."),
073                /** The OAuth server client authentication failed. */
074                INVALID_CLIENT(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server client authentication failed."),
075                /** The OAuth server client is not authorized. */
076                UNAUTHORIZED_CLIENT(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server client is not authorized."),
077                /** The OAuth server redirect is not trusted. */
078                REDIRECT_NOT_TRUSTED(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server redirect is not trusted."),
079                /** The OAuth server request requires PKCE. */
080                PKCE_REQUIRED(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server request requires PKCE."),
081                /** The OAuth server PKCE check failed. */
082                PKCE_MISMATCH(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server PKCE check failed."),
083                /** The OAuth server resource is not permitted. */
084                INVALID_RESOURCE(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server resource is not permitted."),
085                /** The OAuth server scope is not permitted. */
086                INVALID_SCOPE(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server scope is not permitted."),
087                /** The OAuth server interaction has expired. */
088                INTERACTION_EXPIRED(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server interaction has expired."),
089                /** The OAuth server interaction is no longer pending. */
090                INTERACTION_REUSED(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server interaction is no longer pending."),
091                /** The OAuth server grant is invalid. */
092                INVALID_GRANT(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server grant is invalid."),
093                /** The OAuth server refresh credential was reused. */
094                REFRESH_REUSE(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server refresh credential was reused."),
095                /** The OAuth server token is not active. */
096                TOKEN_REVOKED(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server token is not active."),
097                /** The OAuth server authorization was denied. */
098                ACCESS_DENIED(Kind.VALIDATION,ErrorCategory.VALIDATION_FAILURE,"The OAuth server authorization was denied."),
099                /** The OAuth server store is unavailable. */
100                STORE_UNAVAILABLE(Kind.STORE,ErrorCategory.TRANSPORT,"The OAuth server store is unavailable."),
101                /** The OAuth server store state is invalid. */
102                STORE_CORRUPT(Kind.STORE,ErrorCategory.CONFIGURATION,"The OAuth server store state is invalid."),
103                /** The OAuth server commit outcome is unknown. */
104                COMMIT_OUTCOME_UNKNOWN(Kind.STORE,ErrorCategory.TRANSPORT,"The OAuth server commit outcome is unknown."),
105        /** The OAuth server transition committed but its result was not admitted. */
106        COMMIT_CONFIRMED_NOT_ADMITTED(Kind.STORE,ErrorCategory.TRANSPORT,"The OAuth server transition committed but its result was not admitted."),
107                /** The OAuth server client metadata is unavailable. */
108                CLIENT_METADATA_UNAVAILABLE(Kind.TRANSPORT,ErrorCategory.TRANSPORT,"The OAuth server client metadata is unavailable."),
109                /** The OAuth server configuration is invalid. */
110                CONFIGURATION_INVALID(Kind.CONFIGURATION,ErrorCategory.CONFIGURATION,"The OAuth server configuration is invalid."),
111                /** The OAuth server response could not be signed. */
112                SIGNING_FAILED(Kind.SIGNING,ErrorCategory.CONFIGURATION,"The OAuth server response could not be signed."),
113                /** The OAuth server is unavailable. Generic dependency/budget failure does not establish transience. */
114                SERVICE_UNAVAILABLE(Kind.TRANSPORT,ErrorCategory.TRANSPORT,"The OAuth server is unavailable.");
115                private final @NonNull Kind kind;
116                private final @NonNull ErrorCategory category;
117                private final @NonNull String message;
118                Reason(@NonNull Kind kind, @NonNull ErrorCategory category, @NonNull String message) { this.kind=kind; this.category=category; this.message=message; }
119                void requireKind(@NonNull Kind expected) { if(this.kind!=requireNonNull(expected)) throw OAuthStoreFormat.invalid(); }
120        }
121}