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}