ioredis-toolkit 0.0.1

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

@@ -0,0 +1,107 @@
+-- rotate-encrypted.lua (version 1) - encrypted (v2) envelopes
+-- Atomic, single-use session rotation for encrypted sessions.
+--
+-- The ciphertext cannot be decoded inside Lua, so the app decrypts the
+-- 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.
+--
+-- 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)
+--
+-- 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).
+local raw = redis.call('GET', KEYS[1])
+
+if not raw then
+  return 0
+end
+
+local env = cjson.decode(raw)
+
+if env.v ~= 2 then
+  return 6
+end
+
+local now = tonumber(redis.call('TIME')[1])
+
+-- 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
+-- rotation. The stored rotatedTo jti is returned (the retry's own freshly
+-- generated successor jti is discarded - it can never match).
+if env.st == 'consumed' then
+  if ARGV[5] ~= '' and env.rn == ARGV[5] then
+    return { 2, env.rj }
+  end
+  return -1
+end
+
+if env.st ~= 'active' then
+  return -1
+end
+
+if tonumber(env.exp) <= now then
+  redis.call('DEL', KEYS[1])
+  redis.call('ZREM', KEYS[3], ARGV[7])
+  return -2
+end
+
+if ARGV[4] ~= '' and tostring(env.ver) ~= ARGV[4] then
+  return -3
+end
+
+if redis.call('EXISTS', KEYS[2]) == 1 then
+  return -4
+end
+
+local consumedEnv = cjson.decode(ARGV[1])
+consumedEnv.st = 'consumed'
+consumedEnv.ver = env.ver
+consumedEnv.la = env.la
+consumedEnv.idle = env.idle
+consumedEnv.exp = env.exp
+consumedEnv.rn = cjson.null
+consumedEnv.rj = ARGV[3]
+
+if ARGV[5] ~= '' then
+  consumedEnv.rn = ARGV[5]
+end
+
+local nextEnv = cjson.decode(ARGV[2])
+nextEnv.st = 'active'
+nextEnv.ver = 1
+nextEnv.la = now
+if nextEnv.idle ~= cjson.null then
+  nextEnv.idle = math.min(tonumber(nextEnv.idle), tonumber(nextEnv.exp))
+end
+nextEnv.rn = cjson.null
+nextEnv.rj = cjson.null
+
+local nextTtl = math.max(1, tonumber(ARGV[8]))
+
+if ARGV[6] == '1' then
+  redis.call('SET', KEYS[1], cjson.encode(consumedEnv), 'EX', math.max(1, tonumber(ARGV[9])))
+else
+  redis.call('DEL', KEYS[1])
+end
+
+redis.call('SET', KEYS[2], cjson.encode(nextEnv), 'EX', nextTtl)
+redis.call('ZREM', KEYS[3], ARGV[7])
+redis.call('ZADD', KEYS[3], now, ARGV[3])
+
+return { 1, ARGV[3] }

package/dist/session/scripts/rotate.lua

@@ -0,0 +1,119 @@
+-- rotate.lua (version 1) - plain (v1) envelopes
+-- Atomic, single-use session rotation.
+--
+-- The old session is consumed (status=consumed, consumedAt, rotatedTo,
+-- rotationNonceHash) and the successor is created, all in one same-slot
+-- script. No preliminary GET can make this safe; the script is the only
+-- authority. Timestamps are stamped from Redis server time.
+--
+-- Retry-safe idempotency: when the caller retries a rotation that already
+-- succeeded (response lost), the consumed record retains rotationNonceHash
+-- and rotatedTo. If both match the retry, the script returns {2, jti} and
+-- the caller returns the existing successor instead of a replay error.
+--
+-- KEYS[1] = old session record key
+-- KEYS[2] = successor session record key
+-- KEYS[3] = user session index key
+--
+-- ARGV[1] = successor serialized envelope (app-built static fields)
+-- ARGV[2] = successor jti
+-- ARGV[3] = expected version of the old session ('' = no check)
+-- ARGV[4] = rotation nonce hash ('' = none)
+-- ARGV[5] = retain consumed tombstone (1/0)
+-- ARGV[6] = old jti
+--
+-- 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)
+local raw = redis.call('GET', KEYS[1])
+
+if not raw then
+  return 0
+end
+
+local env = cjson.decode(raw)
+
+if env.v ~= 1 then
+  return 5
+end
+
+local s = env.s
+local now = tonumber(redis.call('TIME')[1])
+
+-- 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
+-- rotation. The stored rotatedTo jti is returned (the retry's own freshly
+-- generated successor jti is discarded - it can never match).
+if s.status == 'consumed' then
+  if ARGV[4] ~= '' and s.rotationNonceHash == ARGV[4] then
+    return { 2, s.rotatedTo }
+  end
+  return -1
+end
+
+if s.status ~= 'active' then
+  return -1
+end
+
+if tonumber(s.absoluteExpiresAt) <= now then
+  redis.call('DEL', KEYS[1])
+  redis.call('ZREM', KEYS[3], ARGV[6])
+  return -2
+end
+
+if ARGV[3] ~= '' and tostring(s.version) ~= ARGV[3] then
+  return -3
+end
+
+-- Successor collision: cryptographically improbable, but never overwrite.
+if redis.call('EXISTS', KEYS[2]) == 1 then
+  return -4
+end
+
+-- Build the successor record; server time is authoritative for ordering.
+local nextEnv = cjson.decode(ARGV[1])
+local ns = nextEnv.s
+
+ns.createdAt = now
+ns.lastAccessedAt = now
+ns.rotatedFrom = s.jti
+ns.version = 1
+
+if ns.idleExpiresAt and ns.idleExpiresAt ~= cjson.null then
+  ns.idleExpiresAt = math.min(tonumber(ns.idleExpiresAt), tonumber(ns.absoluteExpiresAt))
+end
+
+local nextTtl = math.max(1, tonumber(ns.absoluteExpiresAt) - now)
+
+-- Consume the old session.
+s.status = 'consumed'
+s.consumedAt = now
+s.rotatedTo = ARGV[2]
+
+if ARGV[4] ~= '' then
+  s.rotationNonceHash = ARGV[4]
+else
+  s.rotationNonceHash = cjson.null
+end
+
+local oldTtl = math.max(1, tonumber(s.absoluteExpiresAt) - now)
+
+if ARGV[5] == '1' then
+  -- Short-lived consumed tombstone for replay detection (bounded TTL).
+  redis.call('SET', KEYS[1], cjson.encode(env), 'EX', oldTtl)
+else
+  redis.call('DEL', KEYS[1])
+end
+
+redis.call('SET', KEYS[2], cjson.encode(nextEnv), 'EX', nextTtl)
+redis.call('ZREM', KEYS[3], ARGV[6])
+redis.call('ZADD', KEYS[3], now, ARGV[2])
+
+return { 1, ARGV[2] }

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

@@ -0,0 +1,89 @@
+-- touch-encrypted.lua (version 1) - encrypted (v2) envelopes
+-- Throttled, monotonic activity refresh for encrypted sessions.
+--
+-- The ciphertext cannot be decoded inside Lua, so the app re-encrypts the
+-- record (with its own clock) and passes the new envelope as ARGV[4]. The
+-- script validates state via the plaintext header mirrors and enforces
+-- monotonicity: a stale request can never move lastAccessedAt backwards.
+--
+-- KEYS[1] = session record key
+--
+-- ARGV[1] = touchInterval (seconds)
+-- ARGV[2] = idleTimeout (seconds, '' when disabled)
+-- ARGV[3] = force (1 = ignore throttle)
+-- ARGV[4] = new serialized envelope (re-encrypted with the current key)
+-- ARGV[5] = new lastAccessedAt (app clock, seconds)
+-- ARGV[6] = new idleExpiresAt (app clock, seconds, '' when disabled)
+-- ARGV[7] = new TTL (absoluteExpiresAt - now, clamped >= 1)
+--
+-- Returns:
+--   1   touched (write performed)
+--   2   skipped: inside touchInterval
+--   3   skipped: request older than recorded activity
+--   0   not found
+--   -1  consumed or revoked
+--   -2  absolute expiry passed; record deleted
+--   -3  idle expired; NOT resurrected
+--   4   envelope is plain (caller must use the plain touch path)
+--   5   stale request: ARGV[5] older than recorded activity
+local raw = redis.call('GET', KEYS[1])
+
+if not raw then
+  return 0
+end
+
+local env = cjson.decode(raw)
+
+if env.v ~= 2 then
+  return 4
+end
+
+if env.st ~= 'active' then
+  return -1
+end
+
+local now = tonumber(redis.call('TIME')[1])
+
+if tonumber(env.exp) <= now then
+  redis.call('DEL', KEYS[1])
+  return -2
+end
+
+if env.idle ~= cjson.null and tonumber(env.idle) <= now then
+  return -3
+end
+
+local interval = tonumber(ARGV[1])
+
+if tonumber(ARGV[3]) ~= 1 and now - tonumber(env.la) < interval then
+  return 2
+end
+
+-- Monotonic guard: a stale app request must never regress activity.
+-- Equal-second requests are allowed (the app clock is second-granular and
+-- cannot advance within the same second); only strictly older writes are
+-- rejected.
+local newLa = tonumber(ARGV[5])
+
+if newLa < tonumber(env.la) then
+  return 5
+end
+
+local newEnv = cjson.decode(ARGV[4])
+
+-- Keep the plaintext header mirrors in sync with the checked values.
+newEnv.st = env.st
+newEnv.la = newLa
+if ARGV[6] ~= '' then
+  newEnv.idle = tonumber(ARGV[6])
+else
+  newEnv.idle = cjson.null
+end
+newEnv.ver = env.ver
+newEnv.exp = env.exp
+newEnv.rn = env.rn
+newEnv.rj = env.rj
+
+redis.call('SET', KEYS[1], cjson.encode(newEnv), 'EX', tonumber(ARGV[7]))
+
+return 1

package/dist/session/scripts/touch.lua

@@ -0,0 +1,72 @@
+-- touch.lua (version 1) - plain (v1) envelopes
+-- Throttled, monotonic activity refresh for plain sessions.
+--
+-- The script is authoritative for all state checks (exists, status,
+-- absolute expiry, idle expiry, throttle). Timestamps come from Redis
+-- server time, so distributed application clocks cannot race each other.
+--
+-- KEYS[1] = session record key
+--
+-- ARGV[1] = touchInterval (seconds)
+-- ARGV[2] = idleTimeout (seconds, '' when idle timeout disabled)
+-- ARGV[3] = force (1 = ignore throttle)
+--
+-- Returns:
+--   1   touched (write performed)
+--   2   skipped: inside touchInterval
+--   3   skipped: request older than recorded activity (not possible with
+--       server time; retained for parity with the encrypted path)
+--   0   not found
+--   -1  consumed or revoked
+--   -2  absolute expiry passed; record deleted
+--   -3  idle expired; NOT resurrected
+--   4   envelope is encrypted (caller must use the encrypted touch path)
+local raw = redis.call('GET', KEYS[1])
+
+if not raw then
+  return 0
+end
+
+local env = cjson.decode(raw)
+
+if env.v ~= 1 then
+  return 4
+end
+
+local s = env.s
+
+if s.status ~= 'active' then
+  return -1
+end
+
+local now = tonumber(redis.call('TIME')[1])
+
+if tonumber(s.absoluteExpiresAt) <= now then
+  redis.call('DEL', KEYS[1])
+  return -2
+end
+
+if s.idleExpiresAt and s.idleExpiresAt ~= cjson.null and tonumber(s.idleExpiresAt) <= now then
+  return -3
+end
+
+local interval = tonumber(ARGV[1])
+
+if tonumber(ARGV[3]) ~= 1 and now - tonumber(s.lastAccessedAt) < interval then
+  return 2
+end
+
+s.lastAccessedAt = now
+
+if ARGV[2] ~= '' then
+  local idle = now + tonumber(ARGV[2])
+  local abs = tonumber(s.absoluteExpiresAt)
+  -- Rolling extends the idle boundary but NEVER the absolute boundary.
+  s.idleExpiresAt = math.min(idle, abs)
+end
+
+local ttl = math.max(1, tonumber(s.absoluteExpiresAt) - now)
+
+redis.call('SET', KEYS[1], cjson.encode(env), 'EX', ttl)
+
+return 1

package/dist/session/scripts/validate.lua

@@ -0,0 +1,90 @@
+-- validate.lua (version 1)
+-- Single-round-trip validation read: fetches the session record, the
+-- user's security version (when the key exists) and lazily cleans up
+-- expired records and their index members, all in one same-slot script.
+--
+-- The script performs the cheap, non-cryptographic state checks; binding
+-- checks and (for encrypted sessions) decryption happen app-side on the
+-- returned payload. A missing security-version key means the check is
+-- skipped (the version is only enforced once setSecurityVersion has run).
+--
+-- KEYS[1] = session record key
+-- KEYS[2] = user security version key (same slot)
+-- KEYS[3] = user session index key (same slot)
+--
+-- ARGV[1] = jti (used for the lazy index cleanup of encrypted records,
+--            whose headers do not carry their own jti)
+--
+-- Returns:
+--   {1, raw, securityVersion?}  record exists and passed script checks;
+--                               raw is the stored envelope; securityVersion
+--                               is the current user version when set
+--   {0}                         not found
+--   {-1, status}                not active (consumed/revoked)
+--   {-2}                        expired (absolute); record + index entry
+--                               removed
+--   {-3}                        idle expired; record + index entry removed
+--   {-4}                        security version mismatch (plain records)
+local raw = redis.call('GET', KEYS[1])
+
+if not raw then
+  return { 0 }
+end
+
+local currentRaw = redis.call('GET', KEYS[2])
+local currentVersion = nil
+
+if currentRaw then
+  currentVersion = tonumber(currentRaw)
+end
+
+local env = cjson.decode(raw)
+local now = tonumber(redis.call('TIME')[1])
+
+if env.v == 1 then
+  local s = env.s
+
+  if s.status ~= 'active' then
+    return { -1, s.status }
+  end
+
+  if tonumber(s.absoluteExpiresAt) <= now then
+    redis.call('DEL', KEYS[1])
+    redis.call('ZREM', KEYS[3], s.jti)
+    return { -2 }
+  end
+
+  if s.idleExpiresAt and s.idleExpiresAt ~= cjson.null and tonumber(s.idleExpiresAt) <= now then
+    redis.call('DEL', KEYS[1])
+    redis.call('ZREM', KEYS[3], s.jti)
+    return { -3 }
+  end
+
+  if currentVersion and (s.securityVersion == nil or tonumber(s.securityVersion) ~= currentVersion) then
+    return { -4 }
+  end
+elseif env.v == 2 then
+  -- Encrypted envelope: only the plaintext header mirrors are readable in
+  -- Lua. They are the script-level authority for state decisions; the
+  -- ciphertext remains authoritative for the payload (assertHeaderMatches).
+  if env.st ~= 'active' then
+    return { -1, env.st }
+  end
+
+  if tonumber(env.exp) <= now then
+    redis.call('DEL', KEYS[1])
+    redis.call('ZREM', KEYS[3], ARGV[1])
+    return { -2 }
+  end
+
+  if env.idle ~= cjson.null and tonumber(env.idle) <= now then
+    redis.call('DEL', KEYS[1])
+    redis.call('ZREM', KEYS[3], ARGV[1])
+    return { -3 }
+  end
+
+  -- Security version is checked app-side for encrypted records (it lives
+  -- only inside the ciphertext).
+end
+
+return { 1, raw, currentVersion }

package/dist/session/session-circuit-breaker.d.ts

@@ -0,0 +1,42 @@
+import type { SessionCircuitBreakerConfig } from './session-config.js';
+export type CircuitBreakerState = 'closed' | 'open' | 'half_open';
+/**
+ * Fail-closed circuit breaker around session storage operations.
+ *
+ * `run()` executes a function while the circuit is closed or a half-open
+ * probe is allowed, and throws {@link CircuitBreakerOpenError} when open.
+ * Callers may instead use {@link tryAcquire} / {@link recordSuccess} /
+ * {@link recordFailure} explicitly.
+ */
+export declare class SessionCircuitBreaker {
+    private readonly config;
+    private readonly circuit;
+    private readonly now;
+    private readonly onTransition;
+    constructor(config: SessionCircuitBreakerConfig, options?: {
+        now?: () => number;
+        onTransition?: (state: CircuitBreakerState) => void;
+    });
+    get state(): CircuitBreakerState;
+    /**
+     * Runs an operation under circuit protection. Records success/failure
+     * based on the promise outcome.
+     *
+     * @throws {CircuitBreakerOpenError} when the circuit is open.
+     */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Attempts to acquire a call slot synchronously. Returns false (fail
+     * closed) when the circuit is open and not yet ready for probes.
+     */
+    tryAcquire(): boolean;
+    /** Records a successful operation (closes a half-open circuit). */
+    recordSuccess(): void;
+    /** Records a failed operation (may open the circuit). */
+    recordFailure(): void;
+    /** Evaluates whether the open timer has elapsed, rolling to half-open. */
+    private rollHalfOpen;
+    private transitionTo;
+    /** Resets the breaker to closed (admin/repair). */
+    reset(): void;
+}

package/dist/session/session-circuit-breaker.js

@@ -0,0 +1,129 @@
+import { CircuitBreakerOpenError } from './session-errors.js';
+/**
+ * Fail-closed circuit breaker around session storage operations.
+ *
+ * `run()` executes a function while the circuit is closed or a half-open
+ * probe is allowed, and throws {@link CircuitBreakerOpenError} when open.
+ * Callers may instead use {@link tryAcquire} / {@link recordSuccess} /
+ * {@link recordFailure} explicitly.
+ */
+export class SessionCircuitBreaker {
+    config;
+    circuit;
+    now;
+    onTransition;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.now = options.now ?? (() => Date.now());
+        this.onTransition = options.onTransition ?? null;
+        this.circuit = {
+            state: 'closed',
+            consecutiveFailures: 0,
+            openedAt: 0,
+            halfOpenInFlight: 0,
+            halfOpenSucceeded: 0,
+        };
+    }
+    get state() {
+        return this.circuit.state;
+    }
+    /**
+     * Runs an operation under circuit protection. Records success/failure
+     * based on the promise outcome.
+     *
+     * @throws {CircuitBreakerOpenError} when the circuit is open.
+     */
+    async run(fn) {
+        if (!this.tryAcquire()) {
+            throw new CircuitBreakerOpenError();
+        }
+        try {
+            const result = await fn();
+            this.recordSuccess();
+            return result;
+        }
+        catch (error) {
+            this.recordFailure();
+            throw error;
+        }
+    }
+    /**
+     * Attempts to acquire a call slot synchronously. Returns false (fail
+     * closed) when the circuit is open and not yet ready for probes.
+     */
+    tryAcquire() {
+        this.rollHalfOpen();
+        if (this.circuit.state === 'closed')
+            return true;
+        if (this.circuit.state === 'half_open') {
+            if (this.circuit.halfOpenInFlight >= this.config.halfOpenMaxRequests) {
+                return false;
+            }
+            this.circuit.halfOpenInFlight += 1;
+            return true;
+        }
+        return false;
+    }
+    /** Records a successful operation (closes a half-open circuit). */
+    recordSuccess() {
+        if (this.circuit.state === 'closed') {
+            this.circuit.consecutiveFailures = 0;
+            return;
+        }
+        if (this.circuit.state !== 'half_open')
+            return;
+        this.circuit.halfOpenInFlight = Math.max(0, this.circuit.halfOpenInFlight - 1);
+        this.circuit.halfOpenSucceeded += 1;
+        if (this.circuit.halfOpenInFlight === 0 && this.circuit.halfOpenSucceeded >= 1) {
+            this.transitionTo('closed');
+        }
+    }
+    /** Records a failed operation (may open the circuit). */
+    recordFailure() {
+        if (this.circuit.state === 'closed') {
+            this.circuit.consecutiveFailures += 1;
+            if (this.circuit.consecutiveFailures >= this.config.failureThreshold) {
+                this.transitionTo('open');
+            }
+            return;
+        }
+        if (this.circuit.state === 'half_open') {
+            this.circuit.halfOpenInFlight = Math.max(0, this.circuit.halfOpenInFlight - 1);
+            this.transitionTo('open');
+        }
+    }
+    /** Evaluates whether the open timer has elapsed, rolling to half-open. */
+    rollHalfOpen() {
+        if (this.circuit.state === 'open' &&
+            this.now() - this.circuit.openedAt >= this.config.resetTimeoutMs) {
+            this.circuit.state = 'half_open';
+            this.circuit.halfOpenInFlight = 0;
+            this.circuit.halfOpenSucceeded = 0;
+            this.onTransition?.('half_open');
+        }
+    }
+    transitionTo(state) {
+        if (this.circuit.state === state)
+            return;
+        this.circuit.state = state;
+        if (state === 'open') {
+            this.circuit.openedAt = this.now();
+            this.circuit.halfOpenInFlight = 0;
+            this.circuit.halfOpenSucceeded = 0;
+        }
+        if (state === 'half_open') {
+            this.circuit.halfOpenInFlight = 0;
+            this.circuit.halfOpenSucceeded = 0;
+        }
+        if (state === 'closed') {
+            this.circuit.consecutiveFailures = 0;
+            this.circuit.halfOpenInFlight = 0;
+            this.circuit.halfOpenSucceeded = 0;
+        }
+        this.onTransition?.(state);
+    }
+    /** Resets the breaker to closed (admin/repair). */
+    reset() {
+        this.transitionTo('closed');
+    }
+}