ioredis-toolkit 0.0.1

package/dist/session/revocation-store.js

@@ -0,0 +1,310 @@
+import { RevocationError, RevocationBatchError, redactIdentifier } from './session-errors.js';
+/**
+ * Redis-backed revocation store. Each revoked jti is stored as
+ * `{prefix}{jti} -> reason`, with the Redis key TTL itself set to the
+ * token's remaining lifetime — expired entries are reclaimed automatically
+ * by Redis, no sweep job required.
+ *
+ * Every operation here is a single-key command, so this store works
+ * identically on standalone, Sentinel, and Cluster with no hash tags
+ * required (unlike the session store, there's no multi-key atomicity
+ * requirement to satisfy).
+ *
+ * Batched operations (`revokeMany`, `isRevokedMany`) group their commands
+ * by hash slot and issue one pipeline per slot, so they never trigger
+ * `CROSSSLOT` errors on Redis Cluster. Pipeline failures are surfaced via
+ * {@link RevocationBatchError} instead of being silently swallowed —
+ * a missed revocation is a security bug.
+ *
+ * Validation fails fast and typed: invalid records throw
+ * {@link RevocationError} before any network call, and reads fail closed
+ * (an infra error is never treated as "not revoked").
+ *
+ * @example
+ * ```ts
+ * const revocations = new RedisRevocationStore({ client });
+ *
+ * await revocations.revoke({
+ *   jti: 'a1b2c3d4',
+ *   reason: 'password-change',
+ *   expiresAt: Math.floor(Date.now() / 1000) + 3600,
+ * });
+ *
+ * if (await revocations.isRevoked('a1b2c3d4')) {
+ *   // token was rotated or revoked - reject it
+ * }
+ * ```
+ */
+export class RedisRevocationStore {
+    client;
+    keyPrefix;
+    /**
+     * Creates a Redis-backed revocation store.
+     *
+     * @param options - Client connection and key-prefix configuration.
+     *
+     * @example
+     * ```ts
+     * const store = new RedisRevocationStore({
+     *   client,
+     *   keyPrefix: 'myapp:revoked:',
+     * });
+     * ```
+     */
+    constructor(options) {
+        this.client = options.client;
+        this.keyPrefix = options.keyPrefix ?? 'authcore:revoked:';
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Revoke                                                                   */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Marks a jti as revoked for the remainder of its lifetime.
+     *
+     * Stores `{prefix}{jti} -> reason` with a Redis TTL equal to the
+     * record's remaining lifetime (`expiresAt - now`), so the entry is
+     * garbage-collected automatically once the original token would have
+     * expired anyway. Overwriting an existing entry extends/refreshes its
+     * TTL to the new expiry.
+     *
+     * @param record - The revocation entry (`jti`, `expiresAt`, optional
+     *   `reason`). `expiresAt` must be a finite Unix-seconds timestamp in
+     *   the future.
+     * @throws {RevocationError} when `record.expiresAt` is missing, not a
+     *   finite number, or not in the future (fails fast instead of sending
+     *   an invalid `EX` to Redis).
+     *
+     * @example
+     * ```ts
+     * await revocations.revoke({
+     *   jti: 'a1b2c3d4',
+     *   reason: 'logout',
+     *   expiresAt: Math.floor(Date.now() / 1000) + 86400,
+     * });
+     * ```
+     */
+    async revoke(record) {
+        const ttl = computeTtl(record);
+        try {
+            await this.client.set(this.key(record.jti), record.reason ?? '1', ttl);
+        }
+        catch (error) {
+            throw wrapStorageError(error, { jti: record.jti });
+        }
+    }
+    /**
+     * Revokes many jtis in one batched call.
+     *
+     * All records are validated up front — an invalid `expiresAt` fails
+     * before any network call is issued, rather than partway through a
+     * batch. Commands are grouped by hash slot (one pipeline per slot) so
+     * the batch stays Cluster-safe, and every pipeline result is inspected:
+     * any failed command throws {@link RevocationBatchError} listing the
+     * affected jtis, because a silently-missed revocation is a security bug.
+     *
+     * @param records - The revocation entries to create/refresh.
+     * @throws {RevocationError} when any record is invalid (validation is
+     *   all-or-nothing, before any network call).
+     * @throws {RevocationBatchError} when one or more pipeline commands
+     *   fail; carries the exact jtis that were not revoked.
+     *
+     * @example
+     * ```ts
+     * await revocations.revokeMany([
+     *   { jti: 'a1', reason: 'logout-all', expiresAt: expiry },
+     *   { jti: 'b2', reason: 'logout-all', expiresAt: expiry },
+     * ]);
+     * ```
+     */
+    async revokeMany(records) {
+        if (records.length === 0)
+            return;
+        // Validate every record up front - fail before issuing any network
+        // calls rather than partway through a batch.
+        const ttls = records.map((record) => computeTtl(record));
+        // Group by hash slot: the jti keys are not hash-tagged, so they may
+        // scatter across Cluster slots. One pipeline per slot avoids
+        // CROSSSLOT errors.
+        const groups = new Map();
+        for (let i = 0; i < records.length; i++) {
+            const record = records[i];
+            const key = this.key(record.jti);
+            const slot = this.client.calculateSlot(key);
+            const entry = { jti: record.jti, value: record.reason ?? '1', ttl: ttls[i] };
+            const group = groups.get(slot);
+            if (group) {
+                group.push(entry);
+            }
+            else {
+                groups.set(slot, [entry]);
+            }
+        }
+        const failures = [];
+        for (const entries of groups.values()) {
+            const pipeline = this.client.pipeline();
+            for (const entry of entries) {
+                pipeline.set(this.key(entry.jti), entry.value, 'EX', entry.ttl);
+            }
+            const results = await pipeline.exec();
+            // pipeline.exec() resolves to [error, result][] - a failed command
+            // does NOT reject the pipeline promise. Check every result.
+            for (let i = 0; i < entries.length; i++) {
+                const result = results?.[i];
+                const error = Array.isArray(result) ? result[0] : undefined;
+                if (error) {
+                    failures.push({ jti: entries[i].jti, error });
+                }
+            }
+        }
+        if (failures.length > 0) {
+            throw new RevocationBatchError(failures);
+        }
+    }
+    /* ------------------------------------------------------------------------ */
+    /* Check                                                                    */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Checks whether a jti is currently revoked.
+     *
+     * Fail-closed: infrastructure errors are wrapped in a typed error and
+     * must NOT be treated as "not revoked".
+     *
+     * @param jti - The token/session id to check.
+     * @returns `true` when the jti has a live revocation entry.
+     * @throws {RevocationError} when the check itself fails (caller must
+     *   treat the outcome as unknown).
+     *
+     * @example
+     * ```ts
+     * if (await revocations.isRevoked(token.jti)) {
+     *   return 401; // token was rotated away or explicitly revoked
+     * }
+     * ```
+     */
+    async isRevoked(jti) {
+        try {
+            const exists = await this.client.exists(this.key(jti));
+            return exists === 1;
+        }
+        catch (error) {
+            throw wrapStorageError(error, { jti });
+        }
+    }
+    /**
+     * Batched revocation check - one network round trip instead of N.
+     *
+     * Useful for validating a whole family of rotated tokens, or a batch
+     * of refresh attempts, at once. Commands are grouped by hash slot
+     * (one pipeline per slot) to stay Cluster-safe, and the check fails
+     * closed: if any command errors, {@link RevocationBatchError} is thrown
+     * rather than silently treating the jti as "not revoked".
+     *
+     * @param jtis - The token/session ids to check.
+     * @returns A `Set` containing exactly the revoked jtis.
+     * @throws {RevocationBatchError} when a pipeline command fails -
+     *   the caller must treat the outcome as unknown, not as "valid".
+     *
+     * @example
+     * ```ts
+     * const revoked = await revocations.isRevokedMany(['a1', 'b2', 'c3']);
+     * if (revoked.has('b2')) {
+     *   // b2 must not be accepted
+     * }
+     * ```
+     */
+    async isRevokedMany(jtis) {
+        if (jtis.length === 0)
+            return new Set();
+        const groups = new Map();
+        for (const jti of jtis) {
+            const key = this.key(jti);
+            const slot = this.client.calculateSlot(key);
+            const group = groups.get(slot);
+            if (group) {
+                group.push(jti);
+            }
+            else {
+                groups.set(slot, [jti]);
+            }
+        }
+        const revoked = new Set();
+        for (const groupJtis of groups.values()) {
+            const pipeline = this.client.pipeline();
+            for (const jti of groupJtis) {
+                pipeline.exists(this.key(jti));
+            }
+            const results = await pipeline.exec();
+            for (let i = 0; i < groupJtis.length; i++) {
+                const result = results?.[i];
+                const error = Array.isArray(result) ? result[0] : undefined;
+                const value = Array.isArray(result) ? result[1] : undefined;
+                if (error) {
+                    // Fail closed: if we can't confirm a jti's status, don't silently
+                    // treat it as "not revoked".
+                    throw new RevocationBatchError([{ jti: groupJtis[i], error }]);
+                }
+                if (value === 1) {
+                    revoked.add(groupJtis[i]);
+                }
+            }
+        }
+        return revoked;
+    }
+    key(jti) {
+        return `${this.keyPrefix}${jti}`;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Helpers                                                                    */
+/* -------------------------------------------------------------------------- */
+function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+/**
+ * Validates and computes the Redis TTL for a revocation record.
+ *
+ * Throws a typed {@link RevocationError} early with a redacted message
+ * instead of letting a malformed `expiresAt` (undefined/NaN/past) turn
+ * into `Math.max(1, NaN) === NaN`, which would otherwise reach Redis as
+ * an invalid `EX` argument and fail with an opaque "value is not an
+ * integer" error deep inside the client.
+ *
+ * @param record - The revocation record to validate.
+ * @param now - Reference timestamp (Unix seconds); overridable for tests.
+ * @returns The TTL in seconds, at least 1.
+ * @throws {RevocationError} on invalid records.
+ */
+function computeTtl(record, now = nowSeconds()) {
+    const safe = redactIdentifier(record.jti);
+    if (!record.jti || typeof record.jti !== 'string') {
+        throw new RevocationError({ reason: 'missing_jti' });
+    }
+    if (!Number.isFinite(record.expiresAt)) {
+        throw new RevocationError({
+            reason: 'invalid_expires_at',
+            jti: safe,
+            detail: 'expiresAt must be a finite number',
+        });
+    }
+    if (record.expiresAt <= now) {
+        throw new RevocationError({
+            reason: 'expires_at_in_past',
+            jti: safe,
+            detail: 'expiresAt must be in the future',
+        });
+    }
+    return Math.max(1, record.expiresAt - now);
+}
+/**
+ * Wraps an underlying storage failure in a typed, redacted error so the
+ * caller can fail closed without losing the root cause.
+ */
+function wrapStorageError(error, context) {
+    if (error instanceof RevocationError)
+        return error;
+    return new RevocationError({
+        reason: 'storage_failure',
+        jti: redactIdentifier(context.jti),
+        cause: error instanceof Error ? error.message : String(error),
+    });
+}

package/dist/session/scripts/cleanup-index.lua

@@ -0,0 +1,21 @@
+-- cleanup-index.lua (version 1)
+-- Lazily removes stale members (whose session records no longer exist,
+-- e.g. expired and naturally reclaimed by Redis TTL) from the user index.
+-- Bounded: the caller chunks the user's jtis into batches.
+--
+-- KEYS[1]   = user session index key
+-- KEYS[2..] = session record keys (same slot as KEYS[1])
+--
+-- ARGV[1..] = matching jtis (index i pairs with KEYS[i + 1])
+--
+-- Returns: the jtis removed from the index.
+local removed = {}
+
+for i = 2, #KEYS do
+  if redis.call('EXISTS', KEYS[i]) == 0 then
+    redis.call('ZREM', KEYS[1], ARGV[i - 1])
+    table.insert(removed, ARGV[i - 1])
+  end
+end
+
+return removed

package/dist/session/scripts/conditional-update-encrypted.lua

@@ -0,0 +1,60 @@
+-- conditional-update-encrypted.lua (version 1) - encrypted (v2) envelopes
+-- Optimistic-concurrency patch update for encrypted sessions.
+--
+-- The app decrypts the record, applies the whitelisted patch, re-encrypts
+-- and passes the new envelope. The script CAS's the plaintext version
+-- mirror and enforces status/expiry; the absolute expiry mirror is
+-- preserved from the stored record (identity/security fields can never be
+-- changed through update).
+--
+-- KEYS[1] = session record key
+--
+-- ARGV[1] = expected version ('' = no check)
+-- ARGV[2] = new serialized envelope (app-built, re-encrypted)
+-- ARGV[3] = new version (expected + 1)
+-- ARGV[4] = new TTL (clamped >= 1)
+--
+-- Returns:
+--   {1, newVersion}  applied
+--   0                not found
+--   -1               consumed or revoked
+--   -2               expired (record removed)
+--   -3               version conflict
+--   6                envelope is plain (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
+
+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 ARGV[1] ~= '' and tostring(env.ver) ~= ARGV[1] then
+  return -3
+end
+
+local newEnv = cjson.decode(ARGV[2])
+newEnv.st = 'active'
+newEnv.ver = tonumber(ARGV[3])
+newEnv.exp = env.exp
+newEnv.rn = env.rn
+newEnv.rj = env.rj
+
+redis.call('SET', KEYS[1], cjson.encode(newEnv), 'EX', tonumber(ARGV[4]))
+
+return { 1, ARGV[3] }

package/dist/session/scripts/conditional-update.lua

@@ -0,0 +1,63 @@
+-- conditional-update.lua (version 1) - plain (v1) envelopes
+-- Optimistic-concurrency patch update. The script is the authority for:
+--   - existence / status / expiry checks
+--   - the version compare-and-swap
+--   - the mutable-field whitelist (identity and security-critical fields
+--     are never touched, regardless of what the caller sends)
+--
+-- KEYS[1] = session record key
+--
+-- ARGV[1] = expected version ('' = no check)
+-- ARGV[2] = patch JSON: only { deviceId?, ipAddress?, userAgent?, metadata? }
+--           may be present; other keys are ignored (never applied)
+--
+-- Returns:
+--   {1, newVersion}  applied
+--   0                not found
+--   -1               consumed or revoked
+--   -2               expired (record removed)
+--   -3               version conflict
+--   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
+
+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 ARGV[1] ~= '' and tostring(s.version) ~= ARGV[1] then
+  return -3
+end
+
+local patch = cjson.decode(ARGV[2])
+
+if patch.deviceId ~= nil then s.deviceId = patch.deviceId end
+if patch.ipAddress ~= nil then s.ipAddress = patch.ipAddress end
+if patch.userAgent ~= nil then s.userAgent = patch.userAgent end
+if patch.metadata ~= nil then s.metadata = patch.metadata end
+
+s.version = tonumber(s.version) + 1
+
+local ttl = math.max(1, tonumber(s.absoluteExpiresAt) - now)
+
+redis.call('SET', KEYS[1], cjson.encode(env), 'EX', ttl)
+
+return { 1, tostring(s.version) }

package/dist/session/scripts/create.lua

@@ -0,0 +1,68 @@
+-- create.lua (version 1)
+-- Atomically creates a session record, registers it in the user index
+-- (ZSET, score = createdAt), optionally claims an idempotency key, and
+-- enforces maxSessionsPerUser with bounded oldest-first eviction.
+--
+-- KEYS[1] = session record key
+-- KEYS[2] = user session index key (ZSET)
+-- KEYS[3] = idempotency claim key (only passed when idempotency is enabled)
+--
+-- ARGV[1] = serialized session envelope (plain v1 or encrypted v2)
+-- ARGV[2] = jti
+-- ARGV[3] = createdAt (Unix seconds)
+-- ARGV[4] = session TTL (absoluteExpiresAt - now, clamped >= 1)
+-- ARGV[5] = maxSessionsPerUser (0 disables)
+-- ARGV[6] = session key prefix for this user (same hash tag => same slot)
+-- ARGV[7] = max evictions per call (bounded Lua work)
+-- ARGV[8] = idempotency claim TTL ('' when idempotency is disabled)
+--
+-- Returns:
+--   {1, {evictedJtis...}}  success (evicted list may be empty)
+--   {3, jti}               idempotent replay: a previous attempt created
+--                          the session; jti identifies it
+--   -5                     jti collision: a session with this id exists
+--
+-- All keys share the {userId} hash tag, so this script is atomic on a
+-- single Cluster slot. No cross-slot keys are touched.
+local key = KEYS[1]
+local index = KEYS[2]
+
+-- Idempotent replay wins over collision detection: a retry with the same
+-- idempotencyKey must return the original session, even though the session
+-- record already exists.
+if ARGV[8] ~= '' then
+  local claimKey = KEYS[3]
+  local claimJti = redis.call('GET', claimKey)
+  if claimJti then
+    return { 3, claimJti }
+  end
+  redis.call('SET', claimKey, ARGV[2], 'EX', tonumber(ARGV[8]))
+end
+
+if redis.call('EXISTS', key) == 1 then
+  return -5
+end
+
+redis.call('SET', key, ARGV[1], 'EX', tonumber(ARGV[4]))
+redis.call('ZADD', index, tonumber(ARGV[3]), ARGV[2])
+
+local evicted = {}
+local limit = tonumber(ARGV[5])
+
+if limit and limit > 0 then
+  local card = redis.call('ZCARD', index)
+  if card > limit then
+    local excess = card - limit
+    local n = math.min(excess, tonumber(ARGV[7]))
+    local members = redis.call('ZRANGE', index, 0, n - 1)
+    local prefix = ARGV[6]
+
+    for _, member in ipairs(members) do
+      redis.call('DEL', prefix .. member)
+      redis.call('ZREM', index, member)
+      table.insert(evicted, member)
+    end
+  end
+end
+
+return { 1, evicted }

package/dist/session/scripts/delete-by-user.lua

@@ -0,0 +1,29 @@
+-- delete-by-user.lua (version 2)
+-- Deletes a bounded batch of a user's sessions and removes them from the
+-- user index, in one same-slot script. The caller chunks the user's jtis
+-- into batches (limits.maxBatchSize), so a user with an arbitrarily large
+-- session count never produces one giant script.
+--
+-- KEYS[1]   = user session index key
+-- KEYS[2..] = session record keys (same slot as KEYS[1])
+--
+-- ARGV[1..] = matching jtis (index i pairs with KEYS[i + 1])
+--
+-- Returns: the jtis whose records were actually deleted. The index key is
+-- deleted at the end (the whole-user operation is complete when the caller
+-- has processed every batch).
+local deleted = {}
+
+for i = 2, #KEYS do
+  local jti = ARGV[i - 1]
+
+  if redis.call('DEL', KEYS[i]) == 1 then
+    table.insert(deleted, jti)
+  end
+
+  redis.call('ZREM', KEYS[1], jti)
+end
+
+redis.call('DEL', KEYS[1])
+
+return deleted

package/dist/session/scripts/delete.lua

@@ -0,0 +1,15 @@
+-- delete.lua (version 1)
+-- Physically deletes a session record and removes it from the user index.
+-- Idempotent: deleting a missing session returns 0 and is not an error.
+--
+-- KEYS[1] = session record key
+-- KEYS[2] = user session index key
+--
+-- ARGV[1] = jti
+--
+-- Returns: 1 if the record existed, 0 otherwise.
+local existed = redis.call('DEL', KEYS[1])
+
+redis.call('ZREM', KEYS[2], ARGV[1])
+
+return existed

package/dist/session/scripts/enforce-limit.lua

@@ -0,0 +1,38 @@
+-- enforce-limit.lua (version 1)
+-- Standalone max-session enforcement (admin/repair paths). Evicts the
+-- oldest excess sessions from a user's index using ZSET ordering and
+-- bounded work (never loads the whole index).
+--
+-- KEYS[1] = user session index key
+--
+-- ARGV[1] = maxSessionsPerUser (0 disables)
+-- ARGV[2] = max evictions per call (bounded Lua work; callers loop to
+--           converge when the excess exceeds this bound)
+-- ARGV[3] = session key prefix for this user (same hash tag => same slot)
+--
+-- Returns: { evictedCount, {evictedJtis...} }
+local card = redis.call('ZCARD', KEYS[1])
+local limit = tonumber(ARGV[1])
+
+if limit <= 0 then
+  return { 0, {} }
+end
+
+local excess = card - limit
+
+if excess <= 0 then
+  return { 0, {} }
+end
+
+local n = math.min(excess, tonumber(ARGV[2]))
+local members = redis.call('ZRANGE', KEYS[1], 0, n - 1)
+local prefix = ARGV[3]
+local evicted = {}
+
+for _, member in ipairs(members) do
+  redis.call('DEL', prefix .. member)
+  redis.call('ZREM', KEYS[1], member)
+  table.insert(evicted, member)
+end
+
+return { #evicted, evicted }

package/dist/session/scripts/revoke.lua

@@ -0,0 +1,61 @@
+-- revoke.lua (version 1)
+-- Logically revokes a session: status -> 'revoked' with a bounded tombstone
+-- TTL (remaining absolute lifetime). Revoked sessions never authenticate,
+-- even if a stale copy of the record survives somewhere. Idempotent: a
+-- second revoke returns 2.
+--
+-- KEYS[1] = session record key
+--
+-- ARGV[1] = new serialized envelope for encrypted (v2) sessions,
+--           '' for plain (v1) sessions (the script builds it itself)
+-- ARGV[2] = tombstone TTL (remaining absolute lifetime, clamped >= 1)
+--
+-- Returns:
+--   1   revoked
+--   2   already revoked (idempotent)
+--   0   not found
+--   3   unknown envelope (neither v1 nor v2)
+local raw = redis.call('GET', KEYS[1])
+
+if not raw then
+  return 0
+end
+
+local env = cjson.decode(raw)
+local ttl = tonumber(ARGV[2])
+
+if env.v == 1 then
+  local s = env.s
+
+  if s.status == 'revoked' then
+    return 2
+  end
+
+  s.status = 'revoked'
+  redis.call('SET', KEYS[1], cjson.encode(env), 'EX', ttl)
+  return 1
+end
+
+if env.v == 2 then
+  if env.st == 'revoked' then
+    return 2
+  end
+
+  if ARGV[1] == '' then
+    return 4
+  end
+
+  local newEnv = cjson.decode(ARGV[1])
+  newEnv.st = 'revoked'
+  newEnv.ver = env.ver
+  newEnv.la = env.la
+  newEnv.idle = env.idle
+  newEnv.exp = env.exp
+  newEnv.rn = env.rn
+  newEnv.rj = env.rj
+
+  redis.call('SET', KEYS[1], cjson.encode(newEnv), 'EX', ttl)
+  return 1
+end
+
+return 3