Interface PendingAuthorizationStore

All Known Implementing Classes:
InMemoryPendingAuthorizationStore

Storage for opaque, browser-bound pending authorization records. A shared implementation must make consume(String, String, Duration) atomic across all participating nodes: a record is returned at most once, even when callbacks race. The browser binding and state are lookup inputs, not an excuse to omit Revetsec's structural, purpose, client, issuer, callback, time and binding checks after a record is consumed. Store-mode records are plaintext JSON containing sensitive PKCE/nonce/application state; their unkeyed binding digest is not a MAC. The implementation must provide confidentiality and integrity for records and browser bindings through trusted storage/access controls (and authenticated protected transport where remote). An attacker-controlled store can 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 restarts; InMemoryPendingAuthorizationStore covers one process only.

This low-level backend SPI deliberately retains opaque String lookup fields for existing store framing. Application-facing pending save/source APIs require BrowserBinding; a store implementation must not interpret the raw SPI spelling as identity, authorization or authenticated request provenance.

Since:
1.0.0
Author:
Mark Allen
  • Method Details

    • save

      @CheckReturnValue default @NonNull PendingAuthorizationSaveResult save(@NonNull String browserBinding, @NonNull String state, @NonNull String opaqueRecord, @NonNull Instant expiresAt)
      Saves with a five-second local convenience budget. Applications with an operation deadline should use the budget-aware overload.
      Parameters:
      browserBinding - browser-specific secret
      state - authorization state
      opaqueRecord - opaque Revetsec record
      expiresAt - exact expiry
      Returns:
      the fixed storage outcome
      Since:
      1.0.0
    • save

      @CheckReturnValue @NonNull PendingAuthorizationSaveResult save(@NonNull String browserBinding, @NonNull String state, @NonNull String opaqueRecord, @NonNull Instant expiresAt, @NonNull Duration remaining)
      Saves one trusted opaque record until its exact supplied expiry without replacing a live binding and state. Return ALREADY_PRESENT for a live duplicate and CAPACITY_REFUSED without evicting live records. UNAVAILABLE promises that no record was saved. A possibly completed write must return INDETERMINATE; callers must not infer that a retry is safe.
      Parameters:
      browserBinding - an application-generated, browser-specific secret
      state - the authorization state
      opaqueRecord - a record produced by Revetsec, never interpreted by the store
      expiresAt - the exact expiry supplied by Revetsec
      remaining - positive time left for this call; the store must not wait beyond it
      Returns:
      the fixed storage outcome
      Since:
      1.0.0
    • consume

      default @NonNull Optional<@NonNull String> consume(@NonNull String browserBinding, @NonNull String state)
      Consumes with a five-second local convenience budget. Callback completion uses its own shrinking deadline.
      Parameters:
      browserBinding - browser-specific secret
      state - authorization state
      Returns:
      removed record or empty
      Since:
      1.0.0
    • consume

      Atomically removes and returns one matching record. A consumed record is never returned again.
      Parameters:
      browserBinding - the browser-specific binding
      state - the authorization state
      remaining - positive time left for this call; an uncertain removal must fail closed
      Returns:
      the removed record, or empty when absent or expired
      Since:
      1.0.0