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 org.jspecify.annotations.NonNull;
022import org.jspecify.annotations.Nullable;
023
024import javax.annotation.concurrent.Immutable;
025import javax.annotation.concurrent.NotThreadSafe;
026import java.io.IOException;
027
028import static java.util.Objects.requireNonNull;
029
030/**
031 * An OAuth request, response, validation or transport failure. The reason and message are fixed; neither contains
032 * authorization codes, pending state, client secrets or tokens. Applications catch this type or one of its leaves.
033 *
034 * @author <a href="https://www.revetkn.com">Mark Allen</a>
035 * @since 1.0.0
036 */
037@NotThreadSafe
038public abstract sealed class OAuthException extends RevetsecException permits AuthorizationErrorException,
039                OAuthErrorResponseException, OAuthValidationException, OAuthResponseException, OAuthTransportException,
040                PendingAuthorizationStoreException, OAuthConfigurationException {
041        private static final long serialVersionUID = 1L;
042        /** Stable public failure reason. */
043        private final @NonNull Reason reason;
044
045        OAuthException(@NonNull Reason reason, boolean transientFailure, @Nullable IOException cause) {
046                super(requireNonNull(reason).category, transientFailure, reason.message, cause);
047                this.reason = reason;
048        }
049
050        /**
051         * Returns the fixed reason for this failure.
052         *
053         * @return the reason
054         * @since 1.0.0
055         */
056        public final @NonNull Reason getReason() {
057                return this.reason;
058        }
059
060        /**
061         * Reasons for OAuth failures. New reasons may be added in a later release.
062         *
063         * @author <a href="https://www.revetkn.com">Mark Allen</a>
064         * @since 1.0.0
065         */
066        @Immutable
067        public enum Reason {
068                /** The callback reported an authorization error. */
069                AUTHORIZATION_ERROR(ErrorCategory.REMOTE_ERROR, "The authorization server rejected the authorization request."),
070                /** The token or revocation endpoint reported an OAuth error. */
071                ENDPOINT_ERROR(ErrorCategory.REMOTE_ERROR, "The authorization server rejected the endpoint request."),
072                /** The callback state is absent or differs from the pending state. */
073                STATE_MISMATCH(ErrorCategory.VALIDATION_FAILURE, "The authorization response state does not match."),
074                /** The browser binding does not match the saved pending authorization. */
075                BROWSER_BINDING_MISMATCH(ErrorCategory.VALIDATION_FAILURE, "The pending authorization belongs to another browser."),
076                /** The sealed pending record is invalid or cannot be opened. */
077                PENDING_AUTHORIZATION_INVALID(ErrorCategory.VALIDATION_FAILURE, "The pending authorization is invalid."),
078                /** The authenticated pending record has expired. */
079                PENDING_AUTHORIZATION_EXPIRED(ErrorCategory.VALIDATION_FAILURE, "The pending authorization has expired."),
080                /** No pending record was found in the store. */
081                PENDING_AUTHORIZATION_NOT_FOUND(ErrorCategory.VALIDATION_FAILURE, "The pending authorization was not found."),
082                /** The pending record belongs to another client. */
083                CLIENT_MISMATCH(ErrorCategory.VALIDATION_FAILURE, "The pending authorization belongs to another client."),
084                /** The pending record belongs to another issuer. */
085                ISSUER_MISMATCH(ErrorCategory.VALIDATION_FAILURE, "The authorization issuer does not match."),
086                /** A required callback issuer is missing. */
087                ISSUER_MISSING(ErrorCategory.VALIDATION_FAILURE, "The authorization response issuer is missing."),
088                /** The trusted callback route differs from the registered redirect URI. */
089                CALLBACK_URI_MISMATCH(ErrorCategory.VALIDATION_FAILURE, "The callback URI does not match the authorization request."),
090                /** The callback delivery mode differs from the pending request. */
091                RESPONSE_MODE_MISMATCH(ErrorCategory.VALIDATION_FAILURE, "The authorization response mode does not match."),
092                /** The metadata issuer or an endpoint is unsafe or mismatched. */
093                METADATA_INVALID(ErrorCategory.VALIDATION_FAILURE, "The authorization server metadata is invalid."),
094                /** The endpoint pair changed while an authorization was pending. */
095                METADATA_ENDPOINT_DRIFT(ErrorCategory.VALIDATION_FAILURE, "The authorization server endpoints changed."),
096                /** An authorization server does not advertise required PKCE S256 support. */
097                PKCE_UNSUPPORTED(ErrorCategory.VALIDATION_FAILURE, "The authorization server does not advertise PKCE S256."),
098                /** A token cannot be returned because its lifetime has already ended. */
099                TOKEN_EXPIRED(ErrorCategory.VALIDATION_FAILURE, "The token has expired."),
100                /** The in-memory store has reached a configured live capacity. */
101                CAPACITY_EXCEEDED(ErrorCategory.CONFIGURATION, "The pending-authorization store is full."),
102                /** The pending-authorization store failed or exceeded the remaining operation budget. */
103                PENDING_AUTHORIZATION_STORE_UNAVAILABLE(ErrorCategory.CONFIGURATION, "The pending-authorization store is unavailable."),
104                /** A callback has duplicate, conflicting or malformed parameters. */
105                CALLBACK_MALFORMED(ErrorCategory.MALFORMED_INPUT, "The authorization response is malformed."),
106                /** A metadata or token JSON document is malformed. */
107                DOCUMENT_MALFORMED(ErrorCategory.MALFORMED_INPUT, "The authorization server document is malformed."),
108                /** An endpoint returned an unexpected status or media type. */
109                ENDPOINT_RESPONSE_MALFORMED(ErrorCategory.MALFORMED_INPUT, "The authorization server response is malformed."),
110                /** The endpoint redirected a request carrying credentials; the redirect was not followed. */
111                REDIRECT_NOT_FOLLOWED(ErrorCategory.REMOTE_ERROR, "The authorization server redirected a credentialed request."),
112                /** The endpoint response exceeded its configured body limit. */
113                TOO_LARGE(ErrorCategory.MALFORMED_INPUT, "The authorization server response is too large."),
114                /** A successful endpoint response lacked one permitted JSON media type. */
115                UNEXPECTED_CONTENT_TYPE(ErrorCategory.MALFORMED_INPUT,
116                                "The authorization server response has an unexpected content type."),
117                /** A network request failed or timed out. */
118                NETWORK_FAILURE(ErrorCategory.TRANSPORT, "The authorization server request failed."),
119                /** A thread was interrupted during a network request. */
120                INTERRUPTED(ErrorCategory.TRANSPORT, "The authorization server request was interrupted."),
121                /** A cache attempt ceiling temporarily held back the request. */
122                ATTEMPT_LIMIT(ErrorCategory.TRANSPORT, "The authorization server request is temporarily held back."),
123                /** The default HTTP client could not be constructed. */
124                HTTP_CLIENT_UNAVAILABLE(ErrorCategory.CONFIGURATION, "The HTTP client is unavailable."),
125                /** The configured assertion key could not be selected. */
126                CLIENT_ASSERTION_KEY_UNAVAILABLE(ErrorCategory.CONFIGURATION, "The client assertion key is unavailable."),
127                /** The configured assertion could not be signed or has invalid timing. */
128                CLIENT_ASSERTION_SIGNING_FAILED(ErrorCategory.CONFIGURATION, "The client assertion could not be prepared."),
129                /** The assertion private and public keys do not form a pair. */
130                CLIENT_ASSERTION_KEY_PAIR_MISMATCH(ErrorCategory.CONFIGURATION, "The client assertion key pair does not match."),
131                /** The asserted endpoint or its authentication metadata does not match the configured trust. */
132                CLIENT_ASSERTION_ENDPOINT_MISMATCH(ErrorCategory.CONFIGURATION, "The client assertion endpoint configuration does not match."),
133                /** The application issuer policy is unavailable. */
134                ISSUER_POLICY_UNAVAILABLE(ErrorCategory.CONFIGURATION, "The issuer policy is unavailable.");
135
136                private final @NonNull ErrorCategory category;
137                private final @NonNull String message;
138
139                Reason(@NonNull ErrorCategory category, @NonNull String message) {
140                        this.category = category;
141                        this.message = message;
142                }
143
144                @NonNull ErrorCategory category() {
145                        return this.category;
146                }
147        }
148}