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.OAuthEndpointError; 023import com.revetsec.oauth.OAuthErrorResponseException; 024import com.revetsec.jose.JoseException; 025import org.jspecify.annotations.Nullable; 026import java.util.Optional; 027 028/** 029 * The outcome of a UserInfo request. 030 * Local validation and non-transient endpoint client errors return fixed rejections. Transport, metadata, 031 * malformed endpoint responses, transient endpoint failures and invalid HMAC configuration remain exceptions. 032 * Applications receive outcomes from the operation and cannot construct them. A later release may add variants; 033 * consuming switches should include a rejecting default branch. 034 * @author <a href="https://www.revetkn.com">Mark Allen</a> 035 * @since 1.0.0 036 */ 037@Immutable 038public abstract sealed class OidcUserInfoResult permits OidcUserInfoResult.Succeeded, OidcUserInfoResult.Rejected, OidcUserInfoResult.RejectedEndpoint { 039 OidcUserInfoResult() { } 040 static @NonNull OidcUserInfoResult fromUserInfo(@NonNull OidcUserInfo value) { return new Succeeded(requireNonNull(value)); } 041 static @NonNull OidcUserInfoResult fromRejection(@NonNull OidcValidationException failure) { 042 return new Rejected(failure.getReason(), failure.getJoseReason().orElse(null)); 043 } 044 static @NonNull OidcUserInfoResult fromEndpoint(@NonNull OAuthErrorResponseException failure) { 045 return new RejectedEndpoint(OAuthEndpointError.fromWireValue(failure.getErrorCode().orElse("")), failure.getStatus()); 046 } 047 /** 048 * Returns the outcome kind with all values redacted. 049 * @return redacted description 050 * @since 1.0.0 051 */ 052 @Override 053 public final @NonNull String toString() { 054 return "OidcUserInfoResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}"; 055 } 056 /** 057 * The UserInfo response passed all configured identity and profile checks. 058 * @author <a href="https://www.revetkn.com">Mark Allen</a> 059 * @since 1.0.0 060 */ 061 @Immutable 062 public static final class Succeeded extends OidcUserInfoResult { 063 private final @NonNull OidcUserInfo value; 064 private Succeeded(@NonNull OidcUserInfo value) { this.value = requireNonNull(value); } 065 /** 066 * Returns the value released after all operation checks passed. 067 * @return checked value 068 * @since 1.0.0 069 */ 070 public @NonNull OidcUserInfo getUserInfo() { return this.value; } 071 } 072 /** 073 * A local OIDC check rejected the operation. No identity, claim or token value is released. 074 * @author <a href="https://www.revetkn.com">Mark Allen</a> 075 * @since 1.0.0 076 */ 077 @Immutable 078 public static final class Rejected extends OidcUserInfoResult { 079 private final OidcValidationException.@NonNull Reason reason; 080 private final JoseException.@Nullable Reason joseReason; 081 private Rejected(OidcValidationException.@NonNull Reason reason, JoseException.@Nullable Reason joseReason) { 082 this.reason = requireNonNull(reason); this.joseReason = joseReason; 083 } 084 /** 085 * Returns the fixed OIDC rejection reason. 086 * @return rejection reason 087 * @since 1.0.0 088 */ 089 public OidcValidationException.@NonNull Reason getReason() { return this.reason; } 090 /** 091 * Returns the fixed lower-layer reason when JOSE rejected the input. 092 * @return optional JOSE reason 093 * @since 1.0.0 094 */ 095 public @NonNull Optional<JoseException.@NonNull Reason> getJoseReason() { 096 return Optional.ofNullable(this.joseReason); 097 } 098 } 099 /** 100 * The endpoint returned a non-transient client error. No response body or credential is retained. 101 * @author <a href="https://www.revetkn.com">Mark Allen</a> 102 * @since 1.0.0 103 */ 104 @Immutable 105 public static final class RejectedEndpoint extends OidcUserInfoResult { 106 private final @NonNull OAuthEndpointError error; 107 private final int status; 108 private RejectedEndpoint(@NonNull OAuthEndpointError error, int status) { 109 this.error = requireNonNull(error); this.status = status; 110 } 111 /** 112 * Returns the fixed endpoint error; unrecognized or absent codes use the same fallback. 113 * @return fixed endpoint error 114 * @since 1.0.0 115 */ 116 public @NonNull OAuthEndpointError getError() { return this.error; } 117 /** 118 * Returns the endpoint's HTTP status. 119 * @return endpoint status 120 * @since 1.0.0 121 */ 122 public @NonNull Integer getStatus() { return this.status; } 123 } 124}