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.oidc;
018
019import org.jspecify.annotations.NonNull;
020import javax.annotation.concurrent.Immutable;
021import static java.util.Objects.requireNonNull;
022import com.revetsec.oauth.OAuthException;
023import com.revetsec.oauth.OAuthEndpointError;
024import com.revetsec.oauth.OAuthErrorResponseException;
025import com.revetsec.jose.JoseException;
026import org.jspecify.annotations.Nullable;
027import java.util.Optional;
028/**
029 * The outcome of OIDC callback completion. Only a fully validated authentication releases identity and tokens.
030 * <p>
031 * Applications receive these outcomes from the corresponding operation; they cannot construct them.
032 * Value accessors exist only on the variant that owns a value. Diagnostic text contains no input or result data.
033 * A later release may add variants; consuming switches should include a rejecting default branch.
034 *
035 * @author <a href="https://www.revetkn.com">Mark Allen</a>
036 * @since 1.0.0
037 */
038@Immutable
039public abstract sealed class OidcAuthenticationResult permits OidcAuthenticationResult.Succeeded, OidcAuthenticationResult.Denied, OidcAuthenticationResult.RejectedAuthorization, OidcAuthenticationResult.RejectedIdToken, OidcAuthenticationResult.Failed, OidcAuthenticationResult.RejectedAuthorizationError, OidcAuthenticationResult.RejectedEndpoint {
040        OidcAuthenticationResult() { }
041
042        static @NonNull OidcAuthenticationResult fromAuthentication(@NonNull OidcAuthentication authentication) {
043                return new Succeeded(requireNonNull(authentication));
044        }
045
046        static @NonNull OidcAuthenticationResult fromDenial() {
047                return new Denied();
048        }
049
050        static @NonNull OidcAuthenticationResult fromAuthorizationReason(OAuthException.@NonNull Reason reason) {
051                return new RejectedAuthorization(requireNonNull(reason));
052        }
053
054        static @NonNull OidcAuthenticationResult fromIdTokenReason(OidcValidationException.@NonNull Reason reason, JoseException.@Nullable Reason joseReason) {
055                return new RejectedIdToken(requireNonNull(reason), joseReason);
056        }
057
058        static @NonNull OidcAuthenticationResult fromStoreFailure(OAuthException.@NonNull Reason reason) {
059                return new Failed(requireNonNull(reason));
060        }
061
062        static @NonNull OidcAuthenticationResult fromAuthorizationError(@NonNull OAuthEndpointError error) {
063                return new RejectedAuthorizationError(requireNonNull(error));
064        }
065        static @NonNull OidcAuthenticationResult fromEndpoint(@NonNull OAuthErrorResponseException failure) {
066                return new RejectedEndpoint(OAuthEndpointError.fromWireValue(failure.getErrorCode().orElse("")), failure.getStatus());
067        }
068
069        /**
070         * Returns the outcome kind with all values redacted.
071         * @return redacted description
072         * @since 1.0.0
073         */
074        @Override
075        public final @NonNull String toString() {
076                return "OidcAuthenticationResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}";
077        }
078
079        /**
080         * The shared authorization checks and all ID-token profile checks passed.
081         * @author <a href="https://www.revetkn.com">Mark Allen</a>
082         * @since 1.0.0
083         */
084        @Immutable
085        public static final class Succeeded extends OidcAuthenticationResult {
086                private final @NonNull OidcAuthentication authentication;
087                private Succeeded(@NonNull OidcAuthentication authentication) { this.authentication = authentication; }
088
089                /**
090                 * Returns the validated authentication and its released tokens.
091                 * @return authentication
092                 * @since 1.0.0
093                 */
094                public @NonNull OidcAuthentication getAuthentication() { return this.authentication; }
095        }
096
097        /**
098         * A bound callback reported access_denied after all pending-state and issuer checks.
099         * @author <a href="https://www.revetkn.com">Mark Allen</a>
100         * @since 1.0.0
101         */
102        @Immutable
103        public static final class Denied extends OidcAuthenticationResult {
104                private Denied() {  }
105        }
106
107        /**
108         * A local callback or pending-state security check failed.
109         * @author <a href="https://www.revetkn.com">Mark Allen</a>
110         * @since 1.0.0
111         */
112        @Immutable
113        public static final class RejectedAuthorization extends OidcAuthenticationResult {
114                private final OAuthException.@NonNull Reason reason;
115                private RejectedAuthorization(OAuthException.@NonNull Reason reason) { this.reason = reason; }
116
117                /**
118                 * Returns the fixed local authorization rejection reason.
119                 * @return reason
120                 * @since 1.0.0
121                 */
122                public OAuthException.@NonNull Reason getReason() { return this.reason; }
123        }
124
125        /**
126         * The ID token failed validation. No identity, claims or endpoint tokens are released.
127         * @author <a href="https://www.revetkn.com">Mark Allen</a>
128         * @since 1.0.0
129         */
130        @Immutable
131        public static final class RejectedIdToken extends OidcAuthenticationResult {
132                private final OidcValidationException.@NonNull Reason reason;
133                private final JoseException.@Nullable Reason joseReason;
134                private RejectedIdToken(OidcValidationException.@NonNull Reason reason, JoseException.@Nullable Reason joseReason) { this.reason = reason; this.joseReason = joseReason; }
135
136                /**
137                 * Returns the fixed ID-token rejection reason.
138                 * @return reason
139                 * @since 1.0.0
140                 */
141                public OidcValidationException.@NonNull Reason getReason() { return this.reason; }
142
143                /**
144                 * Returns the fixed lower-layer reason when JOSE rejected the input.
145                 * @return joseReason
146                 * @since 1.0.0
147                 */
148                public @NonNull Optional<JoseException.@NonNull Reason> getJoseReason() { return Optional.ofNullable(this.joseReason); }
149        }
150
151        /**
152         * The pending store did not complete its operation. No identity or token value is released.
153         * @author <a href="https://www.revetkn.com">Mark Allen</a>
154         * @since 1.0.0
155         */
156        @Immutable
157        public static final class Failed extends OidcAuthenticationResult {
158                private final OAuthException.@NonNull Reason reason;
159                private Failed(OAuthException.@NonNull Reason reason) { this.reason = reason; }
160
161                /**
162                 * Returns the fixed store-failure reason.
163                 * @return reason
164                 * @since 1.0.0
165                 */
166                public OAuthException.@NonNull Reason getReason() { return this.reason; }
167        }
168
169        /**
170         * A bound callback reported an authorization error after all pending-state and issuer checks passed.
171         * @author <a href="https://www.revetkn.com">Mark Allen</a>
172         * @since 1.0.0
173         */
174        @Immutable
175        public static final class RejectedAuthorizationError extends OidcAuthenticationResult {
176                private final @NonNull OAuthEndpointError error;
177                private RejectedAuthorizationError(@NonNull OAuthEndpointError error) { this.error = requireNonNull(error); }
178                /**
179                 * Returns the fixed authorization error; unknown extension codes share one fallback.
180                 * @return authorization error
181                 * @since 1.0.0
182                 */
183                public @NonNull OAuthEndpointError getError() { return this.error; }
184        }
185        /**
186         * The endpoint returned a non-transient client error. No response body or credential is retained.
187         * @author <a href="https://www.revetkn.com">Mark Allen</a>
188         * @since 1.0.0
189         */
190        @Immutable
191        public static final class RejectedEndpoint extends OidcAuthenticationResult {
192                private final @NonNull OAuthEndpointError error;
193                private final int status;
194                private RejectedEndpoint(@NonNull OAuthEndpointError error, int status) {
195                        this.error = requireNonNull(error); this.status = status;
196                }
197                /**
198                 * Returns the fixed endpoint error; unrecognized or absent codes use the same fallback.
199                 * @return fixed endpoint error
200                 * @since 1.0.0
201                 */
202                public @NonNull OAuthEndpointError getError() { return this.error; }
203                /**
204                 * Returns the endpoint's HTTP status.
205                 * @return endpoint status
206                 * @since 1.0.0
207                 */
208                public @NonNull Integer getStatus() { return this.status; }
209        }
210}