ioredis-toolkit 0.0.9 → 0.0.11

package/docs/modules/sessions/usage.md

@@ -0,0 +1,262 @@
+# Sessions Module — Complete Usage Guide
+
+`SessionManager` is a framework-independent Redis-backed authentication-session subsystem. Raw session credentials are returned only at creation/rotation time and are not stored as plaintext Redis values.
+
+## Setup with the unified client
+
+```ts
+import { createRedisClient } from 'ioredis-toolkit';
+
+const redis = createRedisClient({
+  mode: 'standalone',
+  host: '127.0.0.1',
+  port: 6379,
+  sessions: {
+    enabled: true,
+    namespace: 'auth',
+    tokenBytes: 32,
+    ttl: 60 * 60 * 24 * 30,
+    rolling: true,
+    idleTimeout: 60 * 60 * 24 * 7,
+    absoluteTimeout: 60 * 60 * 24 * 30,
+    touchInterval: 60,
+    securityVersionEnabled: true,
+    maxSessionsPerUser: 20,
+    maxMetadataBytes: 8192,
+  },
+});
+
+const sessions = redis.sessions;
+```
+
+To supply a metrics sink or an encryption key manager alongside `createRedisClient()`, pass them as the second argument:
+
+```ts
+const redis = createRedisClient(
+  { mode: 'standalone', host: '127.0.0.1', port: 6379, sessions: { enabled: true } },
+  { metrics: myMetricsSink, encryptionKeyManager: myKeyManager },
+);
+```
+
+Sessions must be explicitly enabled. Creating the client does not require session initialization until `redis.sessions` is accessed.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---:|---|
+| `enabled` | `boolean` | `false` | Enables the session subsystem. |
+| `namespace` | `string` | `app` | Session key namespace. |
+| `tokenBytes` | `number` | `32` | Random secret bytes; minimum 32 (256 bits). |
+| `ttl` | `number` | 30 days | Hard Redis/session lifetime in seconds. |
+| `idleTimeout` | `number` | unset | Optional rolling inactivity lifetime. |
+| `absoluteTimeout` | `number` | unset | Optional hard application lifetime. |
+| `touchInterval` | `number` | 60 | Minimum interval between rolling touch writes. |
+| `rolling` | `boolean` | `true` | Enables rolling idle expiration behavior. |
+| `securityVersionEnabled` | `boolean` | `false` | Enables per-user security-version invalidation. |
+| `maxSessionsPerUser` | `number` | 20 | Maximum configured indexed sessions per user. |
+| `maxMetadataBytes` | `number` | 8192 | Maximum metadata JSON size. |
+| `maxBatchSize` | `number` | 200 | Maximum bounded administrative batch. |
+| `maxConcurrency` | `number` | 8 | Maximum bounded cross-slot/application fan-out. |
+| `storeIpAddress` | `boolean` | false | Persists IP metadata when enabled. |
+| `storeUserAgent` | `boolean` | false | Persists user-agent metadata when enabled. |
+| `storeDeviceId` | `boolean` | false | Persists device ID metadata when enabled. |
+| `encryption.enabled` | `boolean` | false | Enables authenticated encryption for serialized session values when a key manager is supplied. |
+| `circuitBreaker` | object | see below | Reserved configuration, fully defaulted and validated like every other nested section. Not yet consulted by any repository/service code path — there is no circuit-breaker behavior wired up in this release. |
+| `cookie` | object | secure defaults | Cookie serialization settings. |
+
+`circuitBreaker` defaults to `{ enabled: false, failureThreshold: 5, resetTimeoutMs: 10_000, halfOpenMaxRequests: 1 }` and, like `encryption` and `cookie`, may be omitted entirely.
+
+## `create(input)`
+
+Creates a session and returns the raw opaque token exactly once.
+
+```ts
+const created = await sessions.create({
+  userId: 'user_123',
+  deviceId: 'device_1',
+  ipAddress: '203.0.113.10',
+  userAgent: 'Mozilla/5.0',
+  metadata: { loginMethod: 'password', rememberMe: true },
+});
+
+// Store this only in the client's secure cookie/session transport.
+const token = created.token;
+console.log(created.session.id, created.session.expiresAt);
+```
+
+The token is an opaque credential composed of a random JTI and random secret. The authoritative Redis session record does not contain the raw token.
+
+## `validate(token)`
+
+Returns a discriminated result instead of throwing for ordinary invalid-session conditions.
+
+```ts
+const result = await sessions.validate(request.cookies.session ?? '');
+if (!result.valid) {
+  // reason may be not_found, expired, idle_timeout, absolute_timeout,
+  // revoked, consumed, or invalid.
+  return unauthorized();
+}
+const userId = result.session.userId;
+```
+
+Infrastructure failures are different from an invalid credential and are surfaced as storage errors; applications should not convert infrastructure failures into successful authentication.
+
+## `get(token)`
+
+Gets an active authoritative session or throws a typed session error.
+
+```ts
+const session = await sessions.get(token);
+```
+
+Use this when the caller wants exception-based control flow rather than the discriminated `validate()` result.
+
+## `touch(token)`
+
+Applies rolling idle-expiration rules. Touches are throttled by `touchInterval` and are bounded by the absolute expiration.
+
+```ts
+await sessions.touch(token);
+```
+
+It is usually appropriate to call this on authenticated requests without writing every request to Redis.
+
+## `update(token, patch, expectedVersion?)`
+
+Updates mutable metadata with optional optimistic concurrency.
+
+```ts
+const current = await sessions.get(token);
+const updated = await sessions.update(token, {
+  metadata: { ...current.metadata, theme: 'dark' },
+}, current.version);
+```
+
+If another writer changed the record first, the expected-version check prevents an unintended lost update.
+
+## `rotate(token)`
+
+Consumes the predecessor and creates a successor token atomically within the session's Redis hash-tag slot.
+
+```ts
+const rotated = await sessions.rotate(token);
+// Replace the client cookie with rotated.token.
+```
+
+After successful rotation, the predecessor is no longer accepted. Concurrent rotation attempts must not produce multiple valid successors. The successor's rolling idle-timeout window preserves the duration originally configured when the session (or its earliest ancestor) was created, rather than being re-derived from the predecessor's most recent touch — so the idle window does not silently shrink across repeated rotations. If the predecessor is consumed but successor creation then fails, `rotate()` throws `SessionRotationError` rather than leaving the caller with an ambiguous storage error.
+
+## `revoke(token)`
+
+Marks a session unusable.
+
+```ts
+await sessions.revoke(token);
+```
+
+Revocation is idempotent from the application's perspective. `revoke()` (and rotation's internal predecessor `consume()`) remove the session from the user's index immediately rather than only relying on `list()`'s lazy self-heal, so a revoked/rotated session stops counting toward `maxSessionsPerUser` right away instead of only once its tombstone expires.
+
+## `destroy(token)`
+
+Permanently removes the session record and derived indexes.
+
+```ts
+await sessions.destroy(token);
+```
+
+Use `revoke()` when you need an explicit invalidation state; use `destroy()` when removing stored session data is preferable.
+
+## `setSecurityVersion(userId, version)`
+
+Sets a per-user security version when the feature is enabled. Sessions carrying an older version fail authentication.
+
+```ts
+await sessions.setSecurityVersion('user_123', 8);
+```
+
+A common password-reset/logout-all pattern is to increment the user's security version and then let old sessions fail validation.
+
+## `revokeAll(userId, limit?)`
+
+Revokes a bounded batch and returns `{ affected, remaining }` so large user indexes do not require loading every session into memory.
+
+```ts
+let page = await sessions.revokeAll('user_123', 200);
+while (page.remaining > 0) {
+  page = await sessions.revokeAll('user_123', 200);
+}
+```
+
+Use bounded loops or background jobs for users with unusually large session counts.
+
+## `list(userId, offset?, limit?)`
+
+Returns a bounded page of authoritative sessions for an application user.
+
+```ts
+const sessionsForUser = await sessions.list('user_123', 0, 50);
+```
+
+This is an administrative/management operation, not an authentication primitive. A `limit` greater than the configured `maxBatchSize` throws `SessionLimitError` (a malformed `offset`/`limit` throws `SessionInvalidError`).
+
+## Cookie helpers
+
+The package also exposes cookie serializers:
+
+```ts
+import { serializeCookie, serializeDeletionCookie } from 'ioredis-toolkit';
+
+const header = serializeCookie(token, {
+  name: 'session',
+  httpOnly: true,
+  secure: true,
+  sameSite: 'lax',
+  path: '/',
+  maxAge: 60 * 60 * 24 * 30,
+});
+
+const clear = serializeDeletionCookie({ name: 'session', path: '/' });
+```
+
+Cookie authentication requires a CSRF strategy appropriate to the application. `HttpOnly` protects against direct JavaScript reads but does not itself prevent CSRF.
+
+## Security and topology model
+
+Session records and per-user indexes use a user-derived Redis hash tag so operations concerning one user's sessions can be atomic within one Cluster slot. Operations spanning different users are not treated as cross-slot transactions.
+
+Never log raw session tokens. Do not put them into metrics labels, traces, exception messages, or persistent application logs.
+
+`RedisRevocationStore` is a separate, standalone utility for credentials whose authorization model is JTI-based (such as externally issued JWTs) — see [docs/README-API.md](../../README-API.md). It is intentionally **not** consulted by `SessionService`: this module's opaque sessions treat session state itself as the source of truth and deliberately avoid an extra revocation-key lookup on every `validate()` call.
+
+## Errors
+
+All typed errors extend `SessionError` and carry a stable `code`:
+
+| Class | Code | Thrown by |
+|---|---|---|
+| `SessionNotFoundError` | `SESSION_NOT_FOUND` | `get()` when the token resolves to no record |
+| `SessionExpiredError` | `SESSION_EXPIRED` | `get()`/`touch()`/`rotate()` on an expired/idle-timed-out session |
+| `SessionRevokedError` | `SESSION_REVOKED` | `get()` on a revoked session |
+| `SessionReplayError` | `SESSION_REPLAY` | `rotate()` on a non-active (already consumed/revoked) session |
+| `SessionRotationError` | `SESSION_ROTATION` | `rotate()` when the predecessor was already consumed, cannot be rotated, or the successor could not be created after the predecessor was consumed |
+| `SessionConflictError` | `SESSION_CONFLICT` | `update()` on a stale `expectedVersion` |
+| `SessionLimitError` | `SESSION_LIMIT` | `list()` when `limit` exceeds `maxBatchSize` |
+| `SessionInvalidError` | `SESSION_INVALID` | malformed input, or a session that fails an index/security-version check |
+| `SessionStorageError` | `SESSION_STORAGE` | Redis-level read/write failures |
+| `SessionSerializationError` | `SESSION_SERIALIZATION` | a record cannot be serialized, or fails schema/decryption validation on read |
+| `SessionConfigurationError` | `SESSION_CONFIGURATION` | invalid session configuration, or constructing the manager while `enabled: false` |
+
+`validate()` never throws for ordinary invalid-credential conditions — see the discriminated result above. These errors surface from `get()` and the other exception-based methods.
+
+## Metrics
+
+`SessionService` accepts an optional `metrics: SessionMetrics` sink (via `createSessionManager({ ..., metrics })` or `createRedisClient(config, { metrics })`) and defaults to a no-op implementation (`NoopMetrics`) when none is supplied. When configured, it receives `increment()` calls for `session.created`, `session.validate` (labeled `result: 'valid' | 'invalid'`, plus `reason` on the invalid path), `session.rotated`, `session.revoked`, and `session.destroyed`.
+
+## Unified configuration overrides
+
+```ts
+redis.withSessions({ idleTimeout: 60 * 60 });
+redis.withSessions({ namespace: 'auth:v2', rolling: false }, 'replace');
+```
+
+`merge` preserves existing normalized values; `replace` applies the supplied values on top of module defaults.

package/docs/modules/streams/README.md

@@ -0,0 +1,7 @@
+# Streams module
+
+This directory contains the complete usage documentation for the streams module.
+
+**Full guide:** [usage.md](./usage.md)
+
+The usage guide documents configuration, public types, every public method, arguments, return values, semantics, error/edge-case behavior, and multiple examples.

package/docs/modules/streams/usage.md

@@ -0,0 +1,141 @@
+# Streams Module — Complete Usage Guide
+
+`RedisStreams` wraps Redis Streams for append, consumer-group creation, reads, acknowledgements, deletion, and length inspection.
+
+## Setup
+
+```ts
+import { createRedisClient } from 'ioredis-toolkit';
+
+const redis = createRedisClient({
+  mode: 'standalone',
+  host: '127.0.0.1',
+  port: 6379,
+  streams: { enabled: true, keyPrefix: 'myapp:stream', maxEntries: 100_000, blockMs: 5_000 },
+});
+```
+
+`streams.enabled` defaults to `false`. Accessing `redis.streams` while disabled throws `RedisConfigurationError`; set `enabled: true` to use the module.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---:|---|
+| `enabled` | `boolean` | `false` | Enables the module. `redis.streams` throws `RedisConfigurationError` while disabled; `new RedisStreams(...)` remains directly constructible either way. |
+| `keyPrefix` | `string` | `stream` | Physical stream prefix. |
+| `maxEntries` | `number` | `100000` | Approximate retained entry limit used by `add()`. |
+| `blockMs` | `number` | `5000` | Default blocking duration applied to `read()` whenever a call does not pass its own `blockMs`. |
+
+## `key(name)`
+
+Builds the physical stream key.
+
+```ts
+redis.streams.key('orders'); // myapp:stream:orders
+```
+
+## `add(name, fields, maxEntries?)`
+
+Appends a record with Redis-generated `*` ID and approximate trimming.
+
+```ts
+const id = await redis.streams.add('orders', {
+  type: 'created',
+  orderId: 'ord_123',
+  userId: 'user_42',
+});
+```
+
+Override retention for a particular stream:
+
+```ts
+await redis.streams.add('audit', { event: 'login' }, 1_000_000);
+```
+
+Fields are strings because Redis Streams are field/value strings. Serialize structured values explicitly.
+
+```ts
+await redis.streams.add('events', {
+  payload: JSON.stringify({ orderId: 'ord_1', amount: 25 }),
+});
+```
+
+## `createGroup(name, group, startId?, mkStream?)`
+
+Creates a consumer group. `BUSYGROUP` is treated as idempotent success.
+
+```ts
+await redis.streams.createGroup('orders', 'workers', '0', true);
+```
+
+Using `$` starts at the end of the stream, while `0` allows existing entries to be delivered.
+
+## `read(name, options?)`
+
+Reads normal stream entries or consumer-group entries. Every read now blocks for `blockMs` (per-call, or the configured default when omitted) — pass a small `blockMs` (or `0`, which blocks indefinitely per Redis semantics) deliberately rather than relying on an implicit non-blocking read.
+
+Normal read:
+
+```ts
+const entries = await redis.streams.read('orders', {
+  id: '0-0',
+  count: 50,
+});
+```
+
+Consumer-group read:
+
+```ts
+const entries = await redis.streams.read('orders', {
+  group: 'workers',
+  consumer: 'worker-1',
+  count: 20,
+  blockMs: 5000,
+});
+for (const entry of entries) {
+  console.log(entry.id, entry.fields);
+}
+```
+
+`StreamReadOptions`:
+
+- `group`: consumer group name.
+- `consumer`: consumer name; **required** when `group` is supplied — `read()` throws a `RangeError` if `group` is set without `consumer`, instead of silently falling back to a plain, incorrectly-cursored `XREAD`.
+- `count`: maximum requested entries.
+- `blockMs`: optional Redis blocking read duration; defaults to the module's configured `blockMs` when omitted.
+- `id`: starting/continuation ID; group reads commonly use `>` for new messages.
+
+## `ack(name, group, ...ids)`
+
+Acknowledges processed consumer-group messages.
+
+```ts
+await redis.streams.ack('orders', 'workers', '1750000000000-0');
+```
+
+## `delete(name, ...ids)`
+
+Deletes specific entries.
+
+```ts
+await redis.streams.delete('orders', '1750000000000-0');
+```
+
+## `length(name)`
+
+Returns current stream length.
+
+```ts
+const size = await redis.streams.length('orders');
+```
+
+## Operational guidance
+
+Consumer groups create pending-entry state. Production consumers should also implement a pending-entry recovery strategy using native Redis commands appropriate to their workload. This wrapper intentionally keeps its surface small and does not pretend that a single `read()` loop is a complete queue-processing framework.
+
+## Overrides
+
+```ts
+redis.withStreams({ maxEntries: 500_000, blockMs: 10_000 });
+redis.withStreams({ keyPrefix: 'critical-streams' }, 'replace');
+```

package/package.json

@@ -1,50 +1,53 @@
 {
   "name": "ioredis-toolkit",
-  "version": "0.0.9",
-  "description": "Production-grade, type-safe Redis infrastructure for standalone, Sentinel, and Cluster deployments",
+  "version": "0.0.11",
+  "description": "Production-grade Redis sessions, cache, locks, rate limiting, Pub/Sub, and Streams for Node.js",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./types": {
-      "types": "./dist/types.d.ts",
-      "import": "./dist/types.js"
+    "./cache": {
+      "types": "./dist/cache/cache.d.ts",
+      "import": "./dist/cache/cache.js"
     },
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js"
+    "./lock": {
+      "types": "./dist/lock/lock.d.ts",
+      "import": "./dist/lock/lock.js"
     },
-    "./cache": {
-      "types": "./dist/cache.d.ts",
-      "import": "./dist/cache.js"
+    "./rate-limit": {
+      "types": "./dist/rate-limit/rate-limiter.d.ts",
+      "import": "./dist/rate-limit/rate-limiter.js"
     },
     "./pubsub": {
-      "types": "./dist/pubsub.d.ts",
-      "import": "./dist/pubsub.js"
+      "types": "./dist/pubsub/pubsub.d.ts",
+      "import": "./dist/pubsub/pubsub.js"
     },
-    "./lock": {
-      "types": "./dist/lock.d.ts",
-      "import": "./dist/lock.js"
-    },
-    "./health": {
-      "types": "./dist/health.d.ts",
-      "import": "./dist/health.js"
+    "./streams": {
+      "types": "./dist/streams/streams.d.ts",
+      "import": "./dist/streams/streams.js"
     },
-    "./ratelimiter": {
-      "types": "./dist/ratelimiter.d.ts",
-      "import": "./dist/ratelimiter.js"
+    "./sessions": {
+      "types": "./dist/session/manager.d.ts",
+      "import": "./dist/session/manager.js"
     },
-    "./session": {
-      "types": "./dist/session/index.d.ts",
-      "import": "./dist/session/index.js"
-    }
+    "./package.json": "./package.json"
   },
+  "files": [
+    "dist",
+    "src/scripts",
+    "docs",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "author": "Anwar <anwarkamal1434@gmail.com>",
-  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/org-utils/ioredis-toolkit.git"
@@ -58,49 +61,36 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "tsc && node scripts/copy-assets.mjs",
-    "build:watch": "tsc --watch",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
     "test:coverage": "vitest run --coverage",
-    "format": "prettier --write 'src/**/*.ts'",
-    "clean:git": "git clean -xdf",
+    "clean": "rm -rf dist",
     "changeset:init": "changeset init",
     "changeset": "changeset",
     "version": "changeset version",
     "publish": "changeset publish",
     "release": "bun build && changeset publish",
     "prebuild": "bun typecheck",
-    "test:unit": "vitest run test/cluster-slot.test.ts test/config.test.ts test/client.test.ts test/cache.test.ts test/ratelimiter.test.ts"
+    "prepublishOnly": "npm run clean && npm run build && npm test"
   },
-  "keywords": [
-    "redis",
-    "cluster",
-    "sentinel",
-    "distributed",
-    "cache",
-    "pubsub",
-    "locking"
-  ],
   "dependencies": {
-    "ioredis": "^5.11.1",
-    "zod": "^4.4.3"
-  },
-  "engines": {
-    "node": ">=22.0.0"
+    "ioredis": "^5.6.1",
+    "zod": "^4.1.5"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
   "devDependencies": {
-    "@changesets/changelog-github": "^0.7.0",
-    "@changesets/cli": "^2.31.1",
-    "@types/node": "^26.2.0",
-    "ioredis-mock": "^8.13.1",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
-  }
+    "@changesets/changelog-github": "^1.0.1",
+    "@changesets/cli": "^3.0.2",
+    "@types/node": "^24.3.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.34.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.42.0",
+    "vitest": "^3.2.4"
+  },
+  "license": "MIT",
+  "sideEffects": false
 }

package/src/scripts/cleanup-index.lua

@@ -0,0 +1,4 @@
+-- KEYS[1] user index
+-- ARGV[1..N] stale token hashes (user-index ZSET members, not JTIs)
+for i=1,#ARGV do redis.call('ZREM', KEYS[1], ARGV[i]) end
+return #ARGV

package/src/scripts/conditional-update.lua

@@ -0,0 +1,21 @@
+-- Reference copy only. This duplicates update-session.lua: both must mirror the
+-- authoritative script actually executed at runtime, SCRIPT_SOURCES.update_session
+-- in src/session/script-sources.ts. Do not use this script directly.
+-- KEYS[1] session key
+-- ARGV[1] expected version
+-- ARGV[2] now
+-- ARGV[3] serialized replacement
+local raw = redis.call('GET', KEYS[1])
+if not raw then return {0} end
+local ok, s = pcall(cjson.decode, raw)
+if not ok or not s.data then return {-4} end
+if s.data.status ~= 'active' then return {-3} end
+if tonumber(s.data.version) ~= tonumber(ARGV[1]) then return {-2, s.data.version} end
+local replacement = ARGV[3]
+local ok2, parsed = pcall(cjson.decode, replacement)
+if not ok2 or not parsed.data then return {-4} end
+if parsed.data.userId ~= s.data.userId or parsed.data.jti ~= s.data.jti or parsed.data.id ~= s.data.id or parsed.data.createdAt ~= s.data.createdAt or parsed.data.absoluteExpiresAt ~= s.data.absoluteExpiresAt then return {-5} end
+local ttl = tonumber(s.data.expiresAt) - tonumber(ARGV[2])
+if ttl <= 0 then return {-1} end
+redis.call('SET', KEYS[1], replacement, 'XX', 'EX', ttl)
+return {1}

package/src/scripts/consume-session.lua

@@ -0,0 +1,21 @@
+-- KEYS[1] session key
+-- ARGV[1] now epoch seconds
+-- ARGV[2] tombstone ttl seconds
+local raw = redis.call('GET', KEYS[1])
+if not raw then return {0} end
+local ok, s = pcall(cjson.decode, raw)
+if not ok or not s.data then return {-4} end
+local r = s.data
+if r.status == 'consumed' then return {-1} end
+if r.status == 'revoked' then return {-3} end
+local now = tonumber(ARGV[1])
+if tonumber(r.expiresAt) <= now then return {-2} end
+if r.absoluteExpiresAt and r.absoluteExpiresAt ~= cjson.null and tonumber(r.absoluteExpiresAt) > 0 and tonumber(r.absoluteExpiresAt) <= now then return {-2} end
+if r.idleExpiresAt and tonumber(r.idleExpiresAt) > 0 and tonumber(r.idleExpiresAt) <= now then return {-2} end
+r.status = 'consumed'
+r.consumedAt = now
+r.version = tonumber(r.version) + 1
+local ttl = tonumber(ARGV[2])
+local encoded = cjson.encode({v=1, data=r})
+redis.call('SET', KEYS[1], encoded, 'XX', 'EX', ttl)
+return {1, r.userId, r.jti, r.version}

package/src/scripts/create-session.lua

@@ -0,0 +1,28 @@
+-- Reference copy only. The authoritative script actually executed at runtime is
+-- SCRIPT_SOURCES.create_session in src/session/script-sources.ts — keep this file in sync with it.
+-- KEYS[1] session key
+-- KEYS[2] user index
+-- ARGV[1] serialized record
+-- ARGV[2] ttl seconds
+-- ARGV[3] createdAt score
+-- ARGV[4] tokenHash
+-- ARGV[5] max sessions (0 = unlimited)
+-- ARGV[6] namespace
+-- ARGV[7] userTag
+local created = redis.call('SET', KEYS[1], ARGV[1], 'NX', 'EX', ARGV[2])
+if not created then return {-1} end
+redis.call('ZADD', KEYS[2], ARGV[3], ARGV[4])
+if tonumber(ARGV[5]) > 0 then
+  local count = redis.call('ZCARD', KEYS[2])
+  if count > tonumber(ARGV[5]) then
+    local excess = count - tonumber(ARGV[5])
+    local old = redis.call('ZRANGE', KEYS[2], 0, excess - 1)
+    for _, evictedHash in ipairs(old) do
+      redis.call('ZREM', KEYS[2], evictedHash)
+      redis.call('DEL', ARGV[6] .. ':session:{' .. ARGV[7] .. '}:' .. evictedHash)
+      redis.call('DEL', ARGV[6] .. ':token-index:' .. evictedHash)
+    end
+    return {1, excess}
+  end
+end
+return {1}

package/src/scripts/delete.lua

@@ -0,0 +1,2 @@
+-- KEYS[1] session key
+return redis.call('DEL', KEYS[1])

package/src/scripts/destroy-user.lua

@@ -0,0 +1,13 @@
+-- Reference copy only. Not present in SCRIPT_SOURCES and not executed by the
+-- repository at runtime (SessionRepository.revokeAll implements the equivalent
+-- operation in TypeScript via a pipeline). Bounded helper: the application must
+-- pass session keys to delete as KEYS, matching enforce-limit.lua's pattern.
+-- KEYS[1] user index; KEYS[2..N] session keys corresponding to the returned members.
+-- ARGV[1] max batch
+local n = tonumber(ARGV[1])
+local members = redis.call('ZRANGE', KEYS[1], 0, n - 1)
+for i, tokenHash in ipairs(members) do
+  redis.call('ZREM', KEYS[1], tokenHash)
+  redis.call('DEL', KEYS[i + 1])
+end
+return members