ioredis-toolkit 0.0.8 → 0.0.10

package/dist/session/scripts/rotate-encrypted.lua

@@ -5,26 +5,40 @@
 -- old record, builds the consumed + successor payloads (re-encrypted with
 -- the current key) and passes them as ARGV. The script is the only
 -- authority for the state transition, decided from the plaintext header
--- mirrors (st/ver/exp/rn/rj) and Redis server time; the header mirrors of
--- the written payloads are overwritten from the checked values so a stale
--- app payload can never misrepresent state.
+-- mirrors (st/ver/exp/rn/rj/fam) and Redis server time; the header mirrors
+-- of the written payloads are overwritten from the checked values so a
+-- stale app payload can never misrepresent state.
+--
+-- Token-family reuse detection: mirrors rotate.lua (see that file for the
+-- full rationale). The plaintext `fam` header mirror lets this script make
+-- the same family-head decision the plain path makes, even though it can
+-- never see or alter the ciphertext itself: the app is responsible for
+-- baking the correct familyId into both the ciphertext and the `fam`
+-- mirror before calling this script (see SessionRepository.rotate), and
+-- this script cross-checks/forces the mirror the same way it already
+-- forces st/ver/la/idle/exp/rn/rj - if the app ever got it wrong, the next
+-- read's assertHeaderMatches() catches the ciphertext/header disagreement
+-- and fails closed rather than silently establishing the wrong lineage.
 --
 -- KEYS[1] = old session record key
 -- KEYS[2] = successor session record key
 -- KEYS[3] = user session index key
 --
--- ARGV[1] = consumed serialized envelope (app-built, re-encrypted)
--- ARGV[2] = successor serialized envelope (app-built, re-encrypted)
--- ARGV[3] = successor jti
--- ARGV[4] = expected version of the old session ('' = no check)
--- ARGV[5] = rotation nonce hash ('' = none)
--- ARGV[6] = retain consumed tombstone (1/0)
--- ARGV[7] = old jti
--- ARGV[8] = successor TTL (clamped >= 1)
--- ARGV[9] = consumed tombstone TTL (clamped >= 1)
+-- ARGV[1]  = consumed serialized envelope (app-built, re-encrypted)
+-- ARGV[2]  = successor serialized envelope (app-built, re-encrypted)
+-- ARGV[3]  = successor jti
+-- ARGV[4]  = expected version of the old session ('' = no check)
+-- ARGV[5]  = rotation nonce hash ('' = none)
+-- ARGV[6]  = retain consumed tombstone (1/0)
+-- ARGV[7]  = old jti
+-- ARGV[8]  = successor TTL (clamped >= 1)
+-- ARGV[9]  = consumed tombstone TTL (clamped >= 1)
+-- ARGV[10] = session key prefix for this user (same hash tag => same slot)
+-- ARGV[11] = family-head key prefix for this user (same hash tag)
+-- ARGV[12] = revoke the family head on genuine replay (1/0)
 --
--- Returns: same codes as rotate.lua (1/2/0/-1/-2/-3/-4/5), plus 6 when the
--- envelope is plain (caller must use the plain path).
+-- Returns: same codes as rotate.lua (1/2/0/-1/-2/-3/-4/5/{-6,familyId,headJti}),
+-- plus 6 when the envelope is plain (caller must use the plain path).
 local raw = redis.call('GET', KEYS[1])
 
 if not raw then
@@ -40,6 +54,15 @@ end
 local t = redis.call('TIME')
 local now = tonumber(t[1])
 
+-- Immutable identity field: unchanged across every rotation of this
+-- lineage. Legacy pre-migration records lacking it adopt their own jti as
+-- the familyId from this point forward (self-healing) - see rotate.lua.
+local familyId = env.fam
+if familyId == nil or familyId == cjson.null then
+  familyId = ARGV[7]
+end
+local familyHeadKey = ARGV[11] .. familyId
+
 -- Retry-safe replay detection BEFORE rejecting consumed records.
 -- The rotation nonce uniquely identifies the rotation: when the consumed
 -- record carries the same nonce hash, this is a retry of an already-applied
@@ -49,6 +72,18 @@ if env.st == 'consumed' then
   if ARGV[5] ~= '' and env.rn == ARGV[5] then
     return { 2, env.rj }
   end
+
+  -- Genuine reuse of an already-rotated-away token.
+  if ARGV[12] == '1' then
+    local headJti = redis.call('GET', familyHeadKey)
+    if headJti then
+      redis.call('DEL', ARGV[10] .. headJti)
+      redis.call('ZREM', KEYS[3], headJti)
+    end
+    redis.call('DEL', familyHeadKey)
+    return { -6, familyId, headJti or '' }
+  end
+
   return -1
 end
 
@@ -78,6 +113,7 @@ consumedEnv.idle = env.idle
 consumedEnv.exp = env.exp
 consumedEnv.rn = cjson.null
 consumedEnv.rj = ARGV[3]
+consumedEnv.fam = familyId
 
 if ARGV[5] ~= '' then
   consumedEnv.rn = ARGV[5]
@@ -92,6 +128,7 @@ if nextEnv.idle ~= cjson.null then
 end
 nextEnv.rn = cjson.null
 nextEnv.rj = cjson.null
+nextEnv.fam = familyId
 
 local nextTtl = math.max(1, tonumber(ARGV[8]))
 
@@ -106,5 +143,7 @@ redis.call('ZREM', KEYS[3], ARGV[7])
 -- Microsecond-resolution ordering score - see create.lua for why
 -- second-granularity scores break oldest-first eviction ordering.
 redis.call('ZADD', KEYS[3], tonumber(t[1]) + (tonumber(t[2]) / 1000000), ARGV[3])
+-- Advance the family head to the new generation.
+redis.call('SET', familyHeadKey, ARGV[3], 'EX', nextTtl)
 
 return { 1, ARGV[3] }

package/dist/session/scripts/rotate.lua

@@ -11,6 +11,19 @@
 -- and rotatedTo. If both match the retry, the script returns {2, jti} and
 -- the caller returns the existing successor instead of a replay error.
 --
+-- Token-family reuse detection: every session carries a stable familyId
+-- (the first generation's own jti), unchanged across rotations. A
+-- {userId}-scoped "family-head" pointer key tracks the jti of the family's
+-- current active generation, updated atomically on every successful
+-- rotation. When a CONSUMED predecessor is replayed for real (not a
+-- same-nonce retry), that is a strong signal the old token was stolen: if
+-- ARGV[9] enables it, the script atomically revokes whatever the family
+-- head currently points to (the live session an attacker could otherwise
+-- keep using) and clears the head pointer, so the entire lineage dies
+-- rather than just rejecting the one replayed request. The head pointer is
+-- purely a defensive correlation key: per I7 it is never consulted by
+-- validate() and can never itself grant authentication.
+--
 -- KEYS[1] = old session record key
 -- KEYS[2] = successor session record key
 -- KEYS[3] = user session index key
@@ -21,16 +34,24 @@
 -- ARGV[4] = rotation nonce hash ('' = none)
 -- ARGV[5] = retain consumed tombstone (1/0)
 -- ARGV[6] = old jti
+-- ARGV[7] = session key prefix for this user (same hash tag => same slot)
+-- ARGV[8] = family-head key prefix for this user (same hash tag)
+-- ARGV[9] = revoke the family head on genuine replay (1/0)
 --
 -- Returns:
---   {1, successorJti}  success
---   {2, successorJti}  idempotent replay of a rotation with the same nonce
---   0                  old session not found
---   -1                 already consumed / revoked (replay)
---   -2                 old session expired (record removed)
---   -3                 version conflict
---   -4                 successor jti collision
---   5                  envelope is encrypted (use the encrypted path)
+--   {1, successorJti}       success
+--   {2, successorJti}       idempotent replay of a rotation with the same nonce
+--   0                       old session not found
+--   -1                      already consumed / revoked (replay; family not
+--                           touched - either ARGV[9] is off, or the status
+--                           was already 'revoked' rather than 'consumed')
+--   {-6, familyId, headJti} genuine replay of a consumed predecessor: the
+--                           family head (headJti, or "" if none was set)
+--                           was revoked and the family head pointer cleared
+--   -2                      old session expired (record removed)
+--   -3                      version conflict
+--   -4                      successor jti collision
+--   5                       envelope is encrypted (use the encrypted path)
 local raw = redis.call('GET', KEYS[1])
 
 if not raw then
@@ -47,6 +68,15 @@ local s = env.s
 local t = redis.call('TIME')
 local now = tonumber(t[1])
 
+-- Immutable identity field: unchanged across every rotation of this
+-- lineage. Legacy pre-migration records lacking it adopt their own jti as
+-- the familyId from this point forward (self-healing).
+local familyId = s.familyId
+if familyId == nil or familyId == cjson.null then
+  familyId = s.jti
+end
+local familyHeadKey = ARGV[8] .. familyId
+
 -- Retry-safe replay detection BEFORE rejecting consumed records.
 -- The rotation nonce uniquely identifies the rotation: when the consumed
 -- record carries the same nonce hash, this is a retry of an already-applied
@@ -56,6 +86,18 @@ if s.status == 'consumed' then
   if ARGV[4] ~= '' and s.rotationNonceHash == ARGV[4] then
     return { 2, s.rotatedTo }
   end
+
+  -- Genuine reuse of an already-rotated-away token.
+  if ARGV[9] == '1' then
+    local headJti = redis.call('GET', familyHeadKey)
+    if headJti then
+      redis.call('DEL', ARGV[7] .. headJti)
+      redis.call('ZREM', KEYS[3], headJti)
+    end
+    redis.call('DEL', familyHeadKey)
+    return { -6, familyId, headJti or '' }
+  end
+
   return -1
 end
 
@@ -85,6 +127,7 @@ local ns = nextEnv.s
 ns.createdAt = now
 ns.lastAccessedAt = now
 ns.rotatedFrom = s.jti
+ns.familyId = familyId
 ns.version = 1
 
 if ns.idleExpiresAt and ns.idleExpiresAt ~= cjson.null then
@@ -118,5 +161,7 @@ redis.call('ZREM', KEYS[3], ARGV[6])
 -- Microsecond-resolution ordering score - see create.lua for why
 -- second-granularity scores break oldest-first eviction ordering.
 redis.call('ZADD', KEYS[3], tonumber(t[1]) + (tonumber(t[2]) / 1000000), ARGV[2])
+-- Advance the family head to the new generation.
+redis.call('SET', familyHeadKey, ARGV[2], 'EX', nextTtl)
 
-return { 1, ARGV[2] }
+return { 1, ARGV[2] }

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

@@ -246,6 +246,25 @@ export interface SessionConfig {
      * bounded by the remaining absolute lifetime. Default: true.
      */
     retainConsumedTombstones: boolean;
+    /**
+     * On genuine reuse of an already-rotated-away (consumed) session token -
+     * not a same-nonce idempotent retry of an in-flight rotation - atomically
+     * revoke the entire rotation lineage's current active generation instead
+     * of only rejecting the replayed request. This is the strongest response
+     * to stolen refresh-token reuse (specification ยง5): if an attacker
+     * captured an old token and the legitimate client has since rotated past
+     * it, this kills the session the attacker could otherwise keep riding,
+     * rather than leaving it live while only the stale replay is rejected.
+     *
+     * Has no effect unless retainConsumedTombstones is also true: a replay
+     * can only be detected while a consumed tombstone still exists to be
+     * replayed against. Default: false (opt-in - a false positive here is a
+     * full lineage kill, so it should be turned on deliberately once the
+     * caller's retry semantics are understood; the resulting
+     * SessionReplayError with reason 'family_revoked' should be handled as
+     * a security event, e.g. forcing full re-authentication and logging).
+     */
+    revokeFamilyOnReplay: boolean;
 }
 export declare const SessionConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
@@ -312,6 +331,7 @@ export declare const SessionConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     enableCreateIdempotency: z.ZodDefault<z.ZodBoolean>;
     retainConsumedTombstones: z.ZodDefault<z.ZodBoolean>;
+    revokeFamilyOnReplay: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /** Recursively makes every config field optional (matches the schema's input shape). */
 export type DeepPartial<T> = {

package/dist/session/session-config.js

@@ -101,6 +101,7 @@ export const SessionConfigSchema = z
     limits: SessionLimitsConfigSchema.prefault({}),
     enableCreateIdempotency: z.boolean().default(false),
     retainConsumedTombstones: z.boolean().default(true),
+    revokeFamilyOnReplay: z.boolean().default(false),
 })
     .superRefine((data, ctx) => {
     if (data.idleTimeout !== null && data.idleTimeout > data.ttl) {
@@ -117,6 +118,14 @@ export const SessionConfigSchema = z
             path: ['touchInterval'],
         });
     }
+    if (data.revokeFamilyOnReplay && !data.retainConsumedTombstones) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'revokeFamilyOnReplay requires retainConsumedTombstones: replay can only be ' +
+                'detected while a consumed tombstone still exists to be replayed against.',
+            path: ['revokeFamilyOnReplay'],
+        });
+    }
 });
 /**
  * Parses and validates session configuration.

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

@@ -46,6 +46,19 @@ export declare class SessionKeyStrategy {
      * from jtis. The `{userId}` hash tag guarantees same-slot construction.
      */
     sessionKeyPrefix(userId: string): string;
+    /**
+     * Key prefix for a user's rotation-family-head pointers, used by
+     * rotate.lua to construct `{prefix}{familyId}` at runtime (the familyId
+     * is only known once the script reads the old session record, so it
+     * cannot be precomputed as a literal key - see rotate.lua). Same
+     * `{userId}` hash tag as every other per-user key, so this is always
+     * same-slot with the session it may need to revoke.
+     *
+     * The family-head value is a correlation pointer used only to detect and
+     * respond to stolen-refresh-token reuse; per I7 it is never consulted by
+     * validate() and can never by itself grant authentication.
+     */
+    familyHeadKeyPrefix(userId: string): string;
     /** Index key prefix for namespace-scoped administration. */
     namespacePrefix(): string;
 }

package/dist/session/session-keys.js

@@ -106,6 +106,21 @@ export class SessionKeyStrategy {
     sessionKeyPrefix(userId) {
         return this.ns(`session:{${encodeUserId(userId)}}:session:`);
     }
+    /**
+     * Key prefix for a user's rotation-family-head pointers, used by
+     * rotate.lua to construct `{prefix}{familyId}` at runtime (the familyId
+     * is only known once the script reads the old session record, so it
+     * cannot be precomputed as a literal key - see rotate.lua). Same
+     * `{userId}` hash tag as every other per-user key, so this is always
+     * same-slot with the session it may need to revoke.
+     *
+     * The family-head value is a correlation pointer used only to detect and
+     * respond to stolen-refresh-token reuse; per I7 it is never consulted by
+     * validate() and can never by itself grant authentication.
+     */
+    familyHeadKeyPrefix(userId) {
+        return this.ns(`family-head:{${encodeUserId(userId)}}:`);
+    }
     /** Index key prefix for namespace-scoped administration. */
     namespacePrefix() {
         return `${this.namespace}:`;

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

@@ -7,7 +7,7 @@ export interface SessionMetricsAdapter {
     /** 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';
+export type SessionOperation = '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.
  */
@@ -29,5 +29,13 @@ export declare class SessionMetrics {
     encryptionError(reason: string): void;
     /** Records a failed best-effort jti index write (derived-state degradation). */
     jtiIndexWriteFailure(): void;
+    /**
+     * 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: number, removed: number): void;
 }
 export declare const SESSION_OPERATIONS: readonly SessionOperation[];

package/dist/session/session-metrics.js

@@ -20,6 +20,7 @@ const OPERATIONS = [
     'list',
     'find_by_user',
     'set_security_version',
+    'reconcile_user',
     'health',
 ];
 /**
@@ -108,5 +109,27 @@ export class SessionMetrics {
             // 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

@@ -87,10 +87,13 @@ export declare class SessionRepository {
         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
@@ -112,6 +115,26 @@ export declare class SessionRepository {
         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.

package/dist/session/session-repository.js

@@ -233,16 +233,26 @@ export class SessionRepository {
         const expected = options.expectedVersion !== undefined ? String(options.expectedVersion) : '';
         const nonce = options.rotationNonceHash ?? '';
         const retain = options.retainTombstone ? '1' : '0';
+        const sessionPrefix = this.keys.sessionKeyPrefix(userId);
+        const familyHeadPrefix = this.keys.familyHeadKeyPrefix(userId);
+        const revokeFamily = options.revokeFamilyOnReplay ? '1' : '0';
         if (!this.encrypted) {
             const serialized = serializeSession(successor);
-            const result = await this.scripts.eval('rotate', 3, oldKey, newKey, indexKey, serialized, successor.jti, expected, nonce, retain, oldJti);
+            const result = await this.scripts.eval('rotate', 3, oldKey, newKey, indexKey, serialized, successor.jti, expected, nonce, retain, oldJti, sessionPrefix, familyHeadPrefix, revokeFamily);
             const outcome = parseRotateResult(result, successor.jti);
             if (outcome.code === 0) {
                 await this.cleanupJtiIndex(oldJti);
             }
             return outcome;
         }
-        // Encrypted path.
+        // Encrypted path. The GET below is informational only (ยง18/ยง78): it
+        // lets us build well-formed re-encrypted payloads for the optimistic
+        // success path (ciphertext can't be built inside Lua), but every state
+        // decision - already consumed/revoked, expired, version conflict, and
+        // family-head reuse - is made authoritatively by the script from its
+        // own atomic read, never from this snapshot. A concurrent writer may
+        // have already invalidated it by the time the script actually runs;
+        // the script is the only party allowed to decide or write.
         const raw = await this.client.get(oldKey);
         if (raw === null) {
             await this.cleanupJtiIndex(oldJti);
@@ -258,23 +268,7 @@ export class SessionRepository {
             }
             throw error;
         }
-        if (current.status !== 'active') {
-            // Retry-safe replay: the stored rotatedTo jti is authoritative; the
-            // retry's freshly generated successor jti must never be compared
-            // against it (it is discarded, exactly like the plain path).
-            if (nonce !== '' && current.rotationNonceHash === nonce && current.rotatedTo !== null) {
-                return { code: 2, successorJti: current.rotatedTo };
-            }
-            return { code: -1, status: current.status };
-        }
         const now = Math.floor(Date.now() / 1000);
-        if (current.absoluteExpiresAt <= now) {
-            await this.client.del(oldKey);
-            return { code: -2 };
-        }
-        if (options.expectedVersion !== undefined && current.version !== options.expectedVersion) {
-            return { code: -3 };
-        }
         const consumed = {
             ...current,
             status: 'consumed',
@@ -282,12 +276,25 @@ export class SessionRepository {
             rotatedTo: successor.jti,
             rotationNonceHash: nonce !== '' ? nonce : null,
         };
+        // familyId is an identity field: self-heal from the (informational)
+        // old record, exactly like rotate.lua does authoritatively for the
+        // plain path. The Lua script can never rewrite ciphertext, so this is
+        // the only place the encrypted successor's real familyId can be set;
+        // the script still cross-checks the plaintext `fam` mirror it derives
+        // against this on every future read (assertHeaderMatches), so a bug
+        // here fails closed instead of silently mislabeling the lineage.
+        const familyId = current.familyId || current.jti;
+        const successorWithFamily = { ...successor, familyId };
         const consumedSerialized = serializeEncryptedSession(consumed, this.keyProvider);
-        const successorSerialized = serializeEncryptedSession(successor, this.keyProvider);
-        const successorTtl = Math.max(1, successor.absoluteExpiresAt - now);
+        const successorSerialized = serializeEncryptedSession(successorWithFamily, this.keyProvider);
+        const successorTtl = Math.max(1, successorWithFamily.absoluteExpiresAt - now);
         const consumedTtl = Math.max(1, consumed.absoluteExpiresAt - now);
-        const result = await this.scripts.eval('rotateEncrypted', 3, oldKey, newKey, indexKey, consumedSerialized, successorSerialized, successor.jti, expected, nonce, retain, oldJti, String(successorTtl), String(consumedTtl));
-        return parseRotateResult(result, successor.jti);
+        const result = await this.scripts.eval('rotateEncrypted', 3, oldKey, newKey, indexKey, consumedSerialized, successorSerialized, successorWithFamily.jti, expected, nonce, retain, oldJti, String(successorTtl), String(consumedTtl), sessionPrefix, familyHeadPrefix, revokeFamily);
+        const outcome = parseRotateResult(result, successorWithFamily.jti);
+        if (outcome.code === 0) {
+            await this.cleanupJtiIndex(oldJti);
+        }
+        return outcome;
     }
     /* ------------------------------------------------------------------------ */
     /* Update                                                                   */
@@ -450,6 +457,65 @@ export class SessionRepository {
         }
         return sessions;
     }
+    /**
+     * 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.
+     */
+    async reconcileUser(userId, limit, now) {
+        const jtis = await this.listJtis(userId, limit);
+        if (jtis.length === 0)
+            return { checked: 0, staleIndexRemoved: 0, jtiIndexRepaired: 0 };
+        const sessionKeys = jtis.map((jti) => this.keys.sessionKey(userId, jti));
+        const values = await this.client.mget(...sessionKeys);
+        const sessions = [];
+        const stale = [];
+        for (let i = 0; i < jtis.length; i++) {
+            const raw = values[i];
+            if (raw === null || raw === undefined) {
+                stale.push(jtis[i]);
+                continue;
+            }
+            try {
+                sessions.push(deserializeSession(raw, this.keyProvider ?? undefined));
+            }
+            catch (error) {
+                if (error instanceof SessionSerializationError) {
+                    stale.push(jtis[i]);
+                    continue;
+                }
+                throw error;
+            }
+        }
+        if (stale.length > 0) {
+            await this.cleanupIndexEntries(userId, stale);
+        }
+        let jtiIndexRepaired = 0;
+        if (this.jtiIndexEnabled) {
+            for (const session of sessions) {
+                if (session.status !== 'active')
+                    continue;
+                const ttl = Math.max(1, session.absoluteExpiresAt - now);
+                const current = await this.readJtiIndex(session.jti);
+                if (current !== userId) {
+                    const ok = await this.writeJtiIndex(session.jti, userId, ttl);
+                    if (ok)
+                        jtiIndexRepaired += 1;
+                }
+            }
+        }
+        return { checked: sessions.length, staleIndexRemoved: stale.length, jtiIndexRepaired };
+    }
     /**
      * Deletes all of a user's sessions in bounded same-slot batches.
      * Returns the jtis whose records were deleted.
@@ -660,6 +726,20 @@ function parseRotateResult(result, successorJti) {
             const jti = result[1] !== undefined ? String(result[1]) : successorJti;
             return { code, successorJti: jti };
         }
+        if (code === -6) {
+            // { -6, familyId, headJti } - genuine consumed-token replay: the
+            // family head (if any) was revoked and the pointer cleared. headJti
+            // is '' when no head was set (nothing to revoke, but replay itself
+            // is still reported).
+            const familyId = result[1] !== undefined ? String(result[1]) : undefined;
+            const headJtiRaw = result[2] !== undefined ? String(result[2]) : '';
+            const out = { code };
+            if (familyId !== undefined)
+                out.familyId = familyId;
+            if (headJtiRaw !== '')
+                out.headJtiRevoked = headJtiRaw;
+            return out;
+        }
         const status = result[1] !== undefined ? String(result[1]) : undefined;
         return status !== undefined ? { code, status } : { code };
     }

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

@@ -31,7 +31,7 @@ export declare function deserializeSession(raw: string, keyProvider?: SessionKey
  * 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'>;
+export declare function encryptedHeaderOf(record: SessionRecord): Pick<EncryptedSessionEnvelope, 'st' | 'ver' | 'la' | 'idle' | 'exp' | 'rn' | 'rj' | 'fam'>;
 /**
  * Verifies that a decrypted v2 record agrees with the envelope's plaintext
  * header mirrors. The ciphertext is authoritative; a disagreement means the

package/dist/session/session-serializer.js

@@ -99,6 +99,20 @@ export function validateSessionRecord(value) {
     if (!isNullish(r.rotatedFrom) && !isString(r.rotatedFrom)) {
         throw new SessionSerializationError({ reason: 'invalid_rotated_from' });
     }
+    // familyId is an identity field, immutable across a lineage's rotations.
+    // Legacy records written before this field existed lack it: they adopt
+    // their own jti as the familyId (self-healing - see rotate.lua, which
+    // does the same fallback for records it reads directly).
+    let familyId;
+    if (isNullish(r.familyId)) {
+        familyId = jti;
+    }
+    else if (isString(r.familyId) && r.familyId.length >= 20 && r.familyId.length <= 100 && BASE64URL.test(r.familyId)) {
+        familyId = r.familyId;
+    }
+    else {
+        throw new SessionSerializationError({ reason: 'invalid_family_id' });
+    }
     if (!isNullish(r.rotatedTo) && !isString(r.rotatedTo)) {
         throw new SessionSerializationError({ reason: 'invalid_rotated_to' });
     }
@@ -123,6 +137,7 @@ export function validateSessionRecord(value) {
         userAgent: r.userAgent ?? null,
         metadata: metadata ?? null,
         rotatedFrom: r.rotatedFrom ?? null,
+        familyId,
         rotatedTo: r.rotatedTo ?? null,
         consumedAt: r.consumedAt ?? null,
         rotationNonceHash: r.rotationNonceHash ?? null,
@@ -151,6 +166,7 @@ export function serializeEncryptedSession(record, provider) {
         exp: record.absoluteExpiresAt,
         rn: record.rotationNonceHash,
         rj: record.rotatedTo,
+        fam: record.familyId,
     };
     return JSON.stringify(envelope);
 }
@@ -216,6 +232,7 @@ export function encryptedHeaderOf(record) {
         exp: record.absoluteExpiresAt,
         rn: record.rotationNonceHash,
         rj: record.rotatedTo,
+        fam: record.familyId,
     };
 }
 /**
@@ -242,6 +259,8 @@ export function assertHeaderMatches(envelope, record) {
         mismatches.push('rn');
     if (envelope.rj !== header.rj)
         mismatches.push('rj');
+    if (envelope.fam !== header.fam)
+        mismatches.push('fam');
     if (mismatches.length > 0) {
         throw new SessionSerializationError({ reason: 'header_mismatch', fields: mismatches });
     }