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 */ 016package com.revetsec.oauth; 017 018import static java.util.Objects.requireNonNull; 019import com.revetsec.jose.*; 020import com.revetsec.json.*; 021import java.time.*; 022import java.util.*; 023import javax.annotation.concurrent.Immutable; 024import org.jspecify.annotations.NonNull; 025import org.jspecify.annotations.Nullable; 026 027/** 028 * The access-token verdict. Only success releases proof. Credential rejection contains fixed reasons only; 029 * a checked introspection endpoint rejection is distinct from an invalid credential. 030 * Applications cannot construct outcomes. Future variants require a rejecting switch default. 031 * @author <a href="https://www.revetkn.com">Mark Allen</a> 032 * @since 1.0.0 033 */ 034@Immutable 035public abstract sealed class AccessTokenValidationResult permits AccessTokenValidationResult.Succeeded, AccessTokenValidationResult.Rejected, AccessTokenValidationResult.RejectedEndpoint { 036 037 AccessTokenValidationResult() { 038 } 039 040 static @NonNull AccessTokenValidationResult fromToken(@NonNull VerifiedAccessToken token) { 041 return new Succeeded(requireNonNull(token)); 042 } 043 044 static @NonNull AccessTokenValidationResult fromRejection(@NonNull AccessTokenValidationException rejection) { 045 return new Rejected(rejection.getReason(), rejection.getJoseReason().orElse(null)); 046 } 047 048 static @NonNull AccessTokenValidationResult fromEndpoint(@NonNull OAuthErrorResponseException failure) { 049 return new RejectedEndpoint(OAuthEndpointError.fromWireValue(failure.getErrorCode().orElse("")), failure.getStatus()); 050 } 051 052 /** 053 * Returns the outcome kind without data. 054 * @return redacted description 055 * @since 1.0.0 056 */ 057 @Override 058 @NonNull 059 public final String toString() { 060 return "AccessTokenValidationResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}"; 061 } 062 063 /** 064 * All configured access-token checks passed. 065 * @author <a href="https://www.revetkn.com">Mark Allen</a> 066 * @since 1.0.0 067 */ 068 @Immutable 069 public static final class Succeeded extends AccessTokenValidationResult { 070 071 @NonNull 072 private final VerifiedAccessToken token; 073 074 private Succeeded(@NonNull VerifiedAccessToken token) { 075 this.token = token; 076 } 077 078 /** 079 * Returns fully checked proof, without the received credential. 080 * @return access token 081 * @since 1.0.0 082 */ 083 @NonNull 084 public VerifiedAccessToken getAccessToken() { 085 return this.token; 086 } 087 } 088 089 /** 090 * The credential was rejected; no identity, claims, credential or exception is retained. 091 * @author <a href="https://www.revetkn.com">Mark Allen</a> 092 * @since 1.0.0 093 */ 094 @Immutable 095 public static final class Rejected extends AccessTokenValidationResult { 096 097 private final AccessTokenValidationException.@NonNull Reason reason; 098 099 private final JoseException.@Nullable Reason joseReason; 100 101 private Rejected(AccessTokenValidationException.@NonNull Reason reason, JoseException.@Nullable Reason joseReason) { 102 this.reason = reason; 103 this.joseReason = joseReason; 104 } 105 106 /** 107 * Returns the fixed resource-profile rejection. 108 * @return reason 109 * @since 1.0.0 110 */ 111 public AccessTokenValidationException.@NonNull Reason getReason() { 112 return this.reason; 113 } 114 115 /** 116 * Returns the fixed lower-layer JOSE reason, when applicable. 117 * @return reason 118 * @since 1.0.0 119 */ 120 @NonNull 121 public Optional<JoseException.@NonNull Reason> getJoseReason() { 122 return Optional.ofNullable(this.joseReason); 123 } 124 125 /** 126 * Returns a safe bearer challenge error; provider outages never enter this branch. 127 * @return bearer error 128 * @since 1.0.0 129 */ 130 @NonNull 131 public BearerError getBearerError() { 132 return this.reason == AccessTokenValidationException.Reason.MALFORMED_REQUEST ? BearerError.INVALID_REQUEST : BearerError.INVALID_TOKEN; 133 } 134 } 135 /** 136 * The introspection endpoint rejected the request with a checked, nontransient client error. This establishes 137 * no credential verdict and supplies no bearer challenge error. No identity, credential or endpoint prose is retained. 138 * @author <a href="https://www.revetkn.com">Mark Allen</a> 139 * @since 1.0.0 140 */ 141 @Immutable 142 public static final class RejectedEndpoint extends AccessTokenValidationResult { 143 private final @NonNull OAuthEndpointError error; 144 private final int status; 145 private RejectedEndpoint(@NonNull OAuthEndpointError error, int status) { 146 this.error = error; this.status = status; 147 } 148 /** 149 * Returns the fixed endpoint error. Extension codes have the unrecognized value. 150 * @return fixed error 151 * @since 1.0.0 152 */ 153 public @NonNull OAuthEndpointError getError() { return this.error; } 154 /** 155 * Returns the endpoint's HTTP status. 156 * @return HTTP status 157 * @since 1.0.0 158 */ 159 public @NonNull Integer getStatus() { return this.status; } 160 } 161 162}