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}