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}