ioredis-toolkit 0.0.10 → 0.5.0

package/dist/session/scripts/create.lua

@@ -1,83 +0,0 @@
--- create.lua (version 1)
--- Atomically creates a session record, registers it in the user index
--- (ZSET, score = microsecond-resolution Redis server time, used purely
--- for eviction ordering - see below), 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]))
-
--- The user index score is used purely for oldest-first eviction ordering
--- (never as the record's createdAt, which is app-stamped seconds inside the
--- envelope). Redis breaks equal ZSET scores by lexicographic member order,
--- not insertion order, so scoring by second-granularity createdAt would
--- make eviction pick an arbitrary (jti-lexicographic) session rather than
--- the actual oldest one whenever a user creates more than one session in
--- the same wall-clock second - a realistic case under normal traffic, not
--- just a burst edge case. Redis is single-threaded, so two scripts touching
--- the same user slot never observe the same TIME() reading in practice;
--- microsecond-resolution server time therefore gives a strictly monotonic,
--- clock-skew-free ordering key for this user's index.
-local t = redis.call('TIME')
-local orderScore = tonumber(t[1]) + (tonumber(t[2]) / 1000000)
-redis.call('ZADD', index, orderScore, 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

@@ -1,29 +0,0 @@
--- 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

@@ -1,15 +0,0 @@
--- 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

@@ -1,38 +0,0 @@
--- 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

@@ -1,61 +0,0 @@
--- 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

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

@@ -1,149 +0,0 @@
--- 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/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[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/{-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
-  return 0
-end
-
-local env = cjson.decode(raw)
-
-if env.v ~= 2 then
-  return 6
-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
--- 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
-
-  -- 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
-
-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]
-consumedEnv.fam = familyId
-
-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
-nextEnv.fam = familyId
-
-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])
--- 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

@@ -1,167 +0,0 @@
--- 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.
---
--- 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
---
--- 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
--- 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; 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
-  return 0
-end
-
-local env = cjson.decode(raw)
-
-if env.v ~= 1 then
-  return 5
-end
-
-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
--- 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
-
-  -- 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
-
-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.familyId = familyId
-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])
--- 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] }

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

@@ -1,89 +0,0 @@
--- 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