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}