ioredis-toolkit 0.0.10 → 0.0.12

package/dist/session/session-metrics.js

@@ -1,135 +0,0 @@
-/* -------------------------------------------------------------------------- */
-/* 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',
-    'reconcile_user',
-    '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.
-        }
-    }
-    /**
-     * Records the outcome of one reconcileUser() repair pass: how many
-     * missing/stale jti-index entries it found and repaired or removed.
-     * A non-zero count indicates upstream partial-write drift (ยง67), not an
-     * authentication problem - the session record was authoritative and
-     * correct throughout.
-     */
-    reconcileUser(repaired, removed) {
-        if (!this.adapter)
-            return;
-        try {
-            if (repaired > 0) {
-                this.adapter.incCounter('session.jti_index.reconciled_repaired', repaired, this.topology !== null ? { topology: this.topology } : undefined);
-            }
-            if (removed > 0) {
-                this.adapter.incCounter('session.jti_index.reconciled_removed', removed, 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

@@ -1,184 +0,0 @@
-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;
-        revokeFamilyOnReplay: boolean;
-    }): Promise<{
-        code: number;
-        successorJti?: string;
-        status?: string;
-        familyId?: string;
-        headJtiRevoked?: 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[]>;
-    /**
-     * Bounded per-user repair pass (ยง25/ยง67/ยง68): removes stale user-index
-     * entries (same mechanism as {@link listByUser}) and, when the global jti
-     * index is enabled, repairs any live active session whose jti-index entry
-     * is missing or stale (partial-write drift after create/rotate - the
-     * session record itself was authoritative and correct the whole time,
-     * only JTI-only lookup was degraded). Never touches consumed/revoked/
-     * expired sessions: repairing their index entry would make them
-     * JTI-lookupable again, which is unnecessary and works against prompt
-     * self-expiry.
-     *
-     * Bounded by `limit` (capped like every other list/admin operation);
-     * never scans the whole cluster and is safe to call from an
-     * administrative endpoint, not a hot auth path.
-     */
-    reconcileUser(userId: string, limit: number, now: number): Promise<{
-        checked: number;
-        staleIndexRemoved: number;
-        jtiIndexRepaired: number;
-    }>;
-    /**
-     * 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;