ioredis-toolkit 0.0.9 → 0.0.10

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

@@ -7,7 +7,7 @@ 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';
+import type { CreatedSession, ListOptions, ReconcileUserResult, RotateOptions, RotatedSession, SessionCreateInput, SessionRecord, SessionUpdatePatch, SessionValidationResult, TouchOptions, TouchOutcome, UpdateOptions, ValidateOptions } from './session-types.js';
 export interface SessionServiceDeps {
     config: SessionConfig;
     client: RedisClientWrapper;
@@ -85,6 +85,25 @@ export declare class SessionService {
      */
     setSecurityVersion(userId: string, version?: number): Promise<number>;
     getSecurityVersion(userId: string): Promise<number | null>;
+    /**
+     * Bounded administrative repair pass for one user: prunes stale
+     * user-index entries and, when the global jti index is enabled, rewrites
+     * any missing/stale jti-index entry for that user's live active sessions.
+     *
+     * This is NOT required for authentication correctness - every read path
+     * (validate/touch/rotate) already treats the session record as
+     * authoritative and self-heals stale index entries lazily. This exists
+     * purely to shrink the window during which JTI-only lookup (`find(jti)`
+     * without a known userId) can miss a live session after a partial write
+     * (ยง67), and to give operators a way to proactively repair known drift
+     * (e.g. after a Redis incident) instead of waiting for it to be hit
+     * randomly. Safe to call repeatedly; every effect is idempotent.
+     *
+     * Bounded by config.limits.maxSessionsPerUserHardCap, same as
+     * revokeAll/deleteByUser - never scans the cluster and is not called
+     * from a hot auth path.
+     */
+    reconcileUser(userId: string): Promise<ReconcileUserResult>;
     /** Dependency health (PING latency + recent error rate). */
     health(): Promise<ReturnType<SessionHealthChecker['check']>>;
     /**

package/dist/session/session-service.js

@@ -1,5 +1,5 @@
 import { mapWithConcurrency } from '../cluster.js';
-import { SessionConfigurationError, SessionConcurrencyError, SessionError, SessionExpiredError, SessionInvalidError, SessionNotFoundError, SessionRevokedError, SessionRotationError, SessionSerializationError, SessionStorageError, } from './session-errors.js';
+import { SessionConfigurationError, SessionConcurrencyError, SessionError, SessionExpiredError, SessionInvalidError, SessionNotFoundError, SessionReplayError, SessionRevokedError, SessionRotationError, SessionSerializationError, SessionStorageError, } from './session-errors.js';
 import { SessionMetrics } from './session-metrics.js';
 import { assertHeaderMatches, deserializeSession } from './session-serializer.js';
 const IDEMPOTENCY_MIN_LENGTH = 8;
@@ -150,6 +150,10 @@ export class SessionService {
                 rotatedTo: null,
                 consumedAt: null,
                 rotationNonceHash: null,
+                // First generation of a lineage: familyId equals its own jti (the
+                // convention rotate.lua's self-heal also falls back to for legacy
+                // records missing the field - see session-types.ts).
+                familyId: jti,
             };
             const ttl = Math.max(1, record.absoluteExpiresAt - now);
             const result = await this.repository.create(record, ttl);
@@ -315,6 +319,14 @@ export class SessionService {
                 rotatedTo: null,
                 consumedAt: null,
                 rotationNonceHash: null,
+                // Placeholder only: familyId is an identity field decided
+                // authoritatively from the OLD session, not the app. The plain-path
+                // script (rotate.lua) always overwrites this before writing; the
+                // encrypted path resolves the real value from the just-decrypted
+                // predecessor in SessionRepository.rotate() (Lua can't rewrite
+                // ciphertext, so that's the only place it can be fixed up). Any
+                // syntactically valid jti-shaped string is fine here.
+                familyId: oldJti,
             };
             const result = await this.repository.rotate({
                 userId,
@@ -325,6 +337,7 @@ export class SessionService {
                     : {}),
                 ...(rotationNonceHash !== undefined ? { rotationNonceHash } : {}),
                 retainTombstone: this.config.retainConsumedTombstones,
+                revokeFamilyOnReplay: this.config.revokeFamilyOnReplay,
             });
             if (result.code === 1 || result.code === 2) {
                 const replayed = result.code === 2;
@@ -346,6 +359,23 @@ export class SessionService {
                 // and re-authenticate rather than reusing the old token.
                 return replayed ? { session, replayed } : { token: successorToken, session, replayed };
             }
+            if (result.code === -6) {
+                // Genuine reuse of an already-rotated-away token: the entire
+                // lineage's currently active generation was atomically revoked
+                // (this is a strong security signal, never an infra/storage
+                // failure - see SessionReplayError, not SessionStorageError, so it
+                // never trips the circuit breaker per guard()'s classification).
+                // The old jti-index entry (if any) no longer points anywhere
+                // useful; best-effort clean it up.
+                await this.repository.deleteJtiIndex(oldJti);
+                throw new SessionReplayError({
+                    reason: 'family_revoked',
+                    ...(result.familyId !== undefined ? { familyId: result.familyId } : {}),
+                    ...(result.headJtiRevoked !== undefined
+                        ? { headJtiRevoked: result.headJtiRevoked }
+                        : {}),
+                });
+            }
             throw rotationError(result.code, result.status);
         });
     }
@@ -477,6 +507,35 @@ export class SessionService {
         });
     }
     /* ------------------------------------------------------------------------ */
+    /* Reconciliation (ยง25 / ยง67 / ยง68)                                        */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Bounded administrative repair pass for one user: prunes stale
+     * user-index entries and, when the global jti index is enabled, rewrites
+     * any missing/stale jti-index entry for that user's live active sessions.
+     *
+     * This is NOT required for authentication correctness - every read path
+     * (validate/touch/rotate) already treats the session record as
+     * authoritative and self-heals stale index entries lazily. This exists
+     * purely to shrink the window during which JTI-only lookup (`find(jti)`
+     * without a known userId) can miss a live session after a partial write
+     * (ยง67), and to give operators a way to proactively repair known drift
+     * (e.g. after a Redis incident) instead of waiting for it to be hit
+     * randomly. Safe to call repeatedly; every effect is idempotent.
+     *
+     * Bounded by config.limits.maxSessionsPerUserHardCap, same as
+     * revokeAll/deleteByUser - never scans the cluster and is not called
+     * from a hot auth path.
+     */
+    reconcileUser(userId) {
+        return this.guard('reconcile_user', async () => {
+            validateUserId(userId);
+            const result = await this.repository.reconcileUser(userId, this.config.limits.maxSessionsPerUserHardCap, this.now());
+            this.metrics.reconcileUser(result.jtiIndexRepaired, result.staleIndexRemoved);
+            return { userId, ...result };
+        });
+    }
+    /* ------------------------------------------------------------------------ */
     /* Health                                                                   */
     /* ------------------------------------------------------------------------ */
     /** Dependency health (PING latency + recent error rate). */

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

@@ -42,6 +42,15 @@ export type SessionRecord = {
     metadata: Record<string, unknown> | null;
     /** JTI this session was rotated from (rotation chains, reuse detection). */
     rotatedFrom: string | null;
+    /**
+     * Stable identifier for this session's rotation lineage ("family"),
+     * unchanged across every generation produced by rotate(). Equal to the
+     * first generation's own jti (unguessable, 256-bit) - no separate
+     * randomness is generated for it. Used only to detect and respond to
+     * stolen-refresh-token reuse (see rotate.lua); it is never consulted by
+     * validate() and can never by itself grant authentication (I7).
+     */
+    familyId: string;
     /** JTI this session was rotated to (enables retry-safe rotation). */
     rotatedTo: string | null;
     /** When the session was consumed by a rotation (Unix seconds), or null. */
@@ -189,6 +198,20 @@ export type BindingMismatch = {
     userAgent: boolean;
     deviceId: boolean;
 };
+/**
+ * Result of a bounded {@link SessionService.reconcileUser} repair pass.
+ * `checked` is the number of live session records inspected (bounded by
+ * maxSessionsPerUserHardCap); `staleIndexRemoved` counts user-index entries
+ * removed because their session record no longer exists or was corrupt;
+ * `jtiIndexRepaired` counts global jti-index entries that were missing or
+ * stale for a live active session and were rewritten.
+ */
+export type ReconcileUserResult = {
+    userId: string;
+    checked: number;
+    staleIndexRemoved: number;
+    jtiIndexRepaired: number;
+};
 /** Schema version of the persisted envelope. */
 export type SerializedSchemaVersion = 1 | 2;
 /**
@@ -233,6 +256,11 @@ export type EncryptedSessionEnvelope = {
     rn: string | null;
     /** Plaintext rotated-to JTI mirror (script access). */
     rj: string | null;
+    /**
+     * Plaintext rotation-family-id mirror (script access - see rotate.lua).
+     * Immutable identity field, unchanged across rotations of one lineage.
+     */
+    fam: string;
 };
 export type SessionEnvelope = PlainSessionEnvelope | EncryptedSessionEnvelope;
 export type RevocationRecord = {

package/dist/types.js

@@ -7,7 +7,7 @@ export const DistributedLockOptionsSchema = z.object({
 export const CacheOptionsSchema = z.object({
     defaultTTL: z.number().int().min(0).default(3_600),
     compressionThreshold: z.number().int().min(1).default(1_024),
-    namespace: z.string().min(1).default("cache"),
+    namespace: z.string().default('')
 });
 // ============================================================================
 // Rate Limiting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ioredis-toolkit",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Production-grade, type-safe Redis infrastructure for standalone, Sentinel, and Cluster deployments",
   "type": "module",
   "main": "./dist/index.js",