Interface ApiKeyStore

All Known Implementing Classes:
InMemoryApiKeyStore
@ExperimentalJSentinelApi public interface ApiKeyStore
Persistent store for ApiKeyRecords — backs the planned API-key authentication flow (V00.70 Phase 7b).

Keys are looked up by their hash; the plain value never enters the store. Revoked and expired records remain visible to findByHash(String) so the auth flow can distinguish "known but rejected" from "unknown".

Implementations must be thread-safe.

  • Method Details

    • findByHash

      Optional<ApiKeyRecord> findByHash(String keyHash)
      Looks up an API-key record by its hash.
      Parameters:
      keyHash - key hash; must not be null or blank
      Returns:
      the record, if present

    • save

      void save(ApiKeyRecord record)
      Persists or replaces the supplied record. Keyed on ApiKeyRecord.keyHash().
      Parameters:
      record - record to persist; must not be null

    • listBySubject

      List<ApiKeyRecord> listBySubject(TenantId tenant, SubjectId subjectId)
      Returns every record (active, revoked, or expired) belonging to subjectId within tenant, in insertion order (oldest first). Used by an "manage my API keys" UI.
      Parameters:
      tenant - tenant scope; must not be null
      subjectId - subject; must not be null
      Returns:
      immutable list of records; empty when none exist

    • markUsed

      boolean markUsed(String keyHash, Instant at)
      Updates the ApiKeyRecord.lastUsedAt() timestamp of the record for keyHash.
      Parameters:
      keyHash - key hash; must not be null or blank
      at - instant of use; must not be null
      Returns:
      true if the record existed and was updated, false when no such key existed

    • revoke

      boolean revoke(String keyHash, Instant at)
      Marks the record for keyHash revoked at at. No-op on an already-revoked record.
      Parameters:
      keyHash - key hash; must not be null or blank
      at - instant of revocation; must not be null
      Returns:
      true if a not-yet-revoked record was marked, false when no such key existed or when it was already revoked

    • deleteByHash

      boolean deleteByHash(String keyHash)
      Removes the record for keyHash.
      Parameters:
      keyHash - key hash; must not be null or blank
      Returns:
      true when a record was removed

    • purgeExpired

      int purgeExpired(Instant now)
      Drops every record whose ApiKeyRecord.expiresAt() is at or before now.
      Parameters:
      now - retention boundary; must not be null
      Returns:
      number of records purged