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}