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}