@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/secrets-provider-binding.ts

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Scope } from '@kindgi/platform';
+import type { EnvName, Result } from '@kindgi/types';
+
+/**
+ * Adapter surface below `SecretBinding`. External-secret-manager
+ * deployments plug this in behind a secrets router (a thin
+ * `SecretBinding` implementation that delegates every method to a
+ * wired provider). Provider adapter packages MUST ship under
+ * a secrets-provider adapter naming for discoverability.
+ *
+ * Provider adapters MUST NOT emit compliance-evidence events
+ * themselves — the `SecretBinding` router owns that. Adapters are
+ * dumb translators between the framework's uniform surface and the
+ * provider's native API.
+ */
+export interface SecretProviderBinding {
+  readonly providerName: string;
+  getSecret(
+    input: SecretProviderGetInput,
+  ): Promise<Result<SecretProviderPayload | null, SecretProviderError>>;
+  getSecretVersion(
+    input: SecretProviderGetVersionInput,
+  ): Promise<Result<SecretProviderPayload | null, SecretProviderError>>;
+  listSecrets(
+    input: SecretProviderListInput,
+  ): Promise<Result<SecretProviderListOutput, SecretProviderError>>;
+  putSecret(
+    input: SecretProviderPutInput,
+  ): Promise<Result<SecretProviderPutOutput, SecretProviderError>>;
+  rotateSecret(
+    input: SecretProviderRotateInput,
+  ): Promise<Result<SecretProviderRotateOutput, SecretProviderError>>;
+  deleteSecret(
+    input: SecretProviderDeleteInput,
+  ): Promise<Result<SecretProviderDeleteOutput, SecretProviderError>>;
+  probe(): Promise<Result<SecretProviderProbeOutput, SecretProviderError>>;
+}
+
+/**
+ * How the provider knows which scope + env to talk to. Three
+ * strategies (mode governs provider-instance sharing; `scope` carries
+ * the full discriminated `Scope` from `@kindgi/platform` for
+ * path-encoding):
+ *
+ *   - `mode: 'shared-provider'` — one provider instance for all
+ *     tenants + envs; adapter encodes scope + env into `name`
+ *     (e.g. Vault: `secret/data/<scopeKind>/<tenantId>/<orgId|projectId|_>/<envName>/<name>`).
+ *   - `mode: 'per-tenant-provider'` — provider constructed per
+ *     tenant; adapter encodes scope-level (org/project id) + env.
+ *   - `mode: 'per-tenant-env-provider'` — provider constructed per
+ *     (tenant, env) pair; adapter still encodes scope-level
+ *     (org/project) into `name` when non-tenant. For providers with a
+ *     native `environment` concept (env dimension only).
+ *
+ * Scope-hierarchy resolution is done framework-side by the
+ * `SecretBinding` router BEFORE delegating to a provider — each
+ * `Provider*Input` call targets exactly one scope level. Providers
+ * do not walk the hierarchy.
+ *
+ * `SecretProviderScope` carries the full discriminated `Scope`
+ * primitive, not just `tenantId`.
+ */
+export type SecretProviderScope =
+  | {
+      readonly mode: 'shared-provider';
+      readonly scope: Scope;
+      readonly envName: EnvName;
+      readonly namespace?: string;
+    }
+  | { readonly mode: 'per-tenant-provider'; readonly scope: Scope; readonly envName: EnvName }
+  | { readonly mode: 'per-tenant-env-provider'; readonly scope: Scope; readonly envName: EnvName };
+
+export interface SecretProviderGetInput {
+  readonly providerScope: SecretProviderScope;
+  readonly name: string;
+}
+
+export interface SecretProviderGetVersionInput {
+  readonly providerScope: SecretProviderScope;
+  readonly name: string;
+  readonly versionId: number;
+}
+
+export interface SecretProviderPayload {
+  readonly name: string;
+  readonly versionId: number;
+  readonly createdAt: string;
+  readonly value: string;
+}
+
+export interface SecretProviderListInput {
+  readonly providerScope: SecretProviderScope;
+  readonly namePrefix?: string;
+  readonly cursor?: string;
+  readonly limit: number;
+}
+
+export interface SecretProviderListOutput {
+  readonly data: readonly SecretProviderMetadata[];
+  readonly nextCursor?: string;
+}
+
+export interface SecretProviderMetadata {
+  readonly name: string;
+  readonly currentVersion: number;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly revokedAt?: string;
+}
+
+export interface SecretProviderPutInput {
+  readonly providerScope: SecretProviderScope;
+  readonly name: string;
+  readonly value: string;
+  readonly writeMode: 'create-new' | 'add-version';
+}
+
+export type SecretProviderPutOutput =
+  | { readonly kind: 'ok'; readonly versionId: number; readonly createdAt: string }
+  | { readonly kind: 'already-exists' }
+  | { readonly kind: 'version-conflict'; readonly currentVersion: number };
+
+export interface SecretProviderRotateInput {
+  readonly providerScope: SecretProviderScope;
+  readonly name: string;
+  readonly newValue?: string;
+  readonly revokeOldAfterMs?: number;
+}
+
+export type SecretProviderRotateOutput =
+  | { readonly kind: 'ok'; readonly newVersionId: number; readonly oldVersionId: number }
+  | { readonly kind: 'rotation-pending'; readonly resumeToken: string };
+
+export interface SecretProviderDeleteInput {
+  readonly providerScope: SecretProviderScope;
+  readonly name: string;
+  readonly hard: boolean;
+}
+
+export interface SecretProviderDeleteOutput {
+  readonly deleted: boolean;
+}
+
+export interface SecretProviderProbeOutput {
+  readonly reachable: true;
+  readonly providerVersion?: string;
+  readonly latencyMs?: number;
+}
+
+/**
+ * Uniform error shape across every provider adapter. Adapters map
+ * their native failure conditions to these codes; the router
+ * translates them further into `SecretError` codes.
+ */
+export type SecretProviderError =
+  | { readonly code: 'unreachable'; readonly message: string; readonly cause?: unknown }
+  | { readonly code: 'unauthorized'; readonly message: string; readonly cause?: unknown }
+  | {
+      readonly code: 'rate-limited';
+      readonly message: string;
+      readonly retryAfterMs?: number;
+    }
+  | { readonly code: 'unsupported'; readonly message: string; readonly feature: string }
+  | { readonly code: 'provider-error'; readonly message: string; readonly cause?: unknown };

package/src/session-store-binding.ts

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Cursor, SessionId, TenantId, Timestamp, UserId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for OAuth/OIDC session persistence. Same
+ * pattern as `TokenAdmin` (write path for bearer tokens) — the API
+ * package does NOT own session persistence. Deployments plug in a
+ * durable store.
+ *
+ * Sessions are the byproduct of a successful OAuth callback:
+ * `POST /v1/auth/callback/:providerId` exchanges the authorization code
+ * for provider tokens, fetches the userinfo, and calls
+ * `SessionStoreBinding.create` to persist the resulting session; the
+ * route then hands the caller an opaque framework-issued token
+ * (`kgi_sk_<sessionId>`) that never leaks the provider access-token or
+ * refresh-token to the client.
+ *
+ * The bearer-auth middleware routes session-token requests through
+ * `get(tenantId, sessionId)`; the resolver hot path runs on every
+ * authenticated request that carries a session token, so implementations
+ * SHOULD keep `get` cheap (e.g. a single indexed lookup by id and
+ * expiry, or a cache).
+ */
+export interface SessionStoreBinding {
+  create(input: SessionCreateInput): Promise<SessionCreateOutput>;
+  get(input: SessionGetInput): Promise<Session | null>;
+  list(input: SessionListInput): Promise<SessionPage>;
+  revoke(input: SessionRevokeInput): Promise<SessionRevokeOutcome>;
+  revokeAllForUser(input: SessionRevokeAllForUserInput): Promise<SessionRevokeAllForUserOutcome>;
+  /**
+   * Update the session's `lastActiveAt` marker. Called by the auth
+   * middleware on each successful authenticated request (throttled, by
+   * default to at most once per minute per session, so the write path
+   * doesn't hot-spot under load). Absent = the middleware only enforces absolute
+   * TTL; inactivity timeout is disabled.
+   *
+   * The tenant sentinel `MULTI_TENANT_LOOKUP` is honored the same way
+   * as `get` — the middleware doesn't know the tenant ahead of time.
+   */
+  readonly touch?: (input: SessionTouchInput) => Promise<SessionTouchOutcome>;
+}
+
+export interface SessionCreateInput {
+  readonly tenantId: TenantId;
+  readonly userId: UserId;
+  /** ProviderId of the `IdentityProviderBinding` that authenticated the user. */
+  readonly providerId: string;
+  /** Opaque provider access-token — server-side only. */
+  readonly accessToken: string;
+  /** Opaque provider refresh-token — server-side only, may be absent. */
+  readonly refreshToken?: string;
+  readonly expiresAt: Timestamp;
+  readonly scopes: readonly string[];
+  /** Free-form provider claims (e.g. `email`, `name`, `sub`). */
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface SessionCreateOutput {
+  readonly sessionId: SessionId;
+  readonly expiresAt: Timestamp;
+}
+
+export interface SessionGetInput {
+  readonly tenantId: TenantId;
+  readonly sessionId: SessionId;
+}
+
+export interface SessionListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /** Filter to sessions for a single user. Absent → all users in tenant. */
+  readonly userId?: UserId;
+}
+
+export interface SessionRevokeInput {
+  readonly tenantId: TenantId;
+  readonly sessionId: SessionId;
+  /**
+   * Distinguishes an explicit revoke (user logout, admin action) from
+   * a rotation (`POST /v1/auth/refresh` retiring the old session). The
+   * adapter uses this to set both `revokedAt` AND `rotatedAt` on the
+   * session so the middleware can return `401 refresh-token-invalid` when
+   * the OLD session token is reused after rotation. Defaults to
+   * `'revoke'`.
+   */
+  readonly reason?: 'revoke' | 'rotate';
+}
+
+export interface SessionRevokeAllForUserInput {
+  readonly tenantId: TenantId;
+  readonly userId: UserId;
+}
+
+export interface Session {
+  readonly id: SessionId;
+  readonly tenantId: TenantId;
+  readonly userId: UserId;
+  readonly providerId: string;
+  readonly accessToken: string;
+  readonly refreshToken?: string;
+  readonly expiresAt: Timestamp;
+  readonly scopes: readonly string[];
+  readonly metadata?: Record<string, unknown>;
+  readonly createdAt: Timestamp;
+  /**
+   * Last-observed activity timestamp. Populated by adapters that
+   * implement `touch()` — the middleware bumps it (throttled) on each
+   * authenticated request so the deployment can enforce an
+   * inactivity-based logout independent of the absolute session TTL.
+   *
+   * Adapters MAY leave this undefined when the deployment has opted
+   * out of inactivity tracking; in that case the middleware skips the
+   * inactivity check and enforces only absolute TTL.
+   */
+  readonly lastActiveAt?: Timestamp;
+  /**
+   * Set by `POST /v1/auth/refresh` on the OLD session when it mints a
+   * new one. Distinguishes rotation (client should retry with the
+   * fresh token — OAuth 2.1 BCP refresh-token reuse detection) from
+   * an explicit revocation (user logged out). The middleware surfaces
+   * this via `401 refresh-token-invalid` vs `401 auth-revoked`. Set
+   * atomically with `revokedAt`.
+   */
+  readonly rotatedAt?: Timestamp;
+  readonly revokedAt?: Timestamp;
+}
+
+export interface SessionTouchInput {
+  readonly tenantId: TenantId;
+  readonly sessionId: SessionId;
+  /**
+   * The observed activity timestamp. Adapters SHOULD accept a
+   * caller-supplied instant so tests can drive the clock; production
+   * middleware passes `new Date()`.
+   */
+  readonly at: Date;
+}
+
+export interface SessionTouchOutcome {
+  /**
+   * `false` when the session was already revoked or the row is
+   * unknown — the middleware treats either case as a soft-fail (no
+   * fatal error, but the caller's next request will 401 via the
+   * standard checks).
+   */
+  readonly touched: boolean;
+}
+
+export interface SessionPage {
+  readonly data: readonly Session[];
+  readonly nextCursor?: Cursor;
+}
+
+export interface SessionRevokeOutcome {
+  readonly revoked: boolean;
+}
+
+export interface SessionRevokeAllForUserOutcome {
+  readonly revokedCount: number;
+}

package/src/signing-key-binding.ts

@@ -0,0 +1,235 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Cursor, Result, SigningKeyId, TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the API layer's **tenant-scoped signing-key
+ * trust registry** — the seam behind the deploy route's signature
+ * verification + trust-list cross-check.
+ *
+ * ## Position vs `SigningKeyBinding`
+ *
+ * the crypto module already exposes a `SigningKeyBinding` — a low-level
+ * KMS seam that returns raw key bytes for a `SigningKeyId`. That binding
+ * is deployment-wide; every request finds the same keys.
+ *
+ * THIS binding is a **higher-level, tenant-scoped trust registry**. It
+ * answers "for tenant T, is this public key allowed to sign deploys /
+ * artifacts?" and performs signature verification against the registered
+ * trust list. A production adapter typically wraps the crypto-layer
+ * binding for the underlying primitive ops and layers tenant-scoping,
+ * revocation, and audit on top.
+ *
+ * Consumers alias one of the two when importing both — TypeScript resolves
+ * them by module path but the local name collides.
+ *
+ * ## Two responsibilities
+ *
+ * 1. **Trust registry** (`listTrusted` / `getTrusted` / `addTrusted` /
+ *    `revokeTrusted`) — per-tenant CRUD over the set of public keys
+ *    permitted to sign deploys and admin operations.
+ * 2. **Verification** (`isTrusted` / `verify`) — cheap boolean trust
+ *    check + a full signature-verification call. The `POST /v1/deployments`
+ *    route calls `isTrusted` (which must be `true`) and then verifies the
+ *    Ed25519 signature itself; it does not call `verify`.
+ *
+ * Tenant-scoped: callers pass `tenantId` explicitly. Same trust list
+ * partitioning as every other admin surface.
+ *
+ * ## Seam only
+ *
+ * No implementation is bundled here; the `POST /v1/deployments` route
+ * runs its trust check through this interface.
+ */
+export interface SigningKeyBinding {
+  // -------------- verification --------------
+
+  /**
+   * Cheap trust check for the signature step of `POST /v1/deployments`.
+   * Returns `true` when the given `(keyId, publicKey)` pair appears on
+   * the tenant's trust list AND has not been revoked. `false` otherwise —
+   * the route surfaces `false` as `403 signer-not-trusted`.
+   *
+   * The pair is checked jointly to defend against a key-id collision
+   * across tenants: two tenants MAY use the same `SigningKeyId` for
+   * their own keys as long as the public bytes differ. Trust is bound
+   * to the exact bytes.
+   */
+  isTrusted(input: IsTrustedInput): Promise<Result<boolean, SigningKeyError>>;
+  /**
+   * Verify a raw Ed25519 signature over a canonicalised payload against
+   * the trusted key — e.g. the canonical deploy envelope
+   * (`(imageDigest, artifactVersion, indexHash, tenantId, publishedAt)`)
+   * as `payload`. The binding computes the verification and returns
+   * `valid: true` on cryptographic match.
+   *
+   * Bindings MUST NOT trust the caller's assertion that the key is
+   * trusted — they re-run the trust check as part of `verify`, so
+   * `signer-not-trusted` shortcuts before `signature-invalid`.
+   */
+  verify(input: VerifyInput): Promise<Result<VerifyOutcome, SigningKeyError>>;
+
+  // -------------- trust registry --------------
+
+  /**
+   * Cursor-paginated list of trusted keys for the tenant. Sort order is
+   * binding-defined (e.g. `createdAt desc, keyId desc`).
+   */
+  listTrusted(input: ListTrustedInput): Promise<TrustedKeyPage>;
+  /**
+   * Look up a single trusted key by id. `null` when unknown to the
+   * tenant OR revoked; revoked entries are excluded here (they still
+   * appear via `listTrusted` with `includeRevoked: true`).
+   */
+  getTrusted(input: GetTrustedInput): Promise<TrustedKey | null>;
+  /**
+   * Add a key to the tenant's trust list. Idempotent per `(keyId,
+   * publicKey)` — re-adding the same pair returns
+   * `{ kind: 'already-trusted' }` with the existing entry (no bump to
+   * `createdAt`). Different `publicKey` under the same `keyId` is
+   * rejected with `key-id-conflict` — callers rotate by allocating a
+   * new keyId, not by rebinding one.
+   */
+  addTrusted(input: AddTrustedInput): Promise<AddTrustedOutcome>;
+  /**
+   * Revoke a trusted key. Idempotent — revoking an already-revoked or
+   * unknown key returns `{ revoked: false }`; first-time revocation
+   * returns `{ revoked: true }`. The entry is retained (soft-delete)
+   * so historical `Deployment.signerKeyId` refs remain resolvable for
+   * audit; `isTrusted` returns `false` for revoked entries.
+   */
+  revokeTrusted(input: RevokeTrustedInput): Promise<RevokeTrustedOutcome>;
+}
+
+// -------------------- record --------------------
+
+/**
+ * Wire shape for a trusted-key registration. `publicKey` is base64 of
+ * the raw key bytes (Ed25519 = 32 bytes); `algorithm` is the closed set
+ * from the crypto module — extended here as an open string so future
+ * algorithms don't require a package bump on this file.
+ */
+export interface TrustedKey {
+  readonly keyId: SigningKeyId;
+  readonly tenantId: TenantId;
+  /** `'ed25519'` today. Open string for future algorithms. */
+  readonly algorithm: string;
+  /** Base64 of the raw public key bytes. */
+  readonly publicKey: string;
+  /** Optional human-readable label — e.g. `'acme-staging-2026-01'`. */
+  readonly label?: string;
+  /** ISO-8601 timestamp of first registration. */
+  readonly createdAt: string;
+  /** ISO-8601 timestamp of revocation; absent when active. */
+  readonly revokedAt?: string;
+  /** Reason string supplied at revocation time. */
+  readonly revokedReason?: string;
+}
+
+// -------------------- verify --------------------
+
+export interface IsTrustedInput {
+  readonly tenantId: TenantId;
+  readonly keyId: SigningKeyId;
+  /** Base64 of the raw public-key bytes the signer presented. */
+  readonly publicKey: string;
+}
+
+export interface VerifyInput {
+  readonly tenantId: TenantId;
+  readonly keyId: SigningKeyId;
+  /** Base64 of the raw public-key bytes. */
+  readonly publicKey: string;
+  /** Raw bytes over which the signature was computed. */
+  readonly payload: Uint8Array;
+  /** Base64 of the signature bytes. */
+  readonly signature: string;
+}
+
+export interface VerifyOutcome {
+  readonly valid: boolean;
+  /**
+   * When `valid: false`, a hint at why — `signature-mismatch` /
+   * `signer-not-trusted` / `algorithm-unsupported`. Useful for logs.
+   */
+  readonly reason?: string;
+}
+
+// -------------------- registry --------------------
+
+export interface ListTrustedInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /** When `true`, revoked entries are included. Default `false`. */
+  readonly includeRevoked?: boolean;
+  /** Prefix match on `TrustedKey.label` — useful for env-scoped listings. */
+  readonly labelFilter?: string;
+}
+
+export interface TrustedKeyPage {
+  readonly data: readonly TrustedKey[];
+  readonly nextCursor?: Cursor;
+}
+
+export interface GetTrustedInput {
+  readonly tenantId: TenantId;
+  readonly keyId: SigningKeyId;
+}
+
+export interface AddTrustedInput {
+  readonly tenantId: TenantId;
+  readonly keyId: SigningKeyId;
+  readonly algorithm: string;
+  readonly publicKey: string;
+  readonly label?: string;
+}
+
+export type AddTrustedOutcome =
+  | { readonly kind: 'ok'; readonly key: TrustedKey }
+  | { readonly kind: 'already-trusted'; readonly key: TrustedKey }
+  | {
+      /**
+       * Same `keyId` already registered but with different `publicKey`
+       * bytes. Callers rotate by allocating a fresh `keyId`.
+       */
+      readonly kind: 'key-id-conflict';
+      readonly existing: TrustedKey;
+    }
+  | {
+      /**
+       * The key couldn't be trusted. `signing-key-revoked`: the id was
+       * revoked, and revocation is final (rotate under a new id). Other
+       * codes are store failures.
+       */
+      readonly kind: 'error';
+      readonly code: string;
+      readonly message: string;
+    };
+
+export interface RevokeTrustedInput {
+  readonly tenantId: TenantId;
+  readonly keyId: SigningKeyId;
+  /** Optional audit reason surfaced through `TrustedKey.revokedReason`. */
+  readonly reason?: string;
+}
+
+export interface RevokeTrustedOutcome {
+  readonly revoked: boolean;
+}
+
+// -------------------- error --------------------
+
+export type SigningKeyError =
+  | { readonly code: 'signing-key-not-found'; readonly message: string; readonly keyId: string }
+  | {
+      readonly code: 'signing-key-algorithm-unsupported';
+      readonly message: string;
+      readonly algorithm: string;
+    }
+  | {
+      readonly code: 'signing-key-store-error';
+      readonly message: string;
+      readonly cause?: unknown;
+    };

package/src/state-store-binding.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { TenantId } from '@kindgi/types';
+
+/**
+ * Short-lived CSRF-`state` + PKCE-`code_verifier` cache used by the
+ * OAuth login/callback pair. Values live between `/v1/auth/login/:id`
+ * (which generates `state` + `code_verifier`) and
+ * `/v1/auth/callback/:id` (which reads them back). TTL is measured in
+ * minutes — long enough for a user to complete the provider hop, short
+ * enough that a lost row is a non-event.
+ *
+ * The default `createInMemoryOauthStateStore` is appropriate for
+ * single-process dev + tests. Multi-pod deployments MUST plug in a
+ * shared store (Redis, Postgres) because the callback usually lands on
+ * a different pod than the login. Mirror of the `IdempotencyStore`
+ * caller-plugged pattern.
+ *
+ * Keyed by `state` alone — `state` carries 256 bits of entropy, so it
+ * is uniquely identifying without a namespace. `take` matches on
+ * `providerId` when supplied to guard against a stolen `state` being
+ * replayed against the wrong provider mount; `tenantId` is returned in
+ * the entry (the callback route learns it from the row, not the URL).
+ */
+export interface OauthStateStore {
+  put(entry: OauthStateEntry): Promise<void>;
+  /**
+   * Consume the entry keyed by `state`. Returns `null` when unknown or
+   * expired. When `providerId` is supplied, the returned entry MUST
+   * match — the store returns `null` (and leaves the entry in place)
+   * otherwise. `tenantId` is derived from the entry.
+   */
+  take(input: OauthStateTakeInput): Promise<OauthStateEntry | null>;
+}
+
+export interface OauthStateEntry {
+  readonly state: string;
+  readonly tenantId: TenantId;
+  readonly providerId: string;
+  readonly codeVerifier: string;
+  readonly redirectUri: string;
+  readonly expiresAt: number;
+}
+
+export interface OauthStateTakeInput {
+  readonly state: string;
+  /** Optional cross-check — when set, entry must match or `take` returns null. */
+  readonly providerId?: string;
+}
+
+/**
+ * Trivial in-memory store — appropriate for tests + single-process dev.
+ * Entries are single-use (`take` deletes on hit) and time out on their
+ * own; the store performs a shallow expired-entry sweep on every call
+ * so long-lived processes don't leak memory when a callback never
+ * arrives.
+ */
+export function createInMemoryOauthStateStore(): OauthStateStore {
+  const entries = new Map<string, OauthStateEntry>();
+
+  const sweep = (now: number): void => {
+    for (const [key, entry] of entries) {
+      if (entry.expiresAt <= now) entries.delete(key);
+    }
+  };
+
+  return {
+    async put(entry) {
+      sweep(Date.now());
+      entries.set(entry.state, entry);
+    },
+    async take({ state, providerId }) {
+      const now = Date.now();
+      sweep(now);
+      const entry = entries.get(state);
+      if (entry === undefined) return null;
+      if (providerId !== undefined && entry.providerId !== providerId) return null;
+      entries.delete(state);
+      if (entry.expiresAt <= now) return null;
+      return entry;
+    },
+  };
+}