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}