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.saml; 018 019import org.jspecify.annotations.NonNull; 020 021import javax.annotation.concurrent.ThreadSafe; 022import javax.annotation.concurrent.Immutable; 023import java.time.Duration; 024import java.time.Instant; 025import java.util.Objects; 026 027/** 028 * Atomic SAML assertion replay admission. A shared implementation must make one key visible to all nodes before 029 * reporting {@link MarkResult#MARKED}; an uncertain write must report {@link MarkResult#INDETERMINATE}. The key is a 030 * SHA-256, URL-safe encoding of length-prefixed SP, connection, IdP and assertion identifiers, not raw identity data. 031 * Live entries must not be evicted to make room. This interface never validates an assertion by itself. 032 * 033 * @since 1.0.0 034 */ 035@ThreadSafe 036public interface SamlReplayCache { 037 /** 038 * Atomically admit a previously unseen key until its final possible acceptance time across 039 * supported request bindings and time policies. A backend must retain the key through the 040 * supplied absolute expiry without rounding that expiry down. 041 * 042 * @param key the Revetsec-generated replay key 043 * @param expiresAt the final possible acceptance time across supported completion contexts 044 * @param remaining positive time budget for this operation 045 * @return an explicit outcome; only MARKED permits identity release 046 * @since 1.0.0 047 */ 048 @NonNull MarkResult markIfAbsent(@NonNull String key, @NonNull Instant expiresAt, 049 @NonNull Duration remaining); 050 051 /** 052 * Atomically admit a replay key within a connection's capacity namespace. The key 053 * itself already binds the connection, SP and IdP identifiers. Implementations 054 * shared by mutually untrusted IdP connections should override this method and 055 * reserve capacity per connection. The default preserves source compatibility 056 * for existing stores but supplies no such capacity isolation. 057 * 058 * @param connectionId application-approved IdP connection namespace 059 * @param key the Revetsec-generated replay key 060 * @param expiresAt the final possible acceptance time 061 * @param remaining positive time budget 062 * @return an explicit atomic outcome 063 * @since 1.0.0 064 */ 065 default @NonNull MarkResult markIfAbsent(@NonNull String connectionId, @NonNull String key, 066 @NonNull Instant expiresAt, @NonNull Duration remaining) { 067 if (Objects.requireNonNull(connectionId).isEmpty()) 068 throw new IllegalArgumentException("Empty SAML connection namespace"); 069 return markIfAbsent(key, expiresAt, remaining); 070 } 071 072 /** 073 * Outcomes of an atomic replay admission. A retry after INDETERMINATE cannot be interpreted as fresh. 074 * 075 * @since 1.0.0 076 */ 077 @Immutable 078 enum MarkResult { 079 /** This call atomically established the replay fence. */ MARKED, 080 /** The key was already fenced. */ ALREADY_PRESENT, 081 /** The cache cannot accept another live record. */ CAPACITY_REFUSED, 082 /** The cache could not attempt the write. */ UNAVAILABLE, 083 /** The backend may or may not have completed the write. */ INDETERMINATE 084 } 085}