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 com.revetsec.ErrorCategory; 020import com.revetsec.RevetsecException; 021import org.jspecify.annotations.NonNull; 022import javax.annotation.concurrent.Immutable; 023import javax.annotation.concurrent.NotThreadSafe; 024import static java.util.Objects.requireNonNull; 025 026/** 027 * A fixed configuration, preparation, storage or runtime failure in RP-Initiated Logout. 028 * No token, input, provider exception, cause or suppressed value is retained. Local session termination remains 029 * the application's responsibility and is never undone by this failure. No automatic retry is performed. 030 * @author <a href="https://www.revetkn.com">Mark Allen</a> 031 * @since 1.0.0 032 */ 033@NotThreadSafe 034public final class OidcLogoutException extends RevetsecException { 035 private static final long serialVersionUID = 1L; 036 /** The fixed reason retained when serialized. */ 037 private final @NonNull Reason reason; 038 private OidcLogoutException(@NonNull Reason reason) { 039 super(requireNonNull(reason).category, reason == Reason.BUDGET_EXHAUSTED || reason == Reason.DISCOVERY_UNAVAILABLE, reason.message, null); 040 this.reason = reason; 041 } 042 static @NonNull OidcLogoutException fromReason(@NonNull Reason reason) { return new OidcLogoutException(reason); } 043 /** Returns the fixed failure reason. 044 * @return reason 045 * @since 1.0.0 046 */ 047 public @NonNull Reason getReason() { return this.reason; } 048 /** 049 * Fixed reasons. Future releases may add reasons; switches should include a rejecting default branch. 050 * @author <a href="https://www.revetkn.com">Mark Allen</a> 051 * @since 1.0.0 052 */ 053 @Immutable 054 public enum Reason { 055 /** No fixed post-logout callback was configured. */ 056 LOGOUT_NOT_CONFIGURED(ErrorCategory.CONFIGURATION, "OIDC logout is not configured."), 057 /** The provider does not advertise the selected logout endpoint. */ 058 END_SESSION_UNSUPPORTED(ErrorCategory.UNSUPPORTED, "The provider does not support the selected logout request."), 059 /** The endpoint failed URI or reserved-parameter policy. */ 060 ENDPOINT_NOT_PERMITTED(ErrorCategory.CONFIGURATION, "The OIDC logout endpoint is not permitted."), 061 /** A hint or authenticated source belongs to a different client or original reference. */ 062 HINT_MISMATCH(ErrorCategory.CONFIGURATION, "The OIDC logout hint does not match the client and original reference."), 063 /** A selected logout representation exceeded its fixed profile. */ 064 INPUT_LIMIT(ErrorCategory.CONFIGURATION, "The OIDC logout value exceeds its selected profile."), 065 /** The configured sealer cannot represent this bounded hint or pending record. */ 066 STORAGE_PROFILE_UNSUPPORTED(ErrorCategory.CONFIGURATION, "The configured storage profile cannot represent OIDC logout state."), 067 /** A trusted clock, entropy, policy or sealing provider could not complete the operation. */ 068 PROVIDER_UNAVAILABLE(ErrorCategory.CONFIGURATION, "The OIDC logout operation is unavailable."), 069 /** A transport or held-back discovery attempt did not complete. */ 070 DISCOVERY_UNAVAILABLE(ErrorCategory.TRANSPORT, "OIDC logout discovery is unavailable."), 071 /** A store call may have consumed the pending record; safe retry is not established. */ 072 STORE_INDETERMINATE(ErrorCategory.CONFIGURATION, "The OIDC logout store outcome is indeterminate."), 073 /** The original operation budget is exhausted. */ 074 BUDGET_EXHAUSTED(ErrorCategory.TRANSPORT, "The OIDC logout budget is exhausted."), 075 /** The calling thread remains interrupted. */ 076 INTERRUPTED(ErrorCategory.TRANSPORT, "The OIDC logout operation was interrupted."); 077 private final @NonNull ErrorCategory category; 078 private final @NonNull String message; 079 Reason(@NonNull ErrorCategory category, @NonNull String message) { this.category = category; this.message = message; } 080 } 081}