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; 020import javax.annotation.concurrent.ThreadSafe; 021import java.time.Duration; 022import java.time.Instant; 023import java.util.function.Predicate; 024 025/** 026 * Atomic storage for browser-bound SAML login and logout attempts. A shared implementation must consume a 027 * record at most once across all nodes. The record is sealed by Revetsec and is opaque to the 028 * provider. A process-local provider is suitable only for a single node. 029 * <p> 030 * This low-level backend SPI deliberately retains opaque {@link String} lookup fields for exact existing store 031 * framing, including retained SAML spellings. Application-facing pending save/source APIs require 032 * {@link com.revetsec.BrowserBinding}; the SPI value is not identity, authorization or authenticated request 033 * provenance. 034 * 035 * @since 1.0.0 036 */ 037@ThreadSafe 038public interface PendingSamlAuthenticationStore { 039 /** 040 * Saves a fresh record without replacing a live record with the same binding and handle. 041 * 042 * @param browserBinding browser-specific secret 043 * @param relayStateHandle generated opaque lookup handle 044 * @param sealedRecord Revetsec-sealed record 045 * @param expiresAt exact expiry 046 * @param remaining positive operation budget 047 * @return the save outcome 048 * @since 1.0.0 049 */ 050 @NonNull SamlPendingSaveResult save(@NonNull String browserBinding, @NonNull String relayStateHandle, 051 @NonNull String sealedRecord, @NonNull Instant expiresAt, @NonNull Duration remaining); 052 053 /** 054 * Atomically removes and returns one matching record. An uncertain removal is indeterminate. 055 * 056 * @param browserBinding browser-specific secret 057 * @param relayStateHandle generated opaque lookup handle 058 * @param remaining positive operation budget 059 * @return the consume outcome 060 * @since 1.0.0 061 */ 062 @NonNull SamlPendingConsumeResult consume(@NonNull String browserBinding, @NonNull String relayStateHandle, 063 @NonNull Duration remaining); 064 065 /** 066 * Validates one live sealed record before atomically removing that same record. The predicate 067 * must accept the exact record returned by a successful consume; a replacement record must 068 * be validated separately. A false predicate returns {@link SamlPendingConsumeResult.Missing} 069 * without removing the record. A predicate exception or exhausted operation budget returns 070 * {@link SamlPendingConsumeResult.Unavailable} without removal. An uncertain removal is 071 * indeterminate. 072 * <p> 073 * The default implementation returns unavailable without reading, validating or consuming 074 * state. Implementations must supply an atomic conditional consume to support this operation; 075 * falling back to {@link #consume(String, String, Duration)} cannot preserve rejected state. 076 * Logout completion requires this operation and fails closed until the store overrides it. 077 * The predicate should perform only bounded validation and must not mutate store state. 078 * 079 * @param browserBinding browser-specific secret 080 * @param relayStateHandle generated opaque lookup handle 081 * @param sealedRecordMatches validation of the exact live sealed record 082 * @param remaining positive budget including validation and removal 083 * @return conditional consume outcome 084 * @since 1.0.0 085 */ 086 default @NonNull SamlPendingConsumeResult consumeIfMatches(@NonNull String browserBinding, 087 @NonNull String relayStateHandle, @NonNull Predicate<@NonNull String> sealedRecordMatches, 088 @NonNull Duration remaining) { 089 return SamlPendingConsumeResult.Unavailable.INSTANCE; 090 } 091}