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 org.jspecify.annotations.NonNull;
020import javax.annotation.concurrent.Immutable;
021import static java.util.Objects.requireNonNull;
022
023/**
024 * The outcome of OAuth callback completion. Bound authorization errors, checked endpoint rejections and
025 * pending-store failures have distinct, fixed results. Transport, metadata, malformed endpoint responses and
026 * transient endpoint failures remain exceptions.
027 * <p>
028 * Applications receive these outcomes from the corresponding operation; they cannot construct them.
029 * Value accessors exist only on the variant that owns a value. Diagnostic text contains no input or result data.
030 * A later release may add variants; consuming switches should include a rejecting default branch.
031 *
032 * @author <a href="https://www.revetkn.com">Mark Allen</a>
033 * @since 1.0.0
034 */
035@Immutable
036public abstract sealed class AuthorizationCompletionResult permits AuthorizationCompletionResult.Succeeded, AuthorizationCompletionResult.Denied, AuthorizationCompletionResult.Rejected, AuthorizationCompletionResult.Failed, AuthorizationCompletionResult.RejectedAuthorizationError, AuthorizationCompletionResult.RejectedEndpoint {
037        AuthorizationCompletionResult() { }
038
039        static @NonNull AuthorizationCompletionResult fromTokens(@NonNull TokenResponse tokens) {
040                return new Succeeded(requireNonNull(tokens));
041        }
042
043        static @NonNull AuthorizationCompletionResult fromDenial() {
044                return new Denied();
045        }
046
047        static @NonNull AuthorizationCompletionResult fromReason(OAuthException.@NonNull Reason reason) {
048                return new Rejected(requireNonNull(reason));
049        }
050
051        static @NonNull AuthorizationCompletionResult fromStoreFailure(OAuthException.@NonNull Reason reason) {
052                return new Failed(requireNonNull(reason));
053        }
054
055        static @NonNull AuthorizationCompletionResult fromAuthorizationError(@NonNull OAuthEndpointError error) {
056                return new RejectedAuthorizationError(requireNonNull(error));
057        }
058        static @NonNull AuthorizationCompletionResult fromEndpoint(@NonNull OAuthErrorResponseException failure) {
059                return new RejectedEndpoint(OAuthEndpointError.fromWireValue(failure.getErrorCode().orElse("")), failure.getStatus());
060        }
061
062        /**
063         * Returns the outcome kind with all values redacted.
064         * @return redacted description
065         * @since 1.0.0
066         */
067        @Override
068        public final @NonNull String toString() {
069                return "AuthorizationCompletionResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}";
070        }
071
072        /**
073         * The authorization flow completed once and returned endpoint tokens.
074         * @author <a href="https://www.revetkn.com">Mark Allen</a>
075         * @since 1.0.0
076         */
077        @Immutable
078        public static final class Succeeded extends AuthorizationCompletionResult {
079                private final @NonNull TokenResponse tokens;
080                private Succeeded(@NonNull TokenResponse tokens) { this.tokens = tokens; }
081
082                /**
083                 * Returns the endpoint tokens; this OAuth operation establishes no OIDC identity.
084                 * @return tokens
085                 * @since 1.0.0
086                 */
087                public @NonNull TokenResponse getTokens() { return this.tokens; }
088        }
089
090        /**
091         * A bound callback reported access_denied after all pending-state and issuer checks.
092         * @author <a href="https://www.revetkn.com">Mark Allen</a>
093         * @since 1.0.0
094         */
095        @Immutable
096        public static final class Denied extends AuthorizationCompletionResult {
097                private Denied() {  }
098        }
099
100        /**
101         * A local callback or pending-state security check rejected completion.
102         * @author <a href="https://www.revetkn.com">Mark Allen</a>
103         * @since 1.0.0
104         */
105        @Immutable
106        public static final class Rejected extends AuthorizationCompletionResult {
107                private final OAuthException.@NonNull Reason reason;
108                private Rejected(OAuthException.@NonNull Reason reason) { this.reason = reason; }
109
110                /**
111                 * Returns the fixed local authorization rejection reason.
112                 * @return reason
113                 * @since 1.0.0
114                 */
115                public OAuthException.@NonNull Reason getReason() { return this.reason; }
116        }
117
118        /**
119         * The pending store did not complete its operation. No token value is released.
120         * @author <a href="https://www.revetkn.com">Mark Allen</a>
121         * @since 1.0.0
122         */
123        @Immutable
124        public static final class Failed extends AuthorizationCompletionResult {
125                private final OAuthException.@NonNull Reason reason;
126                private Failed(OAuthException.@NonNull Reason reason) { this.reason = reason; }
127
128                /**
129                 * Returns the fixed store-failure reason.
130                 * @return reason
131                 * @since 1.0.0
132                 */
133                public OAuthException.@NonNull Reason getReason() { return this.reason; }
134        }
135
136        /**
137         * A bound callback reported an authorization error after all pending-state and issuer checks passed.
138         * @author <a href="https://www.revetkn.com">Mark Allen</a>
139         * @since 1.0.0
140         */
141        @Immutable
142        public static final class RejectedAuthorizationError extends AuthorizationCompletionResult {
143                private final @NonNull OAuthEndpointError error;
144                private RejectedAuthorizationError(@NonNull OAuthEndpointError error) { this.error = requireNonNull(error); }
145                /**
146                 * Returns the fixed authorization error; unknown extension codes share one fallback.
147                 * @return authorization error
148                 * @since 1.0.0
149                 */
150                public @NonNull OAuthEndpointError getError() { return this.error; }
151        }
152        /**
153         * The endpoint returned a non-transient client error. No response body or credential is retained.
154         * @author <a href="https://www.revetkn.com">Mark Allen</a>
155         * @since 1.0.0
156         */
157        @Immutable
158        public static final class RejectedEndpoint extends AuthorizationCompletionResult {
159                private final @NonNull OAuthEndpointError error;
160                private final int status;
161                private RejectedEndpoint(@NonNull OAuthEndpointError error, int status) {
162                        this.error = requireNonNull(error); this.status = status;
163                }
164                /**
165                 * Returns the fixed endpoint error; unrecognized or absent codes use the same fallback.
166                 * @return fixed endpoint error
167                 * @since 1.0.0
168                 */
169                public @NonNull OAuthEndpointError getError() { return this.error; }
170                /**
171                 * Returns the endpoint's HTTP status.
172                 * @return endpoint status
173                 * @since 1.0.0
174                 */
175                public @NonNull Integer getStatus() { return this.status; }
176        }
177}