ioredis-toolkit 0.0.9 → 0.5.0

package/dist/streams/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/streams/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,sDAAsD;AACtD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5R,sDAAsD;AACtD,MAAM,UAAU,kBAAkB,CAAC,KAAc,IAAmB,OAAO,mBAAmB,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAkB,CAAC,CAAC,CAAC"}

package/dist/streams/streams.d.ts

@@ -0,0 +1,24 @@
+import type { RedisClientWrapper } from '../redis/wrapper.js';
+import type { StreamEntry, StreamReadOptions, StreamsConfig } from './types.js';
+/** Redis Streams abstraction for append, consumer groups, reads and acknowledgements. */
+export declare class RedisStreams {
+    private readonly redis;
+    private readonly config;
+    /** Creates a Streams module bound to the shared Redis client. */
+    constructor(redis: RedisClientWrapper, config: StreamsConfig);
+    /** Builds the physical stream key. */
+    key(name: string): string;
+    /** Appends a field map to a stream and optionally trims the stream length. */
+    add(name: string, fields: Record<string, string>, maxEntries?: number): Promise<string>;
+    /** Creates a consumer group; when startId is omitted, the group starts at '$'. */
+    createGroup(name: string, group: string, startId?: string, mkStream?: boolean): Promise<void>;
+    /** Reads entries from a stream, optionally through a consumer group. */
+    read(name: string, options?: StreamReadOptions): Promise<StreamEntry[]>;
+    /** Acknowledges one or more group messages. */
+    ack(name: string, group: string, ...ids: string[]): Promise<number>;
+    /** Removes entries by ID from a stream. */
+    delete(name: string, ...ids: string[]): Promise<number>;
+    /** Returns the stream length. */
+    length(name: string): Promise<number>;
+}
+//# sourceMappingURL=streams.d.ts.map

package/dist/streams/streams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.d.ts","sourceRoot":"","sources":["../../src/streams/streams.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhF,yFAAyF;AACzF,qBAAa,YAAY;IAEX,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAsB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAD/E,iEAAiE;gBACpC,KAAK,EAAE,kBAAkB,EAAmB,MAAM,EAAE,aAAa;IAC9F,sCAAsC;IACtC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IACzB,8EAA8E;IACxE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,SAAyB,GAAG,OAAO,CAAC,MAAM,CAAC;IAC7G,kFAAkF;IAC5E,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,SAAM,EAAE,QAAQ,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAC7F,wEAAwE;IAClE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAWjF,+CAA+C;IACzC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IACzE,2CAA2C;IACrC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAC7D,iCAAiC;IAC3B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAC5C"}

package/dist/streams/streams.js

@@ -0,0 +1,55 @@
+/** Redis Streams abstraction for append, consumer groups, reads and acknowledgements. */
+export class RedisStreams {
+    redis;
+    config;
+    /** Creates a Streams module bound to the shared Redis client. */
+    constructor(redis, config) {
+        this.redis = redis;
+        this.config = config;
+    }
+    /** Builds the physical stream key. */
+    key(name) { return `${this.config.keyPrefix}:${name}`; }
+    /** Appends a field map to a stream and optionally trims the stream length. */
+    async add(name, fields, maxEntries = this.config.maxEntries) { return this.redis.xadd(this.key(name), 'MAXLEN', '~', String(maxEntries), '*', ...Object.entries(fields).flat()); }
+    /** Creates a consumer group; when startId is omitted, the group starts at '$'. */
+    async createGroup(name, group, startId = '$', mkStream = true) { try {
+        await this.redis.xgroup('CREATE', this.key(name), group, startId, ...(mkStream ? ['MKSTREAM'] : []));
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !/BUSYGROUP/.test(error.message))
+            throw error;
+    } }
+    /** Reads entries from a stream, optionally through a consumer group. */
+    async read(name, options = {}) {
+        if (options.group !== undefined && options.consumer === undefined)
+            throw new RangeError('Stream reads via a consumer group require options.consumer');
+        const useGroup = options.group !== undefined && options.consumer !== undefined;
+        const count = options.count ?? 100;
+        const id = options.id ?? (useGroup ? '>' : '$');
+        const blockMs = options.blockMs ?? this.config.blockMs;
+        const result = useGroup
+            ? await this.redis.xreadgroup('GROUP', options.group, options.consumer, 'COUNT', String(count), 'BLOCK', String(blockMs), 'STREAMS', this.key(name), id)
+            : await this.redis.xread('COUNT', String(count), 'BLOCK', String(blockMs), 'STREAMS', this.key(name), id);
+        return parseStreamResult(result);
+    }
+    /** Acknowledges one or more group messages. */
+    async ack(name, group, ...ids) { return this.redis.xack(this.key(name), group, ...ids); }
+    /** Removes entries by ID from a stream. */
+    async delete(name, ...ids) { return this.redis.xdel(this.key(name), ...ids); }
+    /** Returns the stream length. */
+    async length(name) { return this.redis.xlen(this.key(name)); }
+}
+function parseStreamResult(result) {
+    if (!Array.isArray(result) || result.length === 0)
+        return [];
+    const stream = result[0];
+    if (!stream || !Array.isArray(stream[1]))
+        return [];
+    return stream[1].map(([id, values]) => { const fields = {}; for (let i = 0; i < values.length; i += 2) {
+        const key = values[i];
+        const value = values[i + 1];
+        if (key !== undefined && value !== undefined)
+            fields[key] = value;
+    } return { id, fields }; });
+}
+//# sourceMappingURL=streams.js.map

package/dist/streams/streams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.js","sourceRoot":"","sources":["../../src/streams/streams.ts"],"names":[],"mappings":"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"}

package/dist/streams/types.d.ts

@@ -0,0 +1,32 @@
+/** Normalized configuration for {@link RedisStreams}. */
+export interface StreamsConfig {
+    /** Whether the application has enabled the module. The class remains directly constructible when false; {@link RedisClient}'s `streams` getter throws when disabled. */
+    enabled: boolean;
+    /** Prefix used for physical stream keys. */
+    keyPrefix: string;
+    /** Approximate number of entries retained by the default `add()` trim operation. */
+    maxEntries: number;
+    /** Default configured blocking duration in milliseconds for application policy. */
+    blockMs: number;
+}
+/** One decoded Redis Stream entry. */
+export interface StreamEntry {
+    /** Redis stream entry ID, for example `1750000000000-0`. */
+    id: string;
+    /** Field/value pairs returned by Redis. */
+    fields: Record<string, string>;
+}
+/** Options controlling a stream read. */
+export interface StreamReadOptions {
+    /** Consumer group name. Supplying this selects `XREADGROUP`. */
+    group?: string;
+    /** Consumer name. Required when `group` is supplied. */
+    consumer?: string;
+    /** Maximum number of entries requested from Redis. */
+    count?: number;
+    /** Optional blocking duration in milliseconds. */
+    blockMs?: number;
+    /** Starting/continuation ID. Group reads commonly use `>`. */
+    id?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/streams/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/streams/types.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,wKAAwK;IACxK,OAAO,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,EAAE,CAAC,EAAE,MAAM,CAAC;CACb"}

package/dist/streams/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/streams/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/streams/types.ts"],"names":[],"mappings":""}

package/docs/ACCEPTANCE-REPORT.md

@@ -0,0 +1,70 @@
+# Acceptance Report — redis-session-kit 0.3.0
+
+> **Update (0.5.0):** the package was subsequently renamed to `ioredis-toolkit`. The "Environment limitation" below is specific to the 0.3.0 acceptance pass and no longer applies: the 0.5.0 bug-fix pass ran `typecheck`, `lint`, `test`, and `build` against installed dependencies in this environment and all passed, including a full, verified-ESM `dist/` rebuild. See `CHANGELOG.md` and `docs/TYPE-SAFETY.md`'s "0.5.0 verification note" for what changed and what was actually run.
+
+## Scope
+
+This release adds and documents the Cache, Lock, Rate Limiting, Pub/Sub, and Streams modules alongside the existing session subsystem. All modules share one `RedisClient` and support global configuration plus fluent merge/replace overrides.
+
+## Completed source-level checks
+
+- All TypeScript source was regenerated into `dist/` using the TypeScript compiler's syntax-preserving transpilation APIs after source changes.
+- Every generated JavaScript file passes `node --check`.
+- Public declarations were regenerated from the current source.
+- `npm pack --dry-run` succeeds and reports the expected source, distribution, documentation, and Lua-script files.
+- Module usage documentation exists for Cache, Lock, Rate Limiting, Pub/Sub, Streams, and Sessions.
+- Public module types and methods have JSDoc documentation in the source/declarations.
+
+## Environment limitation
+
+The execution environment could not download npm dependencies from `registry.npmjs.org` because external registry resolution returned `EAI_AGAIN`. Therefore a genuine dependency-backed `npm run typecheck`, Vitest run, and Redis integration run could not be completed here.
+
+This limitation is explicitly recorded rather than treating missing dependency declarations as a successful typecheck.
+
+## Required verification before publishing
+
+Run in a normal networked development/CI environment:
+
+```bash
+bun install --frozen-lockfile
+bun run typecheck
+bun run lint
+bun run test
+bun run test:integration
+bun run build
+npm pack
+```
+
+For integration/failover verification, also run the provided Docker Redis Standalone, Sentinel, and Cluster environments.
+
+## Configuration API acceptance
+
+The intended public configuration model is:
+
+```ts
+const redis = createRedisClient({
+  mode: 'standalone',
+  host: '127.0.0.1',
+  port: 6379,
+  cache: { enabled: true },
+  lock: { enabled: true },
+  rateLimit: { enabled: true },
+  pubsub: { enabled: true },
+  streams: { enabled: true },
+  sessions: { enabled: true },
+});
+```
+
+Each module can then be adjusted without constructing another Redis connection:
+
+```ts
+redis
+  .withCache({ defaultTtl: 60 })
+  .withLock({ defaultTtl: 15 })
+  .withRateLimit({ maxRequests: 500 })
+  .withPubSub({ channelPrefix: 'critical' })
+  .withStreams({ maxEntries: 500_000 })
+  .withSessions({ idleTimeout: 3600 });
+```
+
+Use `replace` when a module should return to defaults before applying the supplied override.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,61 @@
+# Architecture Decision Record
+
+## Status
+
+Accepted for the initial implementation.
+
+## Decision: create the package and Redis infrastructure from scratch
+
+The supplied specification described an existing Redis package, but this project started without one. Therefore the implementation owns the Redis connection factory, wrapper, cluster utilities, configuration validation, session domain, and public exports. No duplicate external authentication/core package is assumed.
+
+## Decision: opaque token + token-hash locator
+
+A token-only `validate(token)` operation requires a locator. The package uses SHA-256(token) as the lookup key and stores only the derived hash plus a user hash-tag pointer. The actual session record remains authoritative.
+
+This is a deliberate secondary-index consistency boundary. A missing/stale index never authenticates anything.
+
+## Decision: per-user Cluster hash tag
+
+Session keys are shaped as:
+
+`<namespace>:session:{<sha256(userId)>}:<sha256(token)>`
+
+The user hash is deterministic and safe for Redis hash-tag syntax. It keeps one user's session records/index in one slot while distributing different users across slots.
+
+## Decision: no global JTI index
+
+JTI is an internal session identifier and is not needed to validate the opaque token. A global JTI index would add another cross-slot consistency boundary without improving the core validation path.
+
+## Decision: session index as a negative authorization guard
+
+The user sorted-set index is checked during validation. The index can deny access but cannot grant access: the session record must independently pass all checks.
+
+Max-session enforcement (`create_session`) and revocation (`revoke()`, and rotation's `consume()`) all remove their affected member from the index eagerly. `create_session` additionally deletes the evicted session's own physical session and token-index keys — a bounded operation (at most one evicted session per `create()` call, given the per-user cap is enforced on every write), not the unbounded cluster-wide cleanup the "bounded maintenance" decision below rules out. Earlier revisions left the physical keys behind to expire on their own TTL; that left orphaned Redis memory and a token-index entry that stayed briefly resolvable past the point the session was actually evicted, so the index-only approach was deliberately narrowed to also delete the record it is evicting.
+
+## Decision: rotation is two-phase
+
+A predecessor is consumed atomically. A successor is created separately because the token-hash key is unrelated to the predecessor's key slot. This can produce a safe availability failure after consumption, but cannot produce two valid successors.
+
+The package does not claim rotation idempotency. Network-timeout retry must be handled by a higher-level protocol if required.
+
+## Decision: server time
+
+Redis TIME is used for authentication/session timestamps to reduce application-clock ordering problems. TTLs remain Redis storage cleanup boundaries; application expiration fields remain authoritative for session validity.
+
+## Decision: bounded maintenance
+
+No request path scans the entire cluster or performs unbounded Lua loops. Batch/list/revoke-all calls are capped by configuration.
+
+## Decision: no built-in circuit breaker
+
+The low-level Redis client already owns connection/reconnect behavior. A circuit breaker in this first package would add another failure-state machine without changing the required fail-closed authentication semantics. Applications may wrap the package with an operation-class breaker if their deployment needs one.
+
+`SessionConfig.circuitBreaker` exists as a reserved, fully-validated/defaulted configuration section for a future breaker, but no repository or service code currently reads it — it is not yet wired to any actual circuit-breaking behavior. Do not infer working circuit-breaker semantics from its presence in the config schema.
+
+## Decision: every Redis connection gets a default `'error'` listener
+
+`Redis`/`Cluster` instances are Node `EventEmitter`s that throw an uncaught exception and crash the process when an `'error'` event fires with zero listeners. `createRedisConnection()` and `RedisPubSub`'s dedicated subscriber connection now both attach a no-op default listener so a connection drop can never crash the process by itself. This does not replace real observability: applications that need alerting on connection errors should still attach their own `'error'` listener on the connection object.
+
+## Decision: module `enabled` flags are enforced uniformly
+
+Every module config (`cache`, `lock`, `rateLimit`, `pubsub`, `streams`, `sessions`) exposes an `enabled` flag defaulting to `false`. `RedisClient`'s lazy getters (`.cache`, `.lock`, `.rateLimiter`, `.pubsub`, `.streams`, `.sessions`) throw a configuration error while the corresponding module is disabled. Each module class remains directly constructible regardless of `enabled` — the flag only gates access through the shared client facade, matching how `sessions` already behaved before the other four modules were brought in line with it.

package/docs/CAPACITY.md

@@ -0,0 +1,33 @@
+# Capacity Planning
+
+Exact Redis memory depends heavily on allocator overhead, key length, metadata, replication, and encryption envelope size. The following is an engineering sizing method rather than a promise of exact bytes.
+
+## Per-session components
+
+Approximate:
+
+- Session key: namespace + fixed prefixes + 64-byte token hash + user hash tag.
+- User-index member: 64-byte token hash plus sorted-set overhead.
+- Serialized record: fixed fields plus bounded metadata.
+- Token locator: token hash key + 64-byte token hash + user tag value.
+- Redis object/allocator overhead: measure with the target Redis version and representative payloads.
+- Replication: multiply by replica count.
+- Fragmentation/headroom: reserve operational margin; do not size to `maxmemory` exactly.
+
+## Required benchmark
+
+Before production sizing, create representative sessions with the largest expected metadata, then measure `MEMORY USAGE` for each key family and extrapolate to:
+
+- 1 million sessions
+- 10 million sessions
+- 50 million sessions
+
+Include token indexes, user indexes, replication, AOF/RDB overhead, allocator fragmentation, and peak write amplification.
+
+## Operational limits
+
+The package defaults to 8 KiB session metadata, 200-item batches, concurrency 8, and 20 sessions per user. These are conservative defaults, not universal production limits. Increase them only after load testing.
+
+A per-user hash tag intentionally concentrates one user's session state on one slot. Extremely active users can become hot keys/slots; solving that requires a separate sharded-user design and would weaken the simple same-user atomicity model.
+
+Sessions evicted by `maxSessionsPerUser` now have their physical session and token-index keys deleted immediately at eviction time, rather than only being removed from the user index and left to expire on their own TTL. Under high per-user session churn this makes actual Redis memory usage track the configured cap more closely instead of transiently overshooting it by up to one full session TTL's worth of orphaned keys per evicted session.

package/docs/DEPLOYMENT.md

@@ -0,0 +1,22 @@
+# Deployment and Migration
+
+## Rolling deployment
+
+The serializer envelope contains a schema version. New application versions should continue reading the previous supported version during a rolling deployment. Add new fields rather than changing the meaning of existing fields in place — for example, `SessionRecord.idleTimeoutSeconds` (0.5.0) was added as a new optional field to preserve rotation/touch idle-window behavior, rather than repurposing an existing field. A record written by an older version simply omits it, and the serializer's schema validation treats it as optional.
+
+Lua scripts are embedded and versioned with the package build. `EVALSHA` is attempted first; after a `NOSCRIPT` response the exact source is sent with `EVAL`, allowing Redis restart/failover to recover without an external script preload step.
+
+## Rollback
+
+1. Keep old application binaries available until all new sessions are compatible with the old reader.
+2. Do not remove old serializer support until the compatibility window closes.
+3. Roll back application code before removing Redis key formats.
+4. Clean obsolete indexes only with bounded maintenance jobs.
+
+## Disaster recovery
+
+Redis authentication state is security-sensitive. Restoring an old RDB/AOF snapshot can resurrect sessions or undo revocations that happened after the snapshot. Treat restore as a security event and invalidate the affected authentication state using an authoritative security-version mechanism at the application/platform level.
+
+## Memory policy
+
+Authentication state should not use an arbitrary eviction policy. `noeviction` is used in the included disposable test environments so memory pressure fails writes instead of silently evicting authentication records. Production capacity and failover requirements must be validated independently.

package/docs/README-API.md

@@ -0,0 +1,15 @@
+# API Notes
+
+## Authorization boundary
+
+The package does not know whether the caller is an administrator or the owner of a user account. `revokeAll(userId)` and `list(userId)` therefore must be called only after the host authentication/authorization layer has established permission. The package intentionally does not accept a caller-supplied user ID as proof of authorization.
+
+## Token lookup
+
+`validate(token)` performs a token-hash lookup, then loads and validates the authoritative session record and checks the per-user authorization index. No raw token is used as a Redis key.
+
+## Revocation store
+
+Use `RedisRevocationStore` for credentials whose authorization model is JTI-based, such as externally issued JWTs. For the opaque stateful sessions in this package, session state itself is the source of truth and a separate revocation key is intentionally not consulted on every request.
+
+`RedisRevocationStore.revoke(jti, now, expiresAt, reason?)` takes an explicit `now` (Unix seconds) rather than reading `Date.now()` internally, so callers should source `now` from the same clock used elsewhere in their system (e.g. Redis `TIME`, as `SessionService` does) to avoid clock-skew affecting the tombstone TTL.

package/docs/STATE-MACHINE.md

@@ -0,0 +1,38 @@
+# Session State Machine
+
+```text
+ACTIVE ───────► CONSUMED
+  │                │
+  │                ▼
+  └────────────► REVOKED
+  │
+  ▼
+EXPIRED (derived by time)
+  │
+  ▼
+DELETED (physical cleanup)
+```
+
+### Rules
+
+- `ACTIVE` is the only state that can authenticate.
+- `CONSUMED` cannot authenticate and is retained only for bounded replay detection.
+- `REVOKED` cannot authenticate.
+- Redis TTL may physically delete any state after its security usefulness ends.
+- `destroy` is physical deletion and idempotent.
+- `revoke` is logical denial and idempotent.
+- `rotate` atomically consumes the predecessor before successor creation.
+- A stale user-index member cannot authenticate because validation requires active session state and current index membership.
+
+## Operation semantics
+
+| Operation | Source | Result | Atomicity | Retry |
+|---|---|---|---|---|
+| create | none | active | session + user index same-slot Lua; on eviction, also same-slot `DEL` of the evicted session/token-index keys; token locator is a separate, cross-slot secondary write | not idempotent |
+| validate | active candidate | read-only decision | no transaction needed | safe read retry by application |
+| touch | active | active | same-key Lua | monotonic/idempotent effect |
+| update | active | active | same-key Lua + version | safe only with version semantics |
+| rotate | active | predecessor consumed + new active session | predecessor Lua consume is atomic; a same-slot but separate `ZREM` then removes it from the user index (self-heals via `list()` if interrupted); successor cross-slot write separate | not inherently idempotent |
+| revoke | active/revoked | revoked/deleted | same-key Lua marks the record; a same-slot but separate `ZREM` then removes it from the user index (self-heals via `list()` if interrupted) | idempotent |
+| destroy | any | deleted | individual writes | idempotent |
+| revokeAll | user index | bounded deletion | bounded per-user pipeline | idempotent per batch |

package/docs/TESTING.md

@@ -0,0 +1,37 @@
+# Testing Matrix
+
+The project separates deterministic unit/security tests from real Redis tests.
+
+## Required CI layers
+
+1. TypeScript strict typecheck.
+2. ESLint.
+3. Unit tests for token generation, hashing, key hashing, serializer, configuration, cookie serialization, and Pub/Sub message/error handling (connection error resilience, malformed-message dropping, subscribe/unsubscribe deduplication).
+4. Security tests ensuring no raw-token persistence is part of the repository contract and invalid credentials fail closed.
+5. Concurrency tests against real Redis for simultaneous touch, update, rotate, revoke, and max-session operations.
+6. Standalone integration tests.
+7. Sentinel integration tests with master/replica/Sentinel failover.
+8. Cluster integration tests with multiple primaries/replicas, MOVED/ASK handling, resharding, and node failure.
+9. Load/performance tests using bounded concurrency.
+
+## Shared Redis safety
+
+Tests must use a unique namespace per run. Never use `FLUSHALL` or `FLUSHDB` against a shared Redis deployment.
+
+## Failure injection
+
+Production verification should include:
+
+- connection loss during reads;
+- connection loss after a server-side write;
+- primary failure and promotion;
+- cluster slot migration;
+- command-level pipeline errors;
+- malformed session payloads;
+- malformed cache/Pub-Sub payloads (non-JSON values written or published by a non-conforming client);
+- stale token indexes;
+- stale user-index members;
+- Redis memory pressure;
+- old backup restore scenarios.
+
+The current archive includes the standalone real-Redis integration harness. Sentinel and Cluster environments are supplied as disposable Docker definitions; their failover/resharding tests should be exercised in CI where Docker networking and Redis administration are available.

package/docs/THREAT-MODEL.md

@@ -0,0 +1,23 @@
+# Threat Model
+
+| Threat | Asset | Mitigation | Residual risk / test target |
+|---|---|---|---|
+| Stolen session token | Authentication state | 256-bit secret; SHA-256 storage; TLS expected; revocation/rotation | Bearer token remains a bearer credential; test token theft/replay |
+| Token brute force | Session lookup | 256-bit random secret | Computationally infeasible; test format rejection |
+| Token enumeration | Authentication existence | Opaque token; safe invalid results | Timing differences should be monitored; public APIs should not expose internal reasons |
+| Session fixation | Login/session identity | Fresh random token creation and rotation | Host auth flow must replace pre-auth session after authentication |
+| Replay after rotation | Refresh/session credential | Atomic predecessor consumption | Rotation is non-idempotent; test concurrent rotate |
+| Replay after logout | Session state | revoke/destroy + index checks | A request already authorized before logout may complete; authorization transaction boundaries remain application-specific |
+| Concurrent attacker requests | Session state | Lua state transitions and version checks | Test simultaneous touch/update/rotate |
+| Redis outage | Authentication state | Fail closed; storage errors distinct from invalid sessions | Application decides 401 vs 503; never fail open |
+| Uncaught connection-error crash | Availability (whole process) | Default no-op `'error'` listener attached to every Redis connection, including the Pub/Sub subscriber connection | The default listener only prevents the crash; applications needing alerting must still attach their own `'error'` listener on the connection |
+| Malformed cached/published payload | Availability | `RedisCache.get()` throws a typed `CacheError`; `RedisPubSub` silently drops an unparseable message | Neither crashes the process; a cache read failure still surfaces as an error to the caller rather than a silent miss |
+| Redis data exposure | Session metadata | Optional AES-256-GCM; TLS/ACLs/private network | Compromised app with key can decrypt |
+| Stale secondary index | Authorization | Session record independently validated; index only denies | `create()` eviction, `revoke()`, and rotation's `consume()` now remove their affected index member eagerly (not only via `list()`'s lazy self-heal), shrinking the window in which a stale entry can exist and be counted toward `maxSessionsPerUser` |
+| Redis eviction | Session state | TTL + index checks; operational memory policy required | Eviction can log users out; it must never authenticate them |
+| Old backup restore | Revocation state | Document restore as security event | Requires deployment-level security-version invalidation strategy |
+| CSRF | Cookie credential | Cookie flags + framework-level CSRF strategy | SameSite is not universal CSRF protection |
+| XSS | Browser auth state | HttpOnly cookie option | XSS can still act as user in browser; application CSP/output encoding required |
+| CORS misconfiguration | Credentialed browser requests | No framework CORS policy inside core | Host application must whitelist origins and never wildcard credentialed requests |
+| Hot user slot | Availability | Per-user hash tag; bounded operations | A single extremely active user can concentrate load |
+| Memory exhaustion | Redis availability | Metadata/pipeline/batch bounds | Deployment still needs capacity planning |

package/docs/TYPE-SAFETY.md

@@ -0,0 +1,34 @@
+# Type Safety and Verification
+
+This package is authored for TypeScript strict mode with ESM and Node.js 22+.
+
+## What is guaranteed by the source
+
+- No `any` is used in package source modules.
+- Public module APIs use explicit exported types.
+- Redis internals are hidden behind `RedisClientWrapper`.
+- Pub/Sub uses a type-only import for `Redis`, which is required when `verbatimModuleSyntax` is enabled.
+- Optional properties are authored to work with `exactOptionalPropertyTypes`.
+- Runtime configuration is validated before it reaches module constructors.
+
+## Required verification
+
+Run the following after installing dependencies:
+
+```bash
+bun install
+bun run typecheck
+bun run build
+bun run lint
+bun run test
+```
+
+Integration tests require Redis and are intentionally separated:
+
+```bash
+bun run test:integration
+```
+
+### 0.5.0 verification note
+
+Earlier releases of this document recorded that dependency-backed `tsc`/Vitest execution could not be performed in the environment used to prepare the archive. That limitation does not apply to the 0.5.0 bug-fix pass: `bun run typecheck` (equivalently `tsc -p tsconfig.json --noEmit`), `bun run lint`, `bun run test`, and `bun run build` were all executed against the installed dependencies and passed, including a full rebuild of `dist/` verified to emit real ESM (the previously committed `dist/` had drifted to stale CommonJS output — see the Changelog). Do not treat a structural audit as a substitute for actually running these commands; the note above only documents that, for this pass, they were run.

package/docs/modules/cache/README.md

@@ -0,0 +1,7 @@
+# Cache module
+
+This directory contains the complete usage documentation for the cache module.
+
+**Full guide:** [usage.md](./usage.md)
+
+The usage guide documents configuration, public types, every public method, arguments, return values, semantics, error/edge-case behavior, and multiple examples.