ioredis-toolkit 0.0.1

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

@@ -0,0 +1,36 @@
+import type { RedisClientWrapper } from '../client.js';
+export declare const SCRIPT_NAMES: readonly ['create', 'touch', 'touchEncrypted', 'rotate', 'rotateEncrypted', 'delete', 'revoke', 'conditionalUpdate', 'conditionalUpdateEncrypted', 'deleteByUser', 'cleanupIndex', 'enforceLimit', 'validate'];
+export type ScriptName = (typeof SCRIPT_NAMES)[number];
+/** Loads a script source from disk relative to this module. */
+export declare function loadScriptSource(name: ScriptName): string;
+export interface SessionScriptRegistryOptions {
+    /** Override script sources (used by tests to inject fixtures). */
+    sources?: Partial<Record<ScriptName, string>>;
+}
+/**
+ * Loads and executes the session Lua scripts through a single client.
+ * Stateless besides the script sources and SHA digests.
+ */
+export declare class SessionScriptRegistry {
+    private readonly sources;
+    private readonly client;
+    private shas;
+    private loaded;
+    constructor(client: RedisClientWrapper, options?: SessionScriptRegistryOptions);
+    /** Returns the raw source of a script (for tests and audits). */
+    source(name: ScriptName): string;
+    /**
+     * Pre-loads every script with SCRIPT LOAD. Best-effort: when loading
+     * fails (e.g. Redis briefly unavailable at startup), the EVALSHA +
+     * NOSCRIPT fallback keeps working, so authentication is never blocked
+     * by a failed preload.
+     */
+    preload(): Promise<void>;
+    /**
+     * Executes a script by name with EVALSHA, falling back to EVAL on
+     * NOSCRIPT (script cache evicted / node restarted).
+     */
+    eval(name: ScriptName, numKeys: number, ...args: Array<string | number | Buffer>): Promise<unknown>;
+    /** Marks the registry dirty (e.g. after tests replaced the client). */
+    invalidate(): void;
+}

package/dist/session/session-scripts.js

@@ -0,0 +1,130 @@
+import { readFileSync } from 'node:fs';
+import { SessionConfigurationError } from './session-errors.js';
+/* -------------------------------------------------------------------------- */
+/* Lua script registry.                                                        */
+/*                                                                             */
+/* Scripts live as versioned .lua files (src/session/scripts/) and are         */
+/* loaded at construction. The registry handles SCRIPT LOAD + EVALSHA with    */
+/* NOSCRIPT fallback, so scripts survive server script-cache eviction and     */
+/* cluster node restarts.                                                      */
+/*                                                                             */
+/* Script contract (enforced by review, not by machinery):                     */
+/*   - every key is declared in KEYS and shares the user's hash slot          */
+/*   - no cross-slot keys, no KEYS/SCAN, no dynamic Lua construction          */
+/*   - stable integer result codes (documented in each script header)         */
+/*   - bounded loops (batch sizes passed in ARGV)                             */
+/* -------------------------------------------------------------------------- */
+export const SCRIPT_NAMES = [
+    'create',
+    'touch',
+    'touchEncrypted',
+    'rotate',
+    'rotateEncrypted',
+    'delete',
+    'revoke',
+    'conditionalUpdate',
+    'conditionalUpdateEncrypted',
+    'deleteByUser',
+    'cleanupIndex',
+    'enforceLimit',
+    'validate',
+];
+const SCRIPT_FILE = {
+    create: 'create.lua',
+    touch: 'touch.lua',
+    touchEncrypted: 'touch-encrypted.lua',
+    rotate: 'rotate.lua',
+    rotateEncrypted: 'rotate-encrypted.lua',
+    delete: 'delete.lua',
+    revoke: 'revoke.lua',
+    conditionalUpdate: 'conditional-update.lua',
+    conditionalUpdateEncrypted: 'conditional-update-encrypted.lua',
+    deleteByUser: 'delete-by-user.lua',
+    cleanupIndex: 'cleanup-index.lua',
+    enforceLimit: 'enforce-limit.lua',
+    validate: 'validate.lua',
+};
+/** Loads a script source from disk relative to this module. */
+export function loadScriptSource(name) {
+    const url = new URL(`./scripts/${SCRIPT_FILE[name]}`, import.meta.url);
+    try {
+        return readFileSync(url, 'utf8');
+    }
+    catch (error) {
+        throw new SessionConfigurationError(`Failed to load Lua script "${SCRIPT_FILE[name]}" (${url.pathname}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Loads and executes the session Lua scripts through a single client.
+ * Stateless besides the script sources and SHA digests.
+ */
+export class SessionScriptRegistry {
+    sources;
+    client;
+    shas = {};
+    loaded = false;
+    constructor(client, options = {}) {
+        this.client = client;
+        const sources = {};
+        for (const name of SCRIPT_NAMES) {
+            sources[name] = options.sources?.[name] ?? loadScriptSource(name);
+        }
+        this.sources = sources;
+    }
+    /** Returns the raw source of a script (for tests and audits). */
+    source(name) {
+        return this.sources[name];
+    }
+    /**
+     * Pre-loads every script with SCRIPT LOAD. Best-effort: when loading
+     * fails (e.g. Redis briefly unavailable at startup), the EVALSHA +
+     * NOSCRIPT fallback keeps working, so authentication is never blocked
+     * by a failed preload.
+     */
+    async preload() {
+        if (this.loaded)
+            return;
+        const results = await Promise.allSettled(SCRIPT_NAMES.map((name) => this.client
+            .scriptLoad(this.sources[name])
+            .then((sha) => {
+            this.shas[name] = sha;
+        })));
+        const failed = results.filter((r) => r.status === 'rejected').length;
+        if (failed > 0) {
+            // Scripts will still work via the EVAL fallback path.
+            this.loaded = false;
+            return;
+        }
+        this.loaded = true;
+    }
+    /**
+     * Executes a script by name with EVALSHA, falling back to EVAL on
+     * NOSCRIPT (script cache evicted / node restarted).
+     */
+    async eval(name, numKeys, ...args) {
+        const sha = this.shas[name];
+        const source = this.sources[name];
+        if (sha) {
+            try {
+                return await this.client.evalsha(sha, source, numKeys, ...args);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (!message.includes('NOSCRIPT'))
+                    throw error;
+                // Fall through to EVAL and refresh the cached SHA.
+            }
+        }
+        const result = await this.client.eval(source, numKeys, ...args);
+        if (sha) {
+            // EVAL succeeds only when the server has the script; update the SHA.
+            this.shas[name] = sha;
+        }
+        return result;
+    }
+    /** Marks the registry dirty (e.g. after tests replaced the client). */
+    invalidate() {
+        this.loaded = false;
+        this.shas = {};
+    }
+}

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

@@ -0,0 +1,42 @@
+import type { SessionKeyProvider } from './session-encryption.js';
+import type { EncryptedSessionEnvelope, SessionRecord } from './session-types.js';
+export type EnvelopeKind = 'plain' | 'encrypted' | 'unknown';
+/**
+ * Runtime validation of an arbitrary parsed value against the SessionRecord
+ * shape. Returns the validated record or throws SessionSerializationError
+ * with a machine-readable reason. Never casts blindly.
+ */
+export declare function validateSessionRecord(value: unknown): SessionRecord;
+/**
+ * Serializes a record into the plain v1 envelope.
+ */
+export declare function serializeSession(record: SessionRecord): string;
+/**
+ * Serializes a record into the encrypted v2 envelope, mirroring the
+ * script-readable plaintext header from the record.
+ */
+export declare function serializeEncryptedSession(record: SessionRecord, provider: SessionKeyProvider): string;
+/** Cheap kind detection without full parsing (for script mode selection). */
+export declare function envelopeKind(raw: string): EnvelopeKind;
+/**
+ * Deserializes a stored envelope into a validated SessionRecord.
+ *
+ * @throws {SessionSerializationError} for unknown schema versions, malformed
+ *   JSON, malformed records, and encryption failures (auth tag, unknown key
+ *   version). The caller decides how to handle the corrupt record (invalidate
+ *   + clean up); this never crashes the process.
+ */
+export declare function deserializeSession(raw: string, keyProvider?: SessionKeyProvider): SessionRecord;
+/**
+ * Builds the plaintext header mirrors for an encrypted envelope from a
+ * record. Used by the repository when re-encrypting on touch/rotate/update.
+ */
+export declare function encryptedHeaderOf(record: SessionRecord): Pick<EncryptedSessionEnvelope, 'st' | 'ver' | 'la' | 'idle' | 'exp' | 'rn' | 'rj'>;
+/**
+ * Verifies that a decrypted v2 record agrees with the envelope's plaintext
+ * header mirrors. The ciphertext is authoritative; a disagreement means the
+ * envelope was built from stale or inconsistent state and MUST fail closed.
+ *
+ * @throws {SessionSerializationError} on any mismatch.
+ */
+export declare function assertHeaderMatches(envelope: EncryptedSessionEnvelope, record: SessionRecord): void;

package/dist/session/session-serializer.js

@@ -0,0 +1,248 @@
+import { SessionSerializationError } from './session-errors.js';
+import { decryptJson, encryptJson } from './session-encryption.js';
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+function isString(v) {
+    return typeof v === 'string';
+}
+function isNullish(v) {
+    return v === null || v === undefined;
+}
+function isSecondsTimestamp(v) {
+    return typeof v === 'number' && Number.isSafeInteger(v) && v > 0;
+}
+function isOptionalSecondsTimestamp(v) {
+    return isNullish(v) || isSecondsTimestamp(v);
+}
+function isStatus(v) {
+    return v === 'active' || v === 'consumed' || v === 'revoked';
+}
+function isOptionalString(v, maxLength = 1024) {
+    return isNullish(v) || (typeof v === 'string' && v.length <= maxLength);
+}
+const MAX_METADATA_DEPTH = 5;
+const MAX_METADATA_KEYS = 128;
+function isPlainMetadata(v, depth = 0) {
+    if (v === null || v === undefined)
+        return true;
+    if (typeof v === 'string' || typeof v === 'boolean')
+        return true;
+    if (typeof v === 'number')
+        return Number.isFinite(v);
+    if (Array.isArray(v)) {
+        if (depth >= MAX_METADATA_DEPTH)
+            return false;
+        return v.every((item) => isPlainMetadata(item, depth + 1));
+    }
+    if (typeof v === 'object') {
+        if (depth >= MAX_METADATA_DEPTH)
+            return false;
+        const keys = Object.keys(v);
+        if (keys.length > MAX_METADATA_KEYS)
+            return false;
+        return keys.every((key) => key.length <= 128 && isPlainMetadata(v[key], depth + 1));
+    }
+    return false;
+}
+/**
+ * Runtime validation of an arbitrary parsed value against the SessionRecord
+ * shape. Returns the validated record or throws SessionSerializationError
+ * with a machine-readable reason. Never casts blindly.
+ */
+export function validateSessionRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new SessionSerializationError({ reason: 'not_an_object' });
+    }
+    const r = value;
+    const jti = r.jti;
+    if (!isString(jti) || jti.length < 20 || jti.length > 100 || !BASE64URL.test(jti)) {
+        throw new SessionSerializationError({ reason: 'invalid_jti' });
+    }
+    const userId = r.userId;
+    if (!isString(userId) || userId.length === 0 || userId.length > 512) {
+        throw new SessionSerializationError({ reason: 'invalid_user_id' });
+    }
+    const createdAt = r.createdAt;
+    const lastAccessedAt = r.lastAccessedAt;
+    const absoluteExpiresAt = r.absoluteExpiresAt;
+    if (!isSecondsTimestamp(createdAt))
+        throw new SessionSerializationError({ reason: 'invalid_created_at' });
+    if (!isSecondsTimestamp(lastAccessedAt))
+        throw new SessionSerializationError({ reason: 'invalid_last_accessed_at' });
+    if (!isSecondsTimestamp(absoluteExpiresAt))
+        throw new SessionSerializationError({ reason: 'invalid_absolute_expiry' });
+    const idleExpiresAt = r.idleExpiresAt;
+    if (!isOptionalSecondsTimestamp(idleExpiresAt)) {
+        throw new SessionSerializationError({ reason: 'invalid_idle_expiry' });
+    }
+    const status = r.status;
+    if (!isStatus(status))
+        throw new SessionSerializationError({ reason: 'invalid_status' });
+    const version = r.version;
+    if (typeof version !== 'number' || !Number.isSafeInteger(version) || version < 0) {
+        throw new SessionSerializationError({ reason: 'invalid_version' });
+    }
+    const securityVersion = r.securityVersion;
+    if (!isNullish(securityVersion) && (typeof securityVersion !== 'number' || !Number.isSafeInteger(securityVersion) || securityVersion < 0)) {
+        throw new SessionSerializationError({ reason: 'invalid_security_version' });
+    }
+    const validatedSecurityVersion = securityVersion ?? null;
+    if (!isOptionalString(r.deviceId))
+        throw new SessionSerializationError({ reason: 'invalid_device_id' });
+    if (!isOptionalString(r.ipAddress))
+        throw new SessionSerializationError({ reason: 'invalid_ip_address' });
+    if (!isOptionalString(r.userAgent))
+        throw new SessionSerializationError({ reason: 'invalid_user_agent' });
+    const metadata = r.metadata;
+    if (!isNullish(metadata) && !isPlainMetadata(metadata)) {
+        throw new SessionSerializationError({ reason: 'invalid_metadata' });
+    }
+    if (!isNullish(r.rotatedFrom) && !isString(r.rotatedFrom)) {
+        throw new SessionSerializationError({ reason: 'invalid_rotated_from' });
+    }
+    if (!isNullish(r.rotatedTo) && !isString(r.rotatedTo)) {
+        throw new SessionSerializationError({ reason: 'invalid_rotated_to' });
+    }
+    if (!isNullish(r.consumedAt) && !isSecondsTimestamp(r.consumedAt)) {
+        throw new SessionSerializationError({ reason: 'invalid_consumed_at' });
+    }
+    if (!isNullish(r.rotationNonceHash) && !isString(r.rotationNonceHash)) {
+        throw new SessionSerializationError({ reason: 'invalid_rotation_nonce_hash' });
+    }
+    return {
+        jti,
+        userId,
+        createdAt,
+        lastAccessedAt,
+        absoluteExpiresAt,
+        idleExpiresAt: idleExpiresAt ?? null,
+        status,
+        version,
+        securityVersion: validatedSecurityVersion,
+        deviceId: r.deviceId ?? null,
+        ipAddress: r.ipAddress ?? null,
+        userAgent: r.userAgent ?? null,
+        metadata: metadata ?? null,
+        rotatedFrom: r.rotatedFrom ?? null,
+        rotatedTo: r.rotatedTo ?? null,
+        consumedAt: r.consumedAt ?? null,
+        rotationNonceHash: r.rotationNonceHash ?? null,
+    };
+}
+/**
+ * Serializes a record into the plain v1 envelope.
+ */
+export function serializeSession(record) {
+    return JSON.stringify({ v: 1, s: record });
+}
+/**
+ * Serializes a record into the encrypted v2 envelope, mirroring the
+ * script-readable plaintext header from the record.
+ */
+export function serializeEncryptedSession(record, provider) {
+    const body = encryptJson(JSON.stringify(record), provider);
+    const envelope = {
+        v: 2,
+        e: 1,
+        ...body,
+        st: record.status,
+        ver: record.version,
+        la: record.lastAccessedAt,
+        idle: record.idleExpiresAt,
+        exp: record.absoluteExpiresAt,
+        rn: record.rotationNonceHash,
+        rj: record.rotatedTo,
+    };
+    return JSON.stringify(envelope);
+}
+/** Cheap kind detection without full parsing (for script mode selection). */
+export function envelopeKind(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && parsed.v === 1)
+            return 'plain';
+        if (parsed && typeof parsed === 'object' && parsed.v === 2 && parsed.e === 1)
+            return 'encrypted';
+        return 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Deserializes a stored envelope into a validated SessionRecord.
+ *
+ * @throws {SessionSerializationError} for unknown schema versions, malformed
+ *   JSON, malformed records, and encryption failures (auth tag, unknown key
+ *   version). The caller decides how to handle the corrupt record (invalidate
+ *   + clean up); this never crashes the process.
+ */
+export function deserializeSession(raw, keyProvider) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new SessionSerializationError({ reason: 'invalid_json' });
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new SessionSerializationError({ reason: 'not_an_object' });
+    }
+    const envelope = parsed;
+    if (envelope.v === 1) {
+        return validateSessionRecord(envelope.s);
+    }
+    if (envelope.v === 2) {
+        if (!keyProvider) {
+            throw new SessionSerializationError({ reason: 'encrypted_without_provider' });
+        }
+        const body = envelope;
+        if (body.e !== 1) {
+            throw new SessionSerializationError({ reason: 'unknown_encryption_version' });
+        }
+        return validateSessionRecord(decryptJson(body, keyProvider));
+    }
+    throw new SessionSerializationError({ reason: 'unsupported_schema_version' });
+}
+/**
+ * Builds the plaintext header mirrors for an encrypted envelope from a
+ * record. Used by the repository when re-encrypting on touch/rotate/update.
+ */
+export function encryptedHeaderOf(record) {
+    return {
+        st: record.status,
+        ver: record.version,
+        la: record.lastAccessedAt,
+        idle: record.idleExpiresAt,
+        exp: record.absoluteExpiresAt,
+        rn: record.rotationNonceHash,
+        rj: record.rotatedTo,
+    };
+}
+/**
+ * Verifies that a decrypted v2 record agrees with the envelope's plaintext
+ * header mirrors. The ciphertext is authoritative; a disagreement means the
+ * envelope was built from stale or inconsistent state and MUST fail closed.
+ *
+ * @throws {SessionSerializationError} on any mismatch.
+ */
+export function assertHeaderMatches(envelope, record) {
+    const header = encryptedHeaderOf(record);
+    const mismatches = [];
+    if (envelope.st !== header.st)
+        mismatches.push('st');
+    if (envelope.ver !== header.ver)
+        mismatches.push('ver');
+    if (envelope.la !== header.la)
+        mismatches.push('la');
+    if (envelope.idle !== header.idle)
+        mismatches.push('idle');
+    if (envelope.exp !== header.exp)
+        mismatches.push('exp');
+    if (envelope.rn !== header.rn)
+        mismatches.push('rn');
+    if (envelope.rj !== header.rj)
+        mismatches.push('rj');
+    if (mismatches.length > 0) {
+        throw new SessionSerializationError({ reason: 'header_mismatch', fields: mismatches });
+    }
+}

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

@@ -0,0 +1,104 @@
+import type { RedisClientWrapper } from '../client.js';
+import type { RevocationStore } from './session-types.js';
+import { SessionCircuitBreaker } from './session-circuit-breaker.js';
+import type { SessionConfig } from './session-config.js';
+import { SessionHealthChecker } from './session-health.js';
+import type { SessionKeyStrategy } from './session-keys.js';
+import { SessionMetrics } from './session-metrics.js';
+import { SessionRepository } from './session-repository.js';
+import type { SessionTokenManager } from './session-token.js';
+import type { CreatedSession, ListOptions, RotateOptions, RotatedSession, SessionCreateInput, SessionRecord, SessionUpdatePatch, SessionValidationResult, TouchOptions, TouchOutcome, UpdateOptions, ValidateOptions } from './session-types.js';
+export interface SessionServiceDeps {
+    config: SessionConfig;
+    client: RedisClientWrapper;
+    repository: SessionRepository;
+    token: SessionTokenManager;
+    keys: SessionKeyStrategy;
+    revocationStore?: RevocationStore;
+    metrics?: SessionMetrics;
+    circuitBreaker?: SessionCircuitBreaker;
+    health?: SessionHealthChecker;
+    now?: () => number;
+}
+export declare class SessionService {
+    private readonly deps;
+    private readonly throttle;
+    constructor(deps: SessionServiceDeps);
+    private get config();
+    private get repository();
+    private get metrics();
+    private get breaker();
+    private get healthChecker();
+    private now;
+    private guard;
+    /**
+     * Creates a session and returns the raw token exactly once.
+     *
+     * Idempotent creation: when `input.idempotencyKey` is provided (and
+     * config.enableCreateIdempotency is on), the idempotencyKey IS the token.
+     * A retry with the same key returns the existing session with
+     * `replayed: true` instead of creating a duplicate.
+     */
+    create(input: SessionCreateInput): Promise<CreatedSession>;
+    /**
+     * Validates a session token. Single Redis round trip when userId is known.
+     * Never throws for invalid sessions; throws only for infrastructure
+     * failures (fail closed) and configuration errors.
+     */
+    validate(token: string, options?: ValidateOptions): Promise<SessionValidationResult>;
+    /**
+     * Refreshes activity. Throttled by touchInterval (in-script + in-memory
+     * optimizations). Never resurrects an idle-expired session.
+     */
+    touch(token: string, options?: TouchOptions): Promise<TouchOutcome>;
+    /**
+     * Single-use atomic rotation with retry-safe idempotency (rotationNonce).
+     */
+    rotate(token: string, options?: RotateOptions): Promise<RotatedSession>;
+    /**
+     * Patch update of non-security fields (device/ip/ua/metadata) with
+     * optimistic concurrency.
+     */
+    update(token: string, patch: SessionUpdatePatch, options?: UpdateOptions): Promise<SessionRecord>;
+    /** Physically deletes a session (idempotent). */
+    destroy(token: string, options?: {
+        userId?: string;
+    }): Promise<boolean>;
+    /**
+     * Logically revokes a session (keeps a bounded tombstone).
+     * Returns 'revoked' | 'already_revoked' | 'not_found'.
+     */
+    revoke(token: string, options?: {
+        userId?: string;
+    }): Promise<string>;
+    /** Revokes every session of a user (bounded, fail-closed on partial). */
+    revokeAll(userId: string): Promise<number>;
+    /** Deletes every session of a user (physical, bounded). */
+    deleteByUser(userId: string): Promise<string[]>;
+    /** Lists a user's sessions (oldest first). */
+    findByUser(userId: string, options?: ListOptions): Promise<SessionRecord[]>;
+    /** Alias of {@link findByUser} for listing. */
+    list(userId: string, options?: ListOptions): Promise<SessionRecord[]>;
+    /**
+     * Sets (or bumps) the user's security version, invalidating every session
+     * captured at an older version. Use after password/MFA changes.
+     */
+    setSecurityVersion(userId: string, version?: number): Promise<number>;
+    getSecurityVersion(userId: string): Promise<number | null>;
+    /** Dependency health (PING latency + recent error rate). */
+    health(): Promise<ReturnType<SessionHealthChecker['check']>>;
+    /**
+     * Resolves the userId for a jti: explicit when provided (fast path), via
+     * the JTI index otherwise. Returns null when the index has no entry.
+     */
+    private resolveUserId;
+    /**
+     * Accepts tokens in the strict issued format (base64url of the configured
+     * entropy) and caller-supplied idempotency keys (bounded printable ASCII),
+     * which are used as tokens for idempotent creation. Rejects everything
+     * else (DoS guard: bounded length, bounded alphabet).
+     */
+    private isAcceptableToken;
+    private checkBinding;
+    private bestEffortCleanup;
+}