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 * The outcome of parsing a stored OIDC continuity reference. A parsed reference is not identity proof.
025 * Invalid structure and invalid sealed state release no reference or failure details.
026 * A later release may add variants; consuming switches should include a rejecting default branch.
027 * @author <a href="https://www.revetkn.com">Mark Allen</a>
028 * @since 1.0.0
029 */
030@Immutable
031public abstract sealed class OidcSessionReferenceParseResult permits OidcSessionReferenceParseResult.Succeeded,
032                OidcSessionReferenceParseResult.Rejected {
033        OidcSessionReferenceParseResult() { }
034        static @NonNull OidcSessionReferenceParseResult fromReference(@NonNull OidcSessionReference reference) {
035                return new Succeeded(requireNonNull(reference));
036        }
037        static @NonNull OidcSessionReferenceParseResult fromRejection() { return new Rejected(); }
038        /**
039         * Returns a description with all reference data redacted.
040         * @return redacted description
041         * @since 1.0.0
042         */
043        @Override public final @NonNull String toString() {
044                return "OidcSessionReferenceParseResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}";
045        }
046        /**
047         * A structurally valid continuity reference was parsed. It supplies no authenticated identity.
048         * @author <a href="https://www.revetkn.com">Mark Allen</a>
049         * @since 1.0.0
050         */
051        @Immutable
052        public static final class Succeeded extends OidcSessionReferenceParseResult {
053                private final @NonNull OidcSessionReference reference;
054                private Succeeded(@NonNull OidcSessionReference reference) { this.reference = reference; }
055                /**
056                 * Returns the parsed continuity reference.
057                 * @return reference, not authenticated identity
058                 * @since 1.0.0
059                 */
060                public @NonNull OidcSessionReference getReference() { return this.reference; }
061        }
062        /**
063         * The stored reference could not be parsed or opened. No reference is released.
064         * @author <a href="https://www.revetkn.com">Mark Allen</a>
065         * @since 1.0.0
066         */
067        @Immutable
068        public static final class Rejected extends OidcSessionReferenceParseResult {
069                private Rejected() { }
070                /**
071                 * Returns the fixed reference-rejection reason.
072                 * @return rejection reason
073                 * @since 1.0.0
074                 */
075                public OidcValidationException.@NonNull Reason getReason() {
076                        return OidcValidationException.Reason.SESSION_REFERENCE_INVALID;
077                }
078        }
079}