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 */
016package com.revetsec.saml;
017
018import org.jspecify.annotations.NonNull;
019
020import javax.annotation.concurrent.Immutable;
021
022import static java.util.Objects.requireNonNull;
023
024/**
025 * The outcome of opening or parsing a SAML logout continuity reference. Successful parsing does not authenticate
026 * an identity. Rejections release no reference, submitted value or sealed-state failure details.
027 * A later release may add variants; consuming switches should include a rejecting default branch.
028 *
029 * @author <a href="https://www.revetkn.com">Mark Allen</a>
030 * @since 1.0.0
031 */
032@Immutable
033public abstract sealed class SamlSessionReferenceParseResult permits SamlSessionReferenceParseResult.Succeeded,
034        SamlSessionReferenceParseResult.Rejected, SamlSessionReferenceParseResult.RejectedSealedState {
035    SamlSessionReferenceParseResult() { }
036
037    static @NonNull SamlSessionReferenceParseResult fromReference(@NonNull SamlSessionReference reference) {
038        return new Succeeded(requireNonNull(reference));
039    }
040    static @NonNull SamlSessionReferenceParseResult fromRejection() { return new Rejected(); }
041    static @NonNull SamlSessionReferenceParseResult fromSealedStateRejection() { return new RejectedSealedState(); }
042
043    /**
044     * Returns the outcome kind with all continuity and storage data redacted.
045     * @return redacted description
046     * @since 1.0.0
047     */
048    @Override public final @NonNull String toString() {
049        return "SamlSessionReferenceParseResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}";
050    }
051
052    /**
053     * A structurally parsed continuity reference, not authenticated identity.
054     * @author <a href="https://www.revetkn.com">Mark Allen</a>
055     * @since 1.0.0
056     */
057    @Immutable
058    public static final class Succeeded extends SamlSessionReferenceParseResult {
059        private final @NonNull SamlSessionReference reference;
060        private Succeeded(@NonNull SamlSessionReference reference) { this.reference = reference; }
061        /**
062         * Returns the parsed logout continuity reference.
063         * @return reference, never identity proof
064         * @since 1.0.0
065         */
066        public @NonNull SamlSessionReference getReference() { return this.reference; }
067    }
068
069    /**
070     * The supplied or opened reference has invalid structure.
071     * @author <a href="https://www.revetkn.com">Mark Allen</a>
072     * @since 1.0.0
073     */
074    @Immutable
075    public static final class Rejected extends SamlSessionReferenceParseResult {
076        private Rejected() { }
077        /**
078         * Returns the fixed invalid-reference reason.
079         * @return rejection reason
080         * @since 1.0.0
081         */
082        public @NonNull Reason getReason() { return Reason.INVALID_REFERENCE; }
083    }
084
085    /**
086     * The sealed state did not authenticate for this type, context, keys or lifetime. Invalid and expired values
087     * have the same outcome; no cryptographic failure step or plaintext is exposed.
088     * @author <a href="https://www.revetkn.com">Mark Allen</a>
089     * @since 1.0.0
090     */
091    @Immutable
092    public static final class RejectedSealedState extends SamlSessionReferenceParseResult {
093        private RejectedSealedState() { }
094        /**
095         * Returns the fixed sealed-state rejection reason.
096         * @return rejection reason
097         * @since 1.0.0
098         */
099        public @NonNull Reason getReason() { return Reason.INVALID_SEALED_STATE; }
100    }
101
102    /**
103     * Fixed storage rejection categories containing no supplied data.
104     * @author <a href="https://www.revetkn.com">Mark Allen</a>
105     * @since 1.0.0
106     */
107    @Immutable
108    public enum Reason {
109        /** The supplied or opened continuity reference has invalid structure. */ INVALID_REFERENCE,
110        /** The sealed value could not be opened; no failure step is disclosed. */ INVALID_SEALED_STATE
111    }
112}