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.oauth.VerifiedAccessToken; 026import com.revetsec.oauth.AccessTokenValidationException; 027import com.revetsec.oauth.BearerError; 028import com.revetsec.jose.JoseException; 029/** 030 * A library-created outcome. Applications cannot mint outcomes or proofs. Future variants require a rejecting 031 * switch default. Diagnostics disclose no interaction, credential, identity or claims. Infrastructure failures 032 * remain exceptions and cannot be reported as credential rejection. 033 * @since 1.0.0 034 */ 035@Immutable 036public abstract sealed class OAuthIssuerAccessTokenResult permits OAuthIssuerAccessTokenResult.Succeeded, OAuthIssuerAccessTokenResult.Rejected { 037 OAuthIssuerAccessTokenResult() {} 038 static @NonNull OAuthIssuerAccessTokenResult fromSucceeded(@NonNull VerifiedAccessToken token, 039 @NonNull String grantValue) { 040 requireNonNull(token); OAuthStoreFormat.nonce(grantValue); 041 return new Succeeded(token, grantValue); 042 } 043 static OAuthIssuerAccessTokenResult.@NonNull Rejected fromRejection(OAuthServerException.@NonNull Reason reason, 044 AccessTokenValidationException.@Nullable Reason accessTokenReason, JoseException.@Nullable Reason joseReason) { 045 requireNonNull(reason).requireKind(OAuthServerException.Kind.VALIDATION); 046 return new Rejected(reason,accessTokenReason,joseReason); 047 } 048 /** Returns a fixed redacted description. 049 * @return fixed redacted description 050 * @since 1.0.0 051 */ 052 @Override public final @NonNull String toString() { return "OAuthIssuerAccessTokenResult{<redacted>}"; } 053 /** The library-created Succeeded outcome. 054 * @since 1.0.0 055 */ 056 @Immutable public static final class Succeeded extends OAuthIssuerAccessTokenResult { 057 private final @NonNull VerifiedAccessToken token; 058 private final @NonNull String grantValue; 059 private Succeeded(@NonNull VerifiedAccessToken token, @NonNull String grantValue) { 060 this.token=token; this.grantValue=grantValue; 061 } 062 /** Returns the checked access-token proof after authoritative issuer status validation. 063 * @return token 064 * @since 1.0.0 065 */ 066 @CheckReturnValue public @NonNull VerifiedAccessToken getAccessToken() { return this.token; } 067 /** 068 * Explicitly releases the sensitive issuer-local grant management handle checked by the same authoritative 069 * admission as the access-token proof. Scope application lookup keys to the issuer or deployment as well as 070 * this value; the bare string is not globally authoritative or permission to act. Never log it. 071 * @return the checked issuer-local grant handle 072 * @since 1.0.0 073 */ 074 @CheckReturnValue public @NonNull String getGrantValue() { return this.grantValue; } 075 } 076 /** A fixed rejection with no proof, request, credential, identity, claims or exception object. 077 * @since 1.0.0 078 */ 079 @Immutable public static final class Rejected extends OAuthIssuerAccessTokenResult { 080 private final OAuthServerException.@NonNull Reason reason; 081 private final AccessTokenValidationException.@Nullable Reason accessTokenReason; 082 private final JoseException.@Nullable Reason joseReason; 083 private Rejected(OAuthServerException.@NonNull Reason reason, AccessTokenValidationException.@Nullable Reason accessTokenReason, 084 JoseException.@Nullable Reason joseReason) { this.reason=reason; this.accessTokenReason=accessTokenReason; this.joseReason=joseReason; } 085 /** Returns the fixed issuer rejection reason, not an external error string. 086 * @return fixed reason 087 * @since 1.0.0 088 */ 089 @CheckReturnValue public OAuthServerException.@NonNull Reason getReason() { return this.reason; } 090 /** Returns a fixed M5 profile reason, when applicable. 091 * @return optional fixed resource-profile reason 092 * @since 1.0.0 093 */ 094 @CheckReturnValue public @NonNull Optional<AccessTokenValidationException.@NonNull Reason> getAccessTokenReason() { return Optional.ofNullable(this.accessTokenReason); } 095 /** Returns a fixed JOSE reason, when applicable. 096 * @return optional fixed JOSE reason 097 * @since 1.0.0 098 */ 099 @CheckReturnValue public @NonNull Optional<JoseException.@NonNull Reason> getJoseReason() { return Optional.ofNullable(this.joseReason); } 100 /** Returns a safe bearer error; provider or store outages never enter this result. 101 * @return safe bearer error 102 * @since 1.0.0 103 */ 104 @CheckReturnValue public @NonNull BearerError getBearerError() { return this.reason==OAuthServerException.Reason.MALFORMED_REQUEST ? BearerError.INVALID_REQUEST : BearerError.INVALID_TOKEN; } 105 } 106}