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.oauth; 018 019import org.jspecify.annotations.NonNull; 020import com.google.errorprone.annotations.CheckReturnValue; 021 022import javax.annotation.concurrent.ThreadSafe; 023import java.time.Instant; 024import java.time.Duration; 025import java.util.Optional; 026 027/** 028 * Storage for opaque, browser-bound pending authorization records. A shared implementation must make 029 * {@link #consume(String, String, Duration)} atomic across all participating nodes: a record is returned at most once, even 030 * when callbacks race. The browser binding and state are lookup inputs, not an excuse to omit Revetsec's structural, 031 * purpose, client, issuer, callback, time and binding checks after a record is consumed. Store-mode records are 032 * plaintext JSON containing sensitive PKCE/nonce/application state; their unkeyed binding digest is not a MAC. 033 * The implementation must provide confidentiality and integrity for records and browser bindings through trusted 034 * storage/access controls (and authenticated protected transport where remote). An attacker-controlled store can 035 * rewrite a record and recompute its digest; these checks do not authenticate such storage. A durable shared store is required for client-side single use across nodes or 036 * restarts; {@link InMemoryPendingAuthorizationStore} covers one process only. 037 * <p> 038 * This low-level backend SPI deliberately retains opaque {@link String} lookup fields for existing store framing. 039 * Application-facing pending save/source APIs require {@link com.revetsec.BrowserBinding}; a store implementation 040 * must not interpret the raw SPI spelling as identity, authorization or authenticated request provenance. 041 * 042 * @author <a href="https://www.revetkn.com">Mark Allen</a> 043 * @since 1.0.0 044 */ 045@ThreadSafe 046public interface PendingAuthorizationStore { 047 /** 048 * Saves with a five-second local convenience budget. Applications with an operation deadline should use the 049 * budget-aware overload. 050 * @param browserBinding browser-specific secret 051 * @param state authorization state 052 * @param opaqueRecord opaque Revetsec record 053 * @param expiresAt exact expiry 054 * @return the fixed storage outcome 055 * @since 1.0.0 056 */ 057 @CheckReturnValue 058 default @NonNull PendingAuthorizationSaveResult save(@NonNull String browserBinding, @NonNull String state, @NonNull String opaqueRecord, 059 @NonNull Instant expiresAt) { 060 return save(browserBinding, state, opaqueRecord, expiresAt, Duration.ofSeconds(5)); 061 } 062 063 /** 064 * Saves one trusted opaque record until its exact supplied expiry without replacing a live binding and state. 065 * Return ALREADY_PRESENT for a live duplicate and CAPACITY_REFUSED without evicting live records. 066 * UNAVAILABLE promises that no record was saved. A possibly completed write must return INDETERMINATE; 067 * callers must not infer that a retry is safe. 068 * 069 * @param browserBinding an application-generated, browser-specific secret 070 * @param state the authorization state 071 * @param opaqueRecord a record produced by Revetsec, never interpreted by the store 072 * @param expiresAt the exact expiry supplied by Revetsec 073 * @param remaining positive time left for this call; the store must not wait beyond it 074 * @return the fixed storage outcome 075 * @since 1.0.0 076 */ 077 @CheckReturnValue 078 @NonNull PendingAuthorizationSaveResult save(@NonNull String browserBinding, @NonNull String state, @NonNull String opaqueRecord, 079 @NonNull Instant expiresAt, @NonNull Duration remaining); 080 081 /** 082 * Consumes with a five-second local convenience budget. Callback completion uses its own shrinking deadline. 083 * @param browserBinding browser-specific secret 084 * @param state authorization state 085 * @return removed record or empty 086 * @since 1.0.0 087 */ 088 default @NonNull Optional<@NonNull String> consume(@NonNull String browserBinding, @NonNull String state) { 089 return consume(browserBinding, state, Duration.ofSeconds(5)); 090 } 091 092 /** 093 * Atomically removes and returns one matching record. A consumed record is never returned again. 094 * 095 * @param browserBinding the browser-specific binding 096 * @param state the authorization state 097 * @param remaining positive time left for this call; an uncertain removal must fail closed 098 * @return the removed record, or empty when absent or expired 099 * @since 1.0.0 100 */ 101 @NonNull Optional<@NonNull String> consume(@NonNull String browserBinding, @NonNull String state, 102 @NonNull Duration remaining); 103}