ioredis-toolkit 0.0.1

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

@@ -0,0 +1,87 @@
+import type { EncryptedSessionEnvelope } from './session-types.js';
+/**
+ * Key management abstraction. Applications provide their own implementation
+ * (KMS, secret store, env-based rotation), or a simple in-memory map of
+ * versions to 32-byte keys for single-process deployments.
+ */
+export interface SessionKeyProvider {
+    /**
+     * Returns the encryption key used for all WRITES (new sessions, updates,
+     * re-encryption on touch). Called on every encryption.
+     *
+     * The version labels which key produced the ciphertext: it is stored in
+     * the session envelope (`k` field) so the corresponding key can be looked
+     * up later on read. Always return the current key here — never an
+     * arbitrary one.
+     *
+     * The key may be a 32-byte Buffer or a string (see {@link toKeyBuffer} for
+     * the accepted encodings). Whatever form is returned here must also be
+     * resolvable via {@link getKey} for the same version.
+     */
+    getCurrentKey(): {
+        keyVersion: number;
+        key: Buffer | string;
+    };
+    /**
+     * Returns the key for a specific version, or null when that version is no
+     * longer available. Called on every READ (decryption).
+     *
+     * Every session records the version it was encrypted with; this lookup
+     * resolves it. Returning null makes sessions encrypted with that version
+     * undecryptable — they surface as {@link SessionSerializationError}.
+     *
+     * This is what enables safe key rotation: when the current key changes,
+     * old keys must stay available here so previously written sessions keep
+     * decrypting. Only drop a version once every session using it has expired
+     * or been re-encrypted with the current key.
+     */
+    getKey(keyVersion: number): Buffer | string | null;
+}
+/**
+ * Normalizes a key to a Buffer for use with AES-256-GCM.
+ *
+ * Buffers are returned as-is. Strings are decoded in priority order:
+ *  - 64 hex characters        -> hex
+ *  - base64 / base64url text that decodes to exactly 32 bytes -> base64
+ *  - anything else            -> utf8 (a 32-character passphrase)
+ *
+ * The decoded key must be 32 bytes (AES-256) for Node's crypto to accept
+ * it; {@link StaticSessionKeyProvider} validates this at construction.
+ */
+export declare function toKeyBuffer(key: Buffer | string): Buffer;
+/** A simple key provider for single-process deployments (env/CLI injection). */
+export declare class StaticSessionKeyProvider implements SessionKeyProvider {
+    private readonly currentVersion;
+    private readonly keys;
+    constructor(keys: ReadonlyMap<number, Buffer | string>, currentVersion: number);
+    getCurrentKey(): {
+        keyVersion: number;
+        key: Buffer;
+    };
+    getKey(keyVersion: number): Buffer | null;
+}
+/**
+ * Creates a {@link StaticSessionKeyProvider} with one freshly generated
+ * 32-byte key. Convenience for local development and tests; production
+ * deployments should derive keys from a KMS/vault instead.
+ *
+ * @param keyVersion - Version label for the generated key (default 1).
+ */
+export declare function createRandomSessionKeyProvider(keyVersion?: number): StaticSessionKeyProvider;
+/**
+ * Encrypts a plaintext payload with AES-256-GCM using the current key.
+ * Returns a fresh random IV + auth tag per call.
+ */
+export declare function encryptPayload(plaintext: Buffer, provider: SessionKeyProvider): Pick<EncryptedSessionEnvelope, 'k' | 'i' | 't' | 'c'>;
+/**
+ * Decrypts an envelope, verifying the GCM auth tag.
+ *
+ * @throws {SessionSerializationError} when the key version is unknown, the
+ *   IV/auth tag/ciphertext are malformed, or authentication fails (tampered
+ *   or corrupt data).
+ */
+export declare function decryptPayload(envelope: Pick<EncryptedSessionEnvelope, 'k' | 'i' | 't' | 'c'>, provider: SessionKeyProvider): Buffer;
+/** Encrypts a JSON string into an encrypted envelope body. */
+export declare function encryptJson(json: string, provider: SessionKeyProvider): Pick<EncryptedSessionEnvelope, 'k' | 'i' | 't' | 'c'>;
+/** Decrypts an envelope body and parses the JSON inside. */
+export declare function decryptJson<T>(envelope: Pick<EncryptedSessionEnvelope, 'k' | 'i' | 't' | 'c'>, provider: SessionKeyProvider): T;

package/dist/session/session-encryption.js

@@ -0,0 +1,139 @@
+import { createCipheriv, createDecipheriv, randomBytes, } from 'node:crypto';
+import { SessionConfigurationError, SessionSerializationError } from './session-errors.js';
+/**
+ * Normalizes a key to a Buffer for use with AES-256-GCM.
+ *
+ * Buffers are returned as-is. Strings are decoded in priority order:
+ *  - 64 hex characters        -> hex
+ *  - base64 / base64url text that decodes to exactly 32 bytes -> base64
+ *  - anything else            -> utf8 (a 32-character passphrase)
+ *
+ * The decoded key must be 32 bytes (AES-256) for Node's crypto to accept
+ * it; {@link StaticSessionKeyProvider} validates this at construction.
+ */
+export function toKeyBuffer(key) {
+    if (Buffer.isBuffer(key))
+        return key;
+    const trimmed = key.trim();
+    if (/^[0-9a-fA-F]{64}$/.test(trimmed)) {
+        return Buffer.from(trimmed, 'hex');
+    }
+    if (/^[A-Za-z0-9+/_-]+={0,2}$/.test(trimmed)) {
+        const decoded = Buffer.from(trimmed.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+        if (decoded.length === 32)
+            return decoded;
+    }
+    return Buffer.from(key, 'utf8');
+}
+/** A simple key provider for single-process deployments (env/CLI injection). */
+export class StaticSessionKeyProvider {
+    currentVersion;
+    keys;
+    constructor(keys, currentVersion) {
+        this.currentVersion = currentVersion;
+        if (keys.size === 0) {
+            throw new SessionConfigurationError('At least one encryption key is required.');
+        }
+        if (!keys.has(currentVersion)) {
+            throw new SessionConfigurationError('currentVersion must be present in the key map.');
+        }
+        const normalized = new Map();
+        for (const [version, raw] of keys) {
+            const key = toKeyBuffer(raw);
+            if (key.length !== 32) {
+                throw new SessionConfigurationError(`Encryption key version ${version} must be exactly 32 bytes (AES-256).`);
+            }
+            normalized.set(version, key);
+        }
+        this.keys = normalized;
+    }
+    getCurrentKey() {
+        return { keyVersion: this.currentVersion, key: this.keys.get(this.currentVersion) };
+    }
+    getKey(keyVersion) {
+        return this.keys.get(keyVersion) ?? null;
+    }
+}
+/**
+ * Creates a {@link StaticSessionKeyProvider} with one freshly generated
+ * 32-byte key. Convenience for local development and tests; production
+ * deployments should derive keys from a KMS/vault instead.
+ *
+ * @param keyVersion - Version label for the generated key (default 1).
+ */
+export function createRandomSessionKeyProvider(keyVersion = 1) {
+    return new StaticSessionKeyProvider(new Map([[keyVersion, randomBytes(32)]]), keyVersion);
+}
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+/**
+ * Encrypts a plaintext payload with AES-256-GCM using the current key.
+ * Returns a fresh random IV + auth tag per call.
+ */
+export function encryptPayload(plaintext, provider) {
+    const { keyVersion, key } = provider.getCurrentKey();
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv('aes-256-gcm', toKeyBuffer(key), iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return {
+        k: keyVersion,
+        i: iv.toString('base64url'),
+        t: authTag.toString('base64url'),
+        c: ciphertext.toString('base64url'),
+    };
+}
+/**
+ * Decrypts an envelope, verifying the GCM auth tag.
+ *
+ * @throws {SessionSerializationError} when the key version is unknown, the
+ *   IV/auth tag/ciphertext are malformed, or authentication fails (tampered
+ *   or corrupt data).
+ */
+export function decryptPayload(envelope, provider) {
+    const raw = provider.getKey(envelope.k);
+    if (!raw) {
+        throw new SessionSerializationError({
+            reason: 'unknown_key_version',
+            keyVersion: envelope.k,
+        });
+    }
+    const key = toKeyBuffer(raw);
+    let iv;
+    let tag;
+    let ciphertext;
+    try {
+        iv = Buffer.from(envelope.i, 'base64url');
+        tag = Buffer.from(envelope.t, 'base64url');
+        ciphertext = Buffer.from(envelope.c, 'base64url');
+    }
+    catch {
+        throw new SessionSerializationError({ reason: 'malformed_encrypted_fields' });
+    }
+    if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) {
+        throw new SessionSerializationError({ reason: 'malformed_encrypted_fields' });
+    }
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    }
+    catch {
+        // GCM auth failure = tampered or corrupted data. Treat as invalid.
+        throw new SessionSerializationError({ reason: 'authentication_failed' });
+    }
+}
+/** Encrypts a JSON string into an encrypted envelope body. */
+export function encryptJson(json, provider) {
+    return encryptPayload(Buffer.from(json, 'utf8'), provider);
+}
+/** Decrypts an envelope body and parses the JSON inside. */
+export function decryptJson(envelope, provider) {
+    const plaintext = decryptPayload(envelope, provider);
+    try {
+        return JSON.parse(plaintext.toString('utf8'));
+    }
+    catch {
+        throw new SessionSerializationError({ reason: 'malformed_plaintext' });
+    }
+}

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

@@ -0,0 +1,85 @@
+import { RedisError } from '../errors.js';
+/**
+ * Base class for every session subsystem error.
+ * Extends {@link RedisError} so existing Redis error handling keeps working.
+ */
+export declare class SessionError extends RedisError {
+    constructor(message: string, code?: string, details?: Record<string, unknown>);
+}
+/** The session does not exist (or no longer exists). */
+export declare class SessionNotFoundError extends SessionError {
+    constructor(details?: Record<string, unknown>);
+}
+/** The session expired (absolute or idle timeout), or was created in the past. */
+export declare class SessionExpiredError extends SessionError {
+    constructor(details?: Record<string, unknown>);
+}
+/** The session was revoked or consumed by a rotation (replay detected). */
+export declare class SessionRevokedError extends SessionError {
+    constructor(details?: Record<string, unknown>);
+}
+/** The session record exists but is invalid (corrupt, tampered, mismatched). */
+export declare class SessionInvalidError extends SessionError {
+    constructor(details?: Record<string, unknown>);
+}
+/** A security-sensitive session transition (rotation) failed. */
+export declare class SessionRotationError extends SessionError {
+    constructor(details?: Record<string, unknown>);
+}
+/** Reuse of an already-consumed session token was detected. */
+export declare class SessionReplayError extends SessionError {
+    constructor(details?: Record<string, unknown>);
+}
+/**
+ * Redis (or the session storage backend) is unavailable.
+ *
+ * Authentication MUST fail closed on this error: never treat it as an
+ * invalid session, and never fall back to assuming the session is valid.
+ */
+export declare class SessionStorageError extends SessionError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/** Stored session data could not be deserialized/decrypted. */
+export declare class SessionSerializationError extends SessionError {
+    constructor(details?: Record<string, unknown>);
+}
+/** Session configuration is invalid (fails at manager construction). */
+export declare class SessionConfigurationError extends SessionError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** Optimistic-concurrency conflict on a session update. */
+export declare class SessionConcurrencyError extends SessionError {
+    constructor(details?: Record<string, unknown>);
+}
+/** A revocation could not be persisted (fail closed, do not swallow). */
+export declare class RevocationError extends SessionError {
+    constructor(details?: Record<string, unknown>);
+}
+/** A batch revocation partially failed; check `failures` for details. */
+export declare class RevocationBatchError extends SessionError {
+    /** Safe identifiers of the entries whose pipeline command failed. */
+    readonly failures: Array<{
+        jti: string;
+        error: unknown;
+    }>;
+    constructor(failures: Array<{
+        jti: string;
+        error: unknown;
+    }>);
+    /** Compatibility alias: the affected jtis. */
+    get ids(): string[];
+}
+/** The circuit breaker is open; requests fail closed without touching Redis. */
+export declare class CircuitBreakerOpenError extends SessionError {
+    constructor(details?: Record<string, unknown>);
+}
+/**
+ * Redacts an identifier for safe inclusion in logs/errors/metrics labels.
+ *
+ * Only the length and a short opaque suffix are revealed; never the full
+ * value. Use for jti/userId/deviceId/ipAddress in structured details.
+ *
+ * @example
+ * redactIdentifier('dG9rZW5oYXNo...') // => 'token#c3V'
+ */
+export declare function redactIdentifier(value: string | null | undefined): string;

package/dist/session/session-errors.js

@@ -0,0 +1,145 @@
+import { RedisError } from '../errors.js';
+/* -------------------------------------------------------------------------- */
+/* Typed, safe session errors.                                                 */
+/*                                                                             */
+/* Rules:                                                                      */
+/*  - Never embed raw session tokens, cookies, passwords, encryption keys,     */
+/*    or full session payloads in messages.                                    */
+/*  - JTI/userId are only included in `details` (structured metadata) after    */
+/*    redaction, never as plain strings in `message`.                          */
+/*  - Authentication layers map these errors to HTTP semantics:                */
+/*      SessionStorageError      -> 503 (infrastructure unavailable)           */
+/*      SessionNotFoundError     -> 401                                        */
+/*      SessionExpiredError      -> 401                                        */
+/*      SessionRevokedError      -> 401                                        */
+/*      CircuitBreakerOpenError  -> 503                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * Base class for every session subsystem error.
+ * Extends {@link RedisError} so existing Redis error handling keeps working.
+ */
+export class SessionError extends RedisError {
+    constructor(message, code = 'SESSION_ERROR', details) {
+        super(message, code, details);
+        this.name = 'SessionError';
+    }
+}
+/** The session does not exist (or no longer exists). */
+export class SessionNotFoundError extends SessionError {
+    constructor(details) {
+        super('Session not found.', 'SESSION_NOT_FOUND', details);
+        this.name = 'SessionNotFoundError';
+    }
+}
+/** The session expired (absolute or idle timeout), or was created in the past. */
+export class SessionExpiredError extends SessionError {
+    constructor(details) {
+        super('Session has expired.', 'SESSION_EXPIRED', details);
+        this.name = 'SessionExpiredError';
+    }
+}
+/** The session was revoked or consumed by a rotation (replay detected). */
+export class SessionRevokedError extends SessionError {
+    constructor(details) {
+        super('Session is no longer valid.', 'SESSION_REVOKED', details);
+        this.name = 'SessionRevokedError';
+    }
+}
+/** The session record exists but is invalid (corrupt, tampered, mismatched). */
+export class SessionInvalidError extends SessionError {
+    constructor(details) {
+        super('Session is invalid.', 'SESSION_INVALID', details);
+        this.name = 'SessionInvalidError';
+    }
+}
+/** A security-sensitive session transition (rotation) failed. */
+export class SessionRotationError extends SessionError {
+    constructor(details) {
+        super('Session rotation failed.', 'SESSION_ROTATION_FAILED', details);
+        this.name = 'SessionRotationError';
+    }
+}
+/** Reuse of an already-consumed session token was detected. */
+export class SessionReplayError extends SessionError {
+    constructor(details) {
+        super('Session reuse detected.', 'SESSION_REPLAY', details);
+        this.name = 'SessionReplayError';
+    }
+}
+/**
+ * Redis (or the session storage backend) is unavailable.
+ *
+ * Authentication MUST fail closed on this error: never treat it as an
+ * invalid session, and never fall back to assuming the session is valid.
+ */
+export class SessionStorageError extends SessionError {
+    constructor(message = 'Session storage unavailable.', details) {
+        super(message, 'SESSION_STORAGE_UNAVAILABLE', details);
+        this.name = 'SessionStorageError';
+    }
+}
+/** Stored session data could not be deserialized/decrypted. */
+export class SessionSerializationError extends SessionError {
+    constructor(details) {
+        super('Stored session data is malformed.', 'SESSION_SERIALIZATION_ERROR', details);
+        this.name = 'SessionSerializationError';
+    }
+}
+/** Session configuration is invalid (fails at manager construction). */
+export class SessionConfigurationError extends SessionError {
+    constructor(message, details) {
+        super(message, 'SESSION_CONFIGURATION_ERROR', details);
+        this.name = 'SessionConfigurationError';
+    }
+}
+/** Optimistic-concurrency conflict on a session update. */
+export class SessionConcurrencyError extends SessionError {
+    constructor(details) {
+        super('Session was modified concurrently.', 'SESSION_CONCURRENCY', details);
+        this.name = 'SessionConcurrencyError';
+    }
+}
+/** A revocation could not be persisted (fail closed, do not swallow). */
+export class RevocationError extends SessionError {
+    constructor(details) {
+        super('Revocation could not be persisted.', 'REVOCATION_ERROR', details);
+        this.name = 'RevocationError';
+    }
+}
+/** A batch revocation partially failed; check `failures` for details. */
+export class RevocationBatchError extends SessionError {
+    /** Safe identifiers of the entries whose pipeline command failed. */
+    failures;
+    constructor(failures) {
+        super(`Revocation batch failed for ${failures.length} entr${failures.length === 1 ? 'y' : 'ies'}.`, 'REVOCATION_BATCH_ERROR', { failureCount: failures.length });
+        this.name = 'RevocationBatchError';
+        this.failures = failures;
+    }
+    /** Compatibility alias: the affected jtis. */
+    get ids() {
+        return this.failures.map((f) => f.jti);
+    }
+}
+/** The circuit breaker is open; requests fail closed without touching Redis. */
+export class CircuitBreakerOpenError extends SessionError {
+    constructor(details) {
+        super('Authentication infrastructure is temporarily unavailable.', 'CIRCUIT_OPEN', details);
+        this.name = 'CircuitBreakerOpenError';
+    }
+}
+/**
+ * Redacts an identifier for safe inclusion in logs/errors/metrics labels.
+ *
+ * Only the length and a short opaque suffix are revealed; never the full
+ * value. Use for jti/userId/deviceId/ipAddress in structured details.
+ *
+ * @example
+ * redactIdentifier('dG9rZW5oYXNo...') // => 'token#c3V'
+ */
+export function redactIdentifier(value) {
+    if (!value)
+        return 'none';
+    if (value.length <= 6)
+        return `#${'*'.repeat(value.length)}`;
+    return `${value.slice(0, 3)}…${value.slice(-3)}`;
+}

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

@@ -0,0 +1,38 @@
+import type { RedisClientWrapper } from '../client.js';
+import type { SessionHealthConfig } from './session-config.js';
+export interface SessionHealthStatus {
+    /** True when PING latency and the recent error rate are within thresholds. */
+    healthy: boolean;
+    /** PING round trip in milliseconds, or null when the probe itself failed. */
+    latencyMs: number | null;
+    /** Recent operation error rate (0..1) from the sliding window. */
+    errorRate: number;
+    /** True when Redis is reachable at all (PING succeeded). */
+    reachable: boolean;
+    /** Unix ms of the last probe. */
+    checkedAt: number;
+}
+/**
+ * Periodic PING probe + sliding-window error rate for the session dependency.
+ *
+ * Error-rate sampling is fed by {@link recordOp}; a PING probe runs on every
+ * {@link check}. Both signals must be healthy for the overall status to be
+ * healthy.
+ */
+export declare class SessionHealthChecker {
+    private readonly client;
+    private readonly config;
+    private readonly now;
+    private readonly results;
+    constructor(client: RedisClientWrapper, config: SessionHealthConfig, options?: {
+        now?: () => number;
+    });
+    /** Feeds one operation outcome into the sliding window. */
+    recordOp(success: boolean): void;
+    private errorRate;
+    /**
+     * Runs a PING probe and returns the current health status.
+     * Never throws: probe failures surface as `reachable: false`.
+     */
+    check(): Promise<SessionHealthStatus>;
+}

package/dist/session/session-health.js

@@ -0,0 +1,60 @@
+/**
+ * Periodic PING probe + sliding-window error rate for the session dependency.
+ *
+ * Error-rate sampling is fed by {@link recordOp}; a PING probe runs on every
+ * {@link check}. Both signals must be healthy for the overall status to be
+ * healthy.
+ */
+export class SessionHealthChecker {
+    client;
+    config;
+    now;
+    results = [];
+    constructor(client, config, options = {}) {
+        this.client = client;
+        this.config = config;
+        this.now = options.now ?? (() => Date.now());
+    }
+    /** Feeds one operation outcome into the sliding window. */
+    recordOp(success) {
+        this.results.push(success);
+        const max = this.config.errorWindowSize;
+        if (this.results.length > max) {
+            this.results.splice(0, this.results.length - max);
+        }
+    }
+    errorRate() {
+        if (this.results.length === 0)
+            return 0;
+        let failures = 0;
+        for (const ok of this.results) {
+            if (!ok)
+                failures += 1;
+        }
+        return failures / this.results.length;
+    }
+    /**
+     * Runs a PING probe and returns the current health status.
+     * Never throws: probe failures surface as `reachable: false`.
+     */
+    async check() {
+        const checkedAt = this.now();
+        const started = performance.now();
+        let reachable = true;
+        let latencyMs = null;
+        try {
+            const pong = await this.client.raw.ping();
+            reachable = pong === 'PONG' || pong === true || pong === 'pong';
+            latencyMs = Math.round(performance.now() - started);
+        }
+        catch {
+            reachable = false;
+            latencyMs = null;
+        }
+        const errorRate = this.errorRate();
+        const healthy = reachable &&
+            (latencyMs === null || latencyMs <= this.config.latencyThresholdMs) &&
+            errorRate <= this.config.errorRateThreshold;
+        return { healthy, latencyMs, errorRate, reachable, checkedAt };
+    }
+}

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

@@ -0,0 +1,51 @@
+/**
+ * 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 declare function encodeUserId(userId: string): string;
+/**
+ * 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 declare class SessionKeyStrategy {
+    private readonly namespace;
+    /**
+     * @param namespace - Key namespace, e.g. `'authcore'`.
+     */
+    constructor(namespace: string);
+    private ns;
+    /**
+     * Key of a single session record. Hash-tagged by userId, so all of one
+     * user's session keys share a slot.
+     */
+    sessionKey(userId: string, jti: string): string;
+    /** Key of the user's session index (ZSET, member = jti, score = createdAt). */
+    userIndexKey(userId: string): string;
+    /** Key of the user's security version counter. Same user slot. */
+    securityVersionKey(userId: string): string;
+    /**
+     * 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: string, jti: string): string;
+    /**
+     * 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: string): string;
+    /** Key of a revocation entry (single-key, cluster-safe, no tag needed). */
+    revokedKey(jti: string): string;
+    /**
+     * 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: string): string;
+    /** Index key prefix for namespace-scoped administration. */
+    namespacePrefix(): string;
+}