ioredis-toolkit 0.0.1

package/dist/session/session-keys.js

@@ -0,0 +1,113 @@
+import { SessionConfigurationError } from './session-errors.js';
+/* -------------------------------------------------------------------------- */
+/* Redis key design for Redis Cluster.                                         */
+/*                                                                             */
+/*   session record : {ns}:session:{userId}:session:{jti}                      */
+/*   user index     : {ns}:user-sessions:{userId}          (ZSET)              */
+/*   security ver   : {ns}:security-version:{userId}      (string)             */
+/*   jti index (opt): {ns}:jti-index:{jti}               (cross-slot, global)  */
+/*   revoked (opt)  : {ns}:revoked:{jti}                 (cross-slot, single)  */
+/*                                                                             */
+/* The literal text `{userId}` is the Redis Cluster hash tag: every key of     */
+/* one user shares one slot, enabling atomic Lua scripts per user. No global   */
+/* hash tag is used, so sessions are spread across slots.                      */
+/*                                                                             */
+/* userId values are percent-encoded before embedding: values containing       */
+/* `{`, `}`, `:`, `*`, `?`, `[`, `]` etc. would otherwise break hash tags,     */
+/* glob patterns and key parsing. The encoding is deterministic and            */
+/* collision-free.                                                             */
+/* -------------------------------------------------------------------------- */
+/** Characters kept verbatim in the encoded user id. */
+const SAFE = /^[A-Za-z0-9._-]$/;
+/**
+ * Deterministically encodes a userId for safe embedding in Redis keys.
+ *
+ * Every byte not in [A-Za-z0-9._-] is hex-encoded as %XX (UTF-8 aware),
+ * so `{`, `}`, `:` and glob metacharacters can never appear. The encoding
+ * is injective: distinct userIds always produce distinct encodings.
+ */
+export function encodeUserId(userId) {
+    if (typeof userId !== 'string' || userId.length === 0 || userId.length > 512) {
+        throw new SessionConfigurationError('userId must be a non-empty string of at most 512 chars.');
+    }
+    let out = '';
+    for (let i = 0; i < userId.length; i++) {
+        const ch = userId[i];
+        if (SAFE.test(ch)) {
+            out += ch;
+        }
+        else {
+            for (const byte of Buffer.from(ch, 'utf8')) {
+                out += `%${byte.toString(16).padStart(2, '0')}`;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Deterministic, Cluster-safe key strategy.
+ *
+ * Every key derived here is stable for the lifetime of the process and
+ * identical across horizontally scaled instances (no randomness).
+ */
+export class SessionKeyStrategy {
+    namespace;
+    /**
+     * @param namespace - Key namespace, e.g. `'authcore'`.
+     */
+    constructor(namespace) {
+        const trimmed = namespace.trim();
+        if (!trimmed || trimmed.length > 64 || /[\s{}/:*?[\]]/.test(trimmed)) {
+            throw new SessionConfigurationError('namespace must be 1-64 chars without whitespace or glob/hash-tag metacharacters.');
+        }
+        this.namespace = trimmed;
+    }
+    ns(part) {
+        return `${this.namespace}:${part}`;
+    }
+    /**
+     * Key of a single session record. Hash-tagged by userId, so all of one
+     * user's session keys share a slot.
+     */
+    sessionKey(userId, jti) {
+        return this.ns(`session:{${encodeUserId(userId)}}:session:${jti}`);
+    }
+    /** Key of the user's session index (ZSET, member = jti, score = createdAt). */
+    userIndexKey(userId) {
+        return this.ns(`user-sessions:{${encodeUserId(userId)}}`);
+    }
+    /** Key of the user's security version counter. Same user slot. */
+    securityVersionKey(userId) {
+        return this.ns(`security-version:{${encodeUserId(userId)}}`);
+    }
+    /**
+     * Short-lived idempotent-creation claim key (user slot). Bounded TTL is
+     * set by the create script; a claim only ever suppresses a duplicate.
+     */
+    createClaimKey(userId, jti) {
+        return this.ns(`create-claim:{${encodeUserId(userId)}}:${jti}`);
+    }
+    /**
+     * Key of the optional global JTI -> userId index.
+     * Deliberately NOT hash-tagged: it is cross-slot from the session record
+     * and treated as derived state (see docs/architecture).
+     */
+    jtiIndexKey(jti) {
+        return this.ns(`jti-index:${jti}`);
+    }
+    /** Key of a revocation entry (single-key, cluster-safe, no tag needed). */
+    revokedKey(jti) {
+        return this.ns(`revoked:${jti}`);
+    }
+    /**
+     * Session key prefix for a user, used by Lua eviction to construct keys
+     * from jtis. The `{userId}` hash tag guarantees same-slot construction.
+     */
+    sessionKeyPrefix(userId) {
+        return this.ns(`session:{${encodeUserId(userId)}}:session:`);
+    }
+    /** Index key prefix for namespace-scoped administration. */
+    namespacePrefix() {
+        return `${this.namespace}:`;
+    }
+}

package/dist/session/session-manager.d.ts

@@ -0,0 +1,59 @@
+import type { RedisClientWrapper } from '../client.js';
+import type { RevocationStore } from './session-types.js';
+import { SessionCircuitBreaker } from './session-circuit-breaker.js';
+import type { PartialSessionConfig, SessionConfig } from './session-config.js';
+import { SessionCookieManager } from './session-cookie.js';
+import { SessionHealthChecker } from './session-health.js';
+import type { SessionKeyProvider } from './session-encryption.js';
+import { SessionKeyStrategy } from './session-keys.js';
+import { SessionMetrics } from './session-metrics.js';
+import type { SessionMetricsAdapter } from './session-metrics.js';
+import { SessionRepository } from './session-repository.js';
+import { SessionService } from './session-service.js';
+import { SessionTokenManager } from './session-token.js';
+export type SessionManagerOptions = {
+    /** Redis client (standalone, sentinel or cluster - all supported). */
+    client: RedisClientWrapper;
+    /** Session configuration (defaults applied; see SessionConfigSchema). */
+    config?: PartialSessionConfig;
+    /**
+     * Encryption key provider. REQUIRED when config.encryption.enabled is
+     * true (fail at construction rather than at first write). The provider
+     * should be backed by a KMS/vault in production.
+     */
+    encryptionKeyProvider?: SessionKeyProvider;
+    /** External revocation store (JWT jti denylists etc.). */
+    revocationStore?: RevocationStore;
+    /** Metrics adapter (no-op without it). */
+    metricsAdapter?: SessionMetricsAdapter;
+    /** Optional circuit breaker (enabled via config.circuitBreaker.enabled). */
+    circuitBreaker?: SessionCircuitBreaker;
+    /** Injectable clock for tests. */
+    now?: () => number;
+};
+export declare class SessionManager {
+    readonly config: SessionConfig;
+    readonly service: SessionService;
+    readonly repository: SessionRepository;
+    readonly metrics: SessionMetrics;
+    readonly circuitBreaker: SessionCircuitBreaker | null;
+    readonly health: SessionHealthChecker;
+    readonly cookies: SessionCookieManager;
+    readonly token: SessionTokenManager;
+    readonly keys: SessionKeyStrategy;
+    private readonly scripts;
+    private readonly client;
+    constructor(options: SessionManagerOptions);
+    /** Preloads Lua scripts now (awaits SCRIPT LOAD on all nodes). */
+    init(): Promise<void>;
+    /** No-op for symmetry: the client is owned by the application. */
+    close(): void;
+}
+/**
+ * Creates a session manager. Synchronous: use `await manager.init()` when
+ * eager script preloading matters (first call latency).
+ *
+ * @throws {SessionConfigurationError} when the config is invalid, encryption
+ *   is enabled without a key provider, or sessions are not explicitly enabled.
+ */
+export declare function createSessionManager(options: SessionManagerOptions): SessionManager;

package/dist/session/session-manager.js

@@ -0,0 +1,94 @@
+import { SessionConfigurationError } from './session-errors.js';
+import { SessionCircuitBreaker } from './session-circuit-breaker.js';
+import { parseSessionConfig } from './session-config.js';
+import { SessionCookieManager } from './session-cookie.js';
+import { SessionHealthChecker } from './session-health.js';
+import { SessionKeyStrategy } from './session-keys.js';
+import { SessionMetrics } from './session-metrics.js';
+import { SessionRepository } from './session-repository.js';
+import { SessionScriptRegistry } from './session-scripts.js';
+import { SessionService } from './session-service.js';
+import { SessionTokenManager } from './session-token.js';
+export class SessionManager {
+    config;
+    service;
+    repository;
+    metrics;
+    circuitBreaker;
+    health;
+    cookies;
+    token;
+    keys;
+    scripts;
+    client;
+    constructor(options) {
+        const config = parseSessionConfig(options.config);
+        if (config.encryption.enabled && !options.encryptionKeyProvider) {
+            throw new SessionConfigurationError('encryptionKeyProvider is required when config.encryption.enabled is true.');
+        }
+        if (!config.enabled) {
+            // Constructing an enabled-by-default subsystem would surprise; the
+            // manager is inert until config.enabled is explicitly set.
+            throw new SessionConfigurationError('Session subsystem is not enabled: set config.enabled = true to opt in.');
+        }
+        this.client = options.client;
+        this.config = config;
+        this.token = new SessionTokenManager(config.tokenBytes);
+        this.keys = new SessionKeyStrategy(config.namespace);
+        this.scripts = new SessionScriptRegistry(options.client);
+        this.repository = new SessionRepository({
+            client: options.client,
+            keys: this.keys,
+            config,
+            scripts: this.scripts,
+            keyProvider: options.encryptionKeyProvider ?? null,
+        });
+        this.metrics = new SessionMetrics(options.metricsAdapter, options.client.mode);
+        this.circuitBreaker =
+            options.circuitBreaker ??
+                (config.circuitBreaker.enabled
+                    ? new SessionCircuitBreaker(config.circuitBreaker, {
+                        onTransition: (state) => this.metrics.breakerState(state),
+                    })
+                    : null);
+        this.health = new SessionHealthChecker(options.client, config.health, {
+            ...(options.now !== undefined ? { now: options.now } : {}),
+        });
+        this.cookies = new SessionCookieManager(config.cookie);
+        this.service = new SessionService({
+            config,
+            client: options.client,
+            repository: this.repository,
+            token: this.token,
+            keys: this.keys,
+            ...(options.revocationStore !== undefined
+                ? { revocationStore: options.revocationStore }
+                : {}),
+            metrics: this.metrics,
+            ...(this.circuitBreaker !== null ? { circuitBreaker: this.circuitBreaker } : {}),
+            health: this.health,
+            ...(options.now !== undefined ? { now: options.now } : {}),
+        });
+        // Preload scripts in the background; the EVALSHA + NOSCRIPT fallback
+        // keeps working until (and after) the preload finishes.
+        void this.scripts.preload();
+    }
+    /** Preloads Lua scripts now (awaits SCRIPT LOAD on all nodes). */
+    async init() {
+        await this.scripts.preload();
+    }
+    /** No-op for symmetry: the client is owned by the application. */
+    close() {
+        this.scripts.invalidate();
+    }
+}
+/**
+ * Creates a session manager. Synchronous: use `await manager.init()` when
+ * eager script preloading matters (first call latency).
+ *
+ * @throws {SessionConfigurationError} when the config is invalid, encryption
+ *   is enabled without a key provider, or sessions are not explicitly enabled.
+ */
+export function createSessionManager(options) {
+    return new SessionManager(options);
+}

package/dist/session/session-metrics.d.ts

@@ -0,0 +1,33 @@
+/** Application-provided metrics sink. Implementations must be non-throwing. */
+export interface SessionMetricsAdapter {
+    /** Increments a counter by delta (default 1). */
+    incCounter(name: string, delta?: number, attributes?: Record<string, string | number>): void;
+    /** Records a duration sample (milliseconds). */
+    recordHistogram(name: string, value: number, attributes?: Record<string, string | number>): void;
+    /** Sets a gauge to a value. */
+    setGauge(name: string, value: number, attributes?: Record<string, string | number>): void;
+}
+export type SessionOperation = 'create' | 'validate' | 'touch' | 'rotate' | 'update' | 'destroy' | 'revoke' | 'revoke_all' | 'delete_by_user' | 'list' | 'find_by_user' | 'set_security_version' | 'health';
+/**
+ * Internal session metrics facade. Safe no-op without an adapter.
+ */
+export declare class SessionMetrics {
+    private readonly adapter;
+    private readonly topology;
+    constructor(adapter?: SessionMetricsAdapter | null, topology?: string);
+    /** Adds the constant topology label to an attribute set. */
+    private withTopology;
+    /** Counts a completed session operation, with its outcome. */
+    operation(op: SessionOperation, outcome: 'ok' | 'error' | 'invalid', code?: string): void;
+    /** Records operation latency in milliseconds. */
+    latency(op: SessionOperation, ms: number): void;
+    /** Records the circuit breaker state transition. */
+    breakerState(state: 'closed' | 'open' | 'half_open'): void;
+    /** Records a fail-closed revocation-store failure (a security-relevant miss). */
+    revocationMiss(): void;
+    /** Records encryption failures (key rotation issues, corruption). */
+    encryptionError(reason: string): void;
+    /** Records a failed best-effort jti index write (derived-state degradation). */
+    jtiIndexWriteFailure(): void;
+}
+export declare const SESSION_OPERATIONS: readonly SessionOperation[];

package/dist/session/session-metrics.js

@@ -0,0 +1,112 @@
+/* -------------------------------------------------------------------------- */
+/* Session metrics: minimal, dependency-free observability.                    */
+/*                                                                             */
+/* An adapter is injected by the application (Prometheus, StatsD, OpenTelemetry*/
+/* - whichever the app already uses). Without an adapter every call is a       */
+/* no-op; metrics never throw and never affect the hot path.                   */
+/*                                                                             */
+/* No session tokens or raw identifiers ever reach a metric label.             */
+/* -------------------------------------------------------------------------- */
+const OPERATIONS = [
+    'create',
+    'validate',
+    'touch',
+    'rotate',
+    'update',
+    'destroy',
+    'revoke',
+    'revoke_all',
+    'delete_by_user',
+    'list',
+    'find_by_user',
+    'set_security_version',
+    'health',
+];
+/**
+ * Internal session metrics facade. Safe no-op without an adapter.
+ */
+export class SessionMetrics {
+    adapter;
+    topology;
+    constructor(adapter, topology) {
+        this.adapter = adapter ?? null;
+        this.topology = topology ?? null;
+    }
+    /** Adds the constant topology label to an attribute set. */
+    withTopology(attributes) {
+        if (this.topology !== null)
+            attributes.topology = this.topology;
+        return attributes;
+    }
+    /** Counts a completed session operation, with its outcome. */
+    operation(op, outcome, code) {
+        if (!this.adapter)
+            return;
+        try {
+            const attributes = { outcome };
+            if (code)
+                attributes.code = code;
+            this.adapter.incCounter(`session.${op}.total`, 1, this.withTopology(attributes));
+        }
+        catch {
+            // Metrics must never break authentication.
+        }
+    }
+    /** Records operation latency in milliseconds. */
+    latency(op, ms) {
+        if (!this.adapter)
+            return;
+        try {
+            this.adapter.recordHistogram(`session.${op}.duration_ms`, ms, this.topology !== null ? { topology: this.topology } : undefined);
+        }
+        catch {
+            // Metrics must never break authentication.
+        }
+    }
+    /** Records the circuit breaker state transition. */
+    breakerState(state) {
+        if (!this.adapter)
+            return;
+        try {
+            this.adapter.setGauge('session.circuit_breaker.state', state === 'open' ? 2 : state === 'half_open' ? 1 : 0, this.topology !== null ? { topology: this.topology } : undefined);
+            this.adapter.incCounter(`session.circuit_breaker.${state}`, 1, this.withTopology({}));
+        }
+        catch {
+            // Metrics must never break authentication.
+        }
+    }
+    /** Records a fail-closed revocation-store failure (a security-relevant miss). */
+    revocationMiss() {
+        if (!this.adapter)
+            return;
+        try {
+            this.adapter.incCounter('session.revocation_store.fail_closed', 1, this.topology !== null ? { topology: this.topology } : undefined);
+        }
+        catch {
+            // Metrics must never break authentication.
+        }
+    }
+    /** Records encryption failures (key rotation issues, corruption). */
+    encryptionError(reason) {
+        if (!this.adapter)
+            return;
+        try {
+            this.adapter.incCounter('session.encryption.errors', 1, this.withTopology({ reason }));
+        }
+        catch {
+            // Metrics must never break authentication.
+        }
+    }
+    /** Records a failed best-effort jti index write (derived-state degradation). */
+    jtiIndexWriteFailure() {
+        if (!this.adapter)
+            return;
+        try {
+            this.adapter.incCounter('session.jti_index.write_failures', 1, this.topology !== null ? { topology: this.topology } : undefined);
+        }
+        catch {
+            // Metrics must never break authentication.
+        }
+    }
+}
+export const SESSION_OPERATIONS = OPERATIONS;

package/dist/session/session-repository.d.ts

@@ -0,0 +1,161 @@
+import type { RedisClientWrapper } from '../client.js';
+import type { SessionConfig } from './session-config.js';
+import type { SessionKeyProvider } from './session-encryption.js';
+import type { SessionKeyStrategy } from './session-keys.js';
+import type { SessionScriptRegistry } from './session-scripts.js';
+import type { SessionRecord, SessionUpdatePatch, TouchOutcome } from './session-types.js';
+export declare class SessionRepository {
+    private readonly client;
+    private readonly keys;
+    private readonly config;
+    private readonly scripts;
+    /** Encryption key provider, or null when encryption is disabled. */
+    readonly keyProvider: SessionKeyProvider | null;
+    constructor(options: {
+        client: RedisClientWrapper;
+        keys: SessionKeyStrategy;
+        config: SessionConfig;
+        scripts: SessionScriptRegistry;
+        keyProvider?: SessionKeyProvider | null;
+    });
+    /** True when the repository can decrypt stored sessions. */
+    hasKeyProvider(): boolean;
+    private get encrypted();
+    private get jtiIndexEnabled();
+    private get maxBatchSize();
+    private get maxFanOut();
+    /**
+     * Stores a session atomically with its user index entry and (bounded)
+     * max-session eviction. Returns the outcome; on idempotent replays the
+     * claim's jti identifies the pre-existing session.
+     */
+    create(record: SessionRecord, ttl: number): Promise<{
+        status: 'created';
+    } | {
+        status: 'replayed';
+        jti: string;
+    }>;
+    /**
+     * Reads and deserializes a session. Returns null when missing.
+     * Throws SessionSerializationError when the stored payload is corrupt.
+     */
+    get(userId: string, jti: string): Promise<SessionRecord | null>;
+    /**
+     * Single-round-trip validation read (session + security version).
+     * Returns { found: false } for missing records, or the raw envelope plus
+     * the current security version for further app-side checks.
+     */
+    validateRead(userId: string, jti: string): Promise<{
+        found: false;
+    } | {
+        found: true;
+        raw: string;
+        currentSecurityVersion: number | null;
+    } | {
+        found: true;
+        code: -1;
+        status: string;
+    } | {
+        found: true;
+        code: -2;
+    } | {
+        found: true;
+        code: -3;
+    } | {
+        found: true;
+        code: -4;
+    }>;
+    /** Best-effort removal of a stale jti index entry (never throws). */
+    private cleanupJtiIndex;
+    /**
+     * Throttled monotonic activity refresh.
+     *
+     * Plain sessions: one atomic script (server time). Encrypted sessions:
+     * read + decrypt + re-encrypt + atomic CAS (two round trips).
+     */
+    touch(userId: string, jti: string, force: boolean): Promise<TouchOutcome>;
+    /**
+     * Atomic single-use rotation. Returns the successor jti on success.
+     *
+     * Plain sessions: one script (server time). Encrypted sessions: read +
+     * decrypt + build + atomic script (two round trips).
+     */
+    rotate(options: {
+        userId: string;
+        oldJti: string;
+        successor: SessionRecord;
+        expectedVersion?: number;
+        rotationNonceHash?: string;
+        retainTombstone: boolean;
+    }): Promise<{
+        code: number;
+        successorJti?: string;
+        status?: string;
+    }>;
+    /**
+     * Optimistic-concurrency patch update. Returns the updated record, or
+     * null when missing. Throws SessionConcurrencyError on version conflict.
+     */
+    update(userId: string, jti: string, patch: SessionUpdatePatch, expectedVersion?: number): Promise<SessionRecord | null>;
+    /** Physically deletes a session and its index entry. Idempotent. */
+    destroy(userId: string, jti: string): Promise<boolean>;
+    /**
+     * Logically revokes a session with a bounded tombstone TTL.
+     * Returns 'revoked' | 'already_revoked' | 'not_found'.
+     */
+    revoke(userId: string, jti: string, tombstoneTtl: number): Promise<string>;
+    /**
+     * Lists a user's sessions (oldest first), lazily cleaning stale index
+     * members. Bounded: fetches at most `limit` members plus cleanup batches.
+     */
+    listByUser(userId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<SessionRecord[]>;
+    /**
+     * Deletes all of a user's sessions in bounded same-slot batches.
+     * Returns the jtis whose records were deleted.
+     */
+    deleteByUser(userId: string): Promise<string[]>;
+    /**
+     * Removes stale (missing) members from a user's index. Bounded, safe to
+     * run repeatedly.
+     */
+    cleanupUserIndex(userId: string): Promise<number>;
+    /** Removes specific stale entries from a user's index (bounded). */
+    cleanupIndexEntries(userId: string, jtis: string[]): Promise<string[]>;
+    /**
+     * Standalone max-session enforcement (used after revokeAll-style bulk
+     * operations and by admin repair). Loops in bounded steps until the
+     * index fits the limit or a hard cap is reached.
+     */
+    enforceLimit(userId: string): Promise<number>;
+    /** Sets the current security version for a user (invalidates older sessions). */
+    setSecurityVersion(userId: string, version: number): Promise<void>;
+    /** Reads the current security version for a user, or null when unset. */
+    getSecurityVersion(userId: string): Promise<number | null>;
+    /** Best-effort write of the JTI lookup index (cross-slot, self-healing). */
+    writeJtiIndex(jti: string, userId: string, ttl: number): Promise<boolean>;
+    /** Reads the JTI lookup index (only valid when the index is enabled). */
+    readJtiIndex(jti: string): Promise<string | null>;
+    /** Deletes one JTI index entry (idempotent, cross-slot). */
+    deleteJtiIndex(jti: string): Promise<void>;
+    /**
+     * Deletes JTI index entries through bounded slot-grouped pipelines
+     * (cross-slot fan-out lives here, not in the session layer).
+     */
+    deleteJtiIndexMany(jtis: string[]): Promise<void>;
+    /** Returns the user id behind a jti via the index, or null. */
+    resolveUserIdByJti(jti: string): Promise<string | null>;
+    /** Server time in seconds (authoritative clock). */
+    serverTime(): Promise<number>;
+    /** Number of sessions currently in a user's index. */
+    countByUser(userId: string): Promise<number>;
+    /**
+     * Lists the jtis of a user's sessions (oldest first), bounded to `max`.
+     * Used by bulk operations (revokeAll, deleteByUser).
+     */
+    listJtis(userId: string, max: number): Promise<string[]>;
+}
+/** Validates and normalizes an externally provided record (defense in depth). */
+export declare function normalizeRecord(value: unknown): SessionRecord;