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}