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}