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;
022
023/**
024 * A correlated browser return or fixed rejection. Returned proves only correlation; it establishes neither
025 * authenticated identity nor termination of every provider session. A sealed cookie has no atomic concurrent
026 * single-use guarantee; a shared atomic store's contract and qualification remain application responsibilities.
027 * Future releases may add variants; consuming switches should include a rejecting default branch.
028 * @author <a href="https://www.revetkn.com">Mark Allen</a>
029 * @since 1.0.0
030 */
031@Immutable
032public abstract sealed class OidcLogoutResult permits OidcLogoutResult.Returned, OidcLogoutResult.Rejected {
033        private OidcLogoutResult() { }
034        static @NonNull OidcLogoutResult returned() { return new Returned(); }
035        static @NonNull OidcLogoutResult rejected(@NonNull Reason reason) { return new Rejected(requireNonNull(reason)); }
036        /** Redacts correlation data.
037         * @return redacted description
038         * @since 1.0.0
039         */
040        @Override public final @NonNull String toString() { return "OidcLogoutResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}"; }
041        /**
042         * Correlation succeeded. No identity, credential, redirect target or provider-session termination proof is released.
043         * @author <a href="https://www.revetkn.com">Mark Allen</a>
044         * @since 1.0.0
045         */
046        @Immutable
047        public static final class Returned extends OidcLogoutResult { private Returned() { } }
048        /**
049         * The callback did not satisfy the selected correlation profile.
050         * @author <a href="https://www.revetkn.com">Mark Allen</a>
051         * @since 1.0.0
052         */
053        @Immutable
054        public static final class Rejected extends OidcLogoutResult {
055                private final @NonNull Reason reason;
056                private Rejected(@NonNull Reason reason) { this.reason = reason; }
057                /** Returns the fixed rejection reason.
058                 * @return reason
059                 * @since 1.0.0
060                 */
061                public @NonNull Reason getReason() { return this.reason; }
062        }
063        /**
064         * Value-free callback rejection reasons. Later releases may add reasons.
065         * @author <a href="https://www.revetkn.com">Mark Allen</a>
066         * @since 1.0.0
067         */
068        @Immutable
069        public enum Reason {
070                /** The return query is outside the selected state-only grammar. */ MALFORMED_RETURN,
071                /** The trusted actual callback differs from the configured callback. */ CALLBACK_MISMATCH,
072                /** No matching pending record was available. */ PENDING_NOT_FOUND,
073                /** The pending record is malformed, wrongly typed or outside its creation interval. */ PENDING_INVALID,
074                /** The exact pending expiry has been reached. */ PENDING_EXPIRED,
075                /** The returned state differs from the pending state. */ STATE_MISMATCH,
076                /** The browser binding differs from the record's binding. */ BROWSER_BINDING_MISMATCH,
077                /** The pending client, issuer or callback differs from this client. */ CLIENT_MISMATCH
078        }
079}