@web-ts-toolkit/express-oidc-vault-redis-store 0.32.0 → 0.33.0

package/README.md

@@ -4,6 +4,11 @@ Redis-backed store provider for `@web-ts-toolkit/express-oidc-vault`.
 
 ## Installation
 
+The `redis` package is referenced by the quick start below, but this package
+treats it as a development-only dependency: the package does not import `redis`
+at runtime and accepts any client that implements the `OidcVaultRedisClient`
+contract. Install `redis` (or your adapter of choice) in your app.
+
 ```sh
 pnpm add @web-ts-toolkit/express-oidc-vault @web-ts-toolkit/express-oidc-vault-redis-store express redis
 ```
@@ -39,6 +44,7 @@ await redis.connect();
 app.use(
   createOidcVaultMiddleware({
     basePath: '/auth/oidc',
+    backendOrigin: 'https://api.example.com',
     config: {
       issuer: process.env.OIDC_ISSUER,
       clientId: process.env.OIDC_CLIENT_ID,
@@ -57,13 +63,69 @@ app.use(
 ## Notes
 
 - use Redis in production when you need shared session state across multiple app instances
+- supported Redis topologies are standalone Redis through the official `redis` client, and Redis Sentinel through the underlying master client retrieved from a `createSentinel(...)` client (see _Redis Version And Topology_); Redis Cluster is not supported
+- Redis Cluster clients are rejected when the store is created because the package does not currently route multi-key vault scripts through a hash-slot adapter
 - the provider stores JSON payloads under prefixed keys for sessions, auth transactions, and one-time exchange codes
 - one-time records are consumed atomically through Redis commands instead of `get` plus `del`
 - session rotation and session indexes are updated atomically so concurrent refreshes do not fork multiple active sessions
-- the client must support `sendCommand(...)`; the official `redis` package already does
+- rotation requires a distinct unused target session ID; missing-source, same-ID, and existing-target rotation conflicts throw `OidcVaultStoreConflictError` without changing source or target records
+- obsolete rotated session IDs are stored as aliases owned by the logical session; revoking the active logical session, or deleting through any obsolete ID, removes all aliases and the reverse alias index
+- creating or rotating into a previously obsolete session ID removes that stale alias ownership first, so a reused ID cannot invoke an old logical-session meaning
+- `createAuthorizationTransaction` and `createExchangeCode` are upserts; `createSession` is create-only and duplicate session IDs throw `OidcVaultStoreConflictError` without changing the existing record or indexes
+- session metadata should be JSON-compatible for portability across store providers
+- backchannel logout token JTI records are consumed only when `expiresAt` is finite and greater than the store clock at consume time
+- the optional `now` hook controls store-domain timestamps and testable JTI validation only; Redis server time is the authority for Redis key expiry and revocation-index cleanup
+- the client must implement `sendCommand(args)`; official standalone `redis` clients already do, and a Sentinel-wrapped master client or any adapter implementing `OidcVaultRedisClient` does too
+
+## Redis Version And Topology
+
+- **Minimum Redis version: 6.2.** One-time authorization transactions and exchange codes are consumed with `GETDEL`, which is unavailable before Redis 6.2. Versions 6.2 and 7.2 are exercised in integration tests.
+- **Standalone Redis**: supported through the official `redis` `createClient(...)` client (`RedisClientType`). This is the tested topological default.
+- **Redis Sentinel**: supported by passing the underlying master client retrieved from a `redis.createSentinel(...)` sentinel — for example, the client returned by `await sentinel.acquire()`, or via `await sentinel.use(c => c)` patterns documented in the `redis` package. The bare `createSentinel(...)` root client does NOT satisfy this package's structural contract directly: its `sendCommand(isReadonly, args, options?)` requires an `isReadonly` first argument, while this store calls `sendCommand(args)`. Wrap the underlying master with an adapter conforming to `OidcVaultRedisClient` if you want to retain the Sentinel's connection management. Sentinel failover switches the underlying node, so vault state survives a failover subject to your Sentinel AOF/RDB durability settings.
+- **Redis Cluster**: **not supported.** Cluster-shaped official clients are rejected when the store is created. The package's atomic vault scripts touch several keys without a hash-slot routing adapter, so Cluster routing could send parts of one logical operation to different nodes. Add a Cluster routing/hash-slot adapter before enabling it.
+
+## Client Lifecycle And Ownership
+
+- **Connect the client yourself.** The store never calls `client.connect()`, `client.quit()`, or `client.disconnect()`. Pass an already-connected client and reuse it across requests.
+- **Own `error` listeners, reconnects, and shutdown.** The store reads and writes commands but does not attach `error` listeners, suppress client errors, or close the client. Always register a client `error` listener on production connections; an unhandled client error can crash the process.
+- **Graceful shutdown.** Draining `createSession`/`rotateSession`/`deleteSessionsBy*` in-flight calls, then `client.quit()`, is the supported shutdown order. The store holds no background timers, so no store-side teardown is required beyond verifying in-flight operations have settled.
+- **Concurrency.** `OidcVaultStoreProvider` methods are safe to call concurrently from one or more processes. Atomic operations are protected by Redis server-side scripts; concurrent duplicate ID creation, concurrent indexed revocation of overlapping indexes, concurrent rotation into the same target ID, and concurrent same-ID rotation conflicting with indexed revocation are all bounded.
+
+## Key Namespace And Migration
+
+- All vault keys are written as `<keyPrefix>:<kind>:<id>` and default to the `oidc-vault` prefix. Use `keyPrefix` when the same Redis instance stores data for multiple apps, environments, or tenants.
+- **Changing the prefix is not a migration.** Switching `keyPrefix` starts an independent empty namespace: existing sessions, indexes, aliases, exchange codes, and authorization transactions remain under the previous prefix and are neither revoked nor cleaned up by the new store. Rotate the prefix only when you are prepared to lose access to, or coordinate decommissioning of, the previous namespace.
+- New sessions created under the new prefix will not collide with the old namespace, even when ranges of session IDs overlap — keys are fully namespaced and the cleanup scan only walks the configured prefix.
+
+## Stored Data Characteristics
+
+- This package stores refresh tokens, ID tokens, access tokens (when present), and session metadata as **plaintext JSON** in Redis values. It does not encrypt the values, redact them on read, or strip token fields before returning them.
+- Audit-trail and long-term persistence safety depends entirely on your Redis deployment: AOF/RDB snapshots, replicas, backups, and slow-query logs may all retain these plaintext values. Treat the Redis instance, its backups, and any persistence or replication as trusted infrastructure with the same access control you apply to your application database.
+- ACLs, TLS, network isolation, and Redis instance boundaries are the responsibility of the operator. Run the Redis instance on a private network, enable TLS for any cross-network hop, and apply the principle of least privilege with ACL rules that limit clients to the keyspace consumed by `keyPrefix`.
+- The package holds no cross-version schema migration guarantee. Treat the package version as the schema owner unless a future release documents a migration path.
+
+## Expiry And Index Cleanup
+
+- expiring session records are stored with Redis `PXAT`, and revocation index scores use the same absolute expiration timestamp
+- stale revocation memberships are pruned with Redis `TIME`, not the application clock, so a skewed application clock cannot remove a still-live Redis session from subject, provider-session, or logical-session indexes
+- indexed revocation also checks the primary session key before deleting or returning a session; expired primary values are not returned and missing primary values remove the stale membership encountered during traversal
+- indexed revocation traverses Redis sorted sets with bounded cursor batches and batched record reads; it revokes sessions present in the cursor scan's view, while sessions added to the same index after the scan starts may be revoked by a later indexed revocation call
+- each successful session create or rotation scans up to 100 prefixed keys and removes Redis-expired members from subject, provider-session, and logical-session indexes; Redis deletes empty sorted sets, so unique expired logical-session index keys are eventually removed even without a logout for that logical session
+- rotated session aliases use the same expiry score as their successor session; non-expiring alias churn is bounded by cleanup on logical-session termination, and malformed stale aliases are deleted when their session ID is reused
+- stale index storage is therefore bounded by active session index entries plus expired entries waiting for Redis expiry and the incremental cleanup scan window; non-expiring sessions use a non-expiring index score and remain until revoked
+
+## Stored Data Validation And Corruption Handling
+
+- stored records are JSON payloads validated structurally on read; see _Stored Data Characteristics_ for the schema-migration and plaintext-storage posture
+- malformed one-time authorization transaction and exchange-code records are consumed atomically and return `null`, preventing reuse while failing closed
+- malformed session records are treated as unreadable, deleted when encountered through session reads or indexed revocation, and never returned as authenticated state
+- indexed revocation removes stale corrupt members and continues processing later valid sessions
+- Redis mutation scripts preflight expected key types before writing so wrong-type keys fail without deterministic partial mutation
+- validation errors and script errors are sanitized and do not include stored refresh tokens, ID tokens, authorization transactions, or exchange codes
 
 ## Main Exports
 
 - `createRedisOidcVaultStore(...)`
+- `OidcVaultRedisStoreRecordError`
 - `type RedisOidcVaultStoreOptions`
 - `type OidcVaultRedisClient`

package/index.d.mts

@@ -1,18 +1,96 @@
 import { OidcVaultStoreProvider } from '@web-ts-toolkit/express-oidc-vault';
 
+/**
+ * Thrown when a stored Redis value cannot be parsed or fails structural
+ * validation. The message never includes stored token or refresh values.
+ * Malformed one-time records are consumed atomically and return `null`; they
+ * fail closed without throwing this error. Malformed sessions are deleted when
+ * encountered through reads or indexed revocation.
+ */
+declare class OidcVaultRedisStoreRecordError extends Error {
+    constructor(recordKind: string);
+}
+
+/**
+ * Minimal structural shape of the Redis client or adapter this package
+ * consumes. The package does not import the official `redis` driver at runtime;
+ * it accepts any client that implements this interface. An official
+ * `redis.createClient(...)` standalone client (`RedisClientType`) satisfies
+ * this shape directly. Redis Cluster clients are intentionally excluded until
+ * the package ships a hash-slot routing adapter.
+ *
+ * Redis Sentinel: the `redis.createSentinel(...)` root client does NOT satisfy
+ * this contract directly because its `sendCommand(isReadonly, args, options?)`
+ * requires an `isReadonly` first argument. To use Sentinel, acquire the
+ * underlying master client (for example through `sentinel.use(c => c)` or
+ * `await sentinel.acquire()`) and pass a client connection that exposes the
+ * standalone `sendCommand(args, options?)` signature, or wrap the Sentinel
+ * root with an adapter conforming to this interface.
+ *
+ * A constructed client must be connected before use; the package never calls
+ * `connect()` and never reads or suppresses client error/quit listeners. The
+ * caller owns the client lifecycle (connect, error handling, and shutdown).
+ *
+ * `sendCommand` is required because atomic session writes, rotations,
+ * deletions, and one-time record consumption transit Redis
+ * `EVAL`/`GETDEL`/`TYPE`/`TIME`/`ZRANGE`/`ZSCAN`/`MGET` commands through it.
+ * It was previously optional in this type but always enforced at runtime.
+ */
 interface OidcVaultRedisClient {
     set(key: string, value: string, options?: {
         PXAT?: number;
+        NX?: true;
     }): Promise<unknown>;
     get(key: string): Promise<string | null>;
     del(keys: string | string[]): Promise<number>;
-    sendCommand?(args: string[]): Promise<unknown>;
+    sendCommand(args: string[]): Promise<unknown>;
+    /** Sentinel members that mark an official Redis Cluster client. Reject at construction. */
+    getSlotMaster?: never;
+    masters?: never;
+    nodeClient?: never;
+    slots?: never;
 }
+/**
+ * Options for {@link createRedisOidcVaultStore}.
+ *
+ * The caller is responsible for connecting the `client` before constructing the
+ * store and for owning `error` listeners, reconnects, and shutdown (`quit()` /
+ * `disconnect()`). The package never calls `connect`, `quit`, or `disconnect`.
+ */
 interface RedisOidcVaultStoreOptions {
+    /** Connected Redis client or compatible adapter implementing {@link OidcVaultRedisClient}. */
     client: OidcVaultRedisClient;
+    /**
+     * Optional namespace for vault keys, written as `<keyPrefix>:<kind>:<id>`.
+     * Defaults to `oidc-vault`. Changing it after records exist starts an
+     * independent namespace; existing sessions remain discoverable only under
+     * the previous prefix and will not be revoked or cleaned up by the new store.
+     */
     keyPrefix?: string;
+    /**
+     * Optional clock used only for store-domain timestamps (e.g. JTI
+     * expiration). Redis server time remains the authority for key expiry
+     * (`PXAT`) and revocation-index pruning, so a skewed application clock
+     * cannot remove a still-live Redis session from any index.
+     */
     now?: () => number;
 }
+/**
+ * Create an `OidcVaultStoreProvider` backed by a connected Redis client.
+ *
+ * Pass an already-connected official `redis` standalone client (or any adapter
+ * implementing {@link OidcVaultRedisClient}). For Redis Sentinel deployments,
+ * acquire or wrap the underlying master client as described on
+ * {@link OidcVaultRedisClient}; the bare `createSentinel(...)` client does not
+ * satisfy the structural contract. The store does not connect, disconnect, or
+ * attach `error` listeners; it only issues commands.
+ *
+ * The package requires Redis 6.2 or later (it uses `GETDEL`). Redis Cluster is
+ * not supported and is rejected here.
+ *
+ * @param options construction options; see {@link RedisOidcVaultStoreOptions}.
+ * @returns a provider satisfying the core `OidcVaultStoreProvider` contract.
+ */
 declare function createRedisOidcVaultStore(options: RedisOidcVaultStoreOptions): OidcVaultStoreProvider;
 
-export { type OidcVaultRedisClient, type RedisOidcVaultStoreOptions, createRedisOidcVaultStore };
+export { type OidcVaultRedisClient, OidcVaultRedisStoreRecordError, type RedisOidcVaultStoreOptions, createRedisOidcVaultStore };

package/index.d.ts

@@ -1,18 +1,96 @@
 import { OidcVaultStoreProvider } from '@web-ts-toolkit/express-oidc-vault';
 
+/**
+ * Thrown when a stored Redis value cannot be parsed or fails structural
+ * validation. The message never includes stored token or refresh values.
+ * Malformed one-time records are consumed atomically and return `null`; they
+ * fail closed without throwing this error. Malformed sessions are deleted when
+ * encountered through reads or indexed revocation.
+ */
+declare class OidcVaultRedisStoreRecordError extends Error {
+    constructor(recordKind: string);
+}
+
+/**
+ * Minimal structural shape of the Redis client or adapter this package
+ * consumes. The package does not import the official `redis` driver at runtime;
+ * it accepts any client that implements this interface. An official
+ * `redis.createClient(...)` standalone client (`RedisClientType`) satisfies
+ * this shape directly. Redis Cluster clients are intentionally excluded until
+ * the package ships a hash-slot routing adapter.
+ *
+ * Redis Sentinel: the `redis.createSentinel(...)` root client does NOT satisfy
+ * this contract directly because its `sendCommand(isReadonly, args, options?)`
+ * requires an `isReadonly` first argument. To use Sentinel, acquire the
+ * underlying master client (for example through `sentinel.use(c => c)` or
+ * `await sentinel.acquire()`) and pass a client connection that exposes the
+ * standalone `sendCommand(args, options?)` signature, or wrap the Sentinel
+ * root with an adapter conforming to this interface.
+ *
+ * A constructed client must be connected before use; the package never calls
+ * `connect()` and never reads or suppresses client error/quit listeners. The
+ * caller owns the client lifecycle (connect, error handling, and shutdown).
+ *
+ * `sendCommand` is required because atomic session writes, rotations,
+ * deletions, and one-time record consumption transit Redis
+ * `EVAL`/`GETDEL`/`TYPE`/`TIME`/`ZRANGE`/`ZSCAN`/`MGET` commands through it.
+ * It was previously optional in this type but always enforced at runtime.
+ */
 interface OidcVaultRedisClient {
     set(key: string, value: string, options?: {
         PXAT?: number;
+        NX?: true;
     }): Promise<unknown>;
     get(key: string): Promise<string | null>;
     del(keys: string | string[]): Promise<number>;
-    sendCommand?(args: string[]): Promise<unknown>;
+    sendCommand(args: string[]): Promise<unknown>;
+    /** Sentinel members that mark an official Redis Cluster client. Reject at construction. */
+    getSlotMaster?: never;
+    masters?: never;
+    nodeClient?: never;
+    slots?: never;
 }
+/**
+ * Options for {@link createRedisOidcVaultStore}.
+ *
+ * The caller is responsible for connecting the `client` before constructing the
+ * store and for owning `error` listeners, reconnects, and shutdown (`quit()` /
+ * `disconnect()`). The package never calls `connect`, `quit`, or `disconnect`.
+ */
 interface RedisOidcVaultStoreOptions {
+    /** Connected Redis client or compatible adapter implementing {@link OidcVaultRedisClient}. */
     client: OidcVaultRedisClient;
+    /**
+     * Optional namespace for vault keys, written as `<keyPrefix>:<kind>:<id>`.
+     * Defaults to `oidc-vault`. Changing it after records exist starts an
+     * independent namespace; existing sessions remain discoverable only under
+     * the previous prefix and will not be revoked or cleaned up by the new store.
+     */
     keyPrefix?: string;
+    /**
+     * Optional clock used only for store-domain timestamps (e.g. JTI
+     * expiration). Redis server time remains the authority for key expiry
+     * (`PXAT`) and revocation-index pruning, so a skewed application clock
+     * cannot remove a still-live Redis session from any index.
+     */
     now?: () => number;
 }
+/**
+ * Create an `OidcVaultStoreProvider` backed by a connected Redis client.
+ *
+ * Pass an already-connected official `redis` standalone client (or any adapter
+ * implementing {@link OidcVaultRedisClient}). For Redis Sentinel deployments,
+ * acquire or wrap the underlying master client as described on
+ * {@link OidcVaultRedisClient}; the bare `createSentinel(...)` client does not
+ * satisfy the structural contract. The store does not connect, disconnect, or
+ * attach `error` listeners; it only issues commands.
+ *
+ * The package requires Redis 6.2 or later (it uses `GETDEL`). Redis Cluster is
+ * not supported and is rejected here.
+ *
+ * @param options construction options; see {@link RedisOidcVaultStoreOptions}.
+ * @returns a provider satisfying the core `OidcVaultStoreProvider` contract.
+ */
 declare function createRedisOidcVaultStore(options: RedisOidcVaultStoreOptions): OidcVaultStoreProvider;
 
-export { type OidcVaultRedisClient, type RedisOidcVaultStoreOptions, createRedisOidcVaultStore };
+export { type OidcVaultRedisClient, OidcVaultRedisStoreRecordError, type RedisOidcVaultStoreOptions, createRedisOidcVaultStore };