ioredis-toolkit 0.0.1

package/dist/ratelimiter.js

@@ -0,0 +1,289 @@
+import { randomUUID } from 'node:crypto';
+import { defaultLogger } from './logger.js';
+const CONSUME_SCRIPT = `
+local key = KEYS[1]
+local now = tonumber(ARGV[1])
+local window = tonumber(ARGV[2])
+local limit = tonumber(ARGV[3])
+local member = ARGV[4]
+
+redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
+
+local count = redis.call('ZCARD', key)
+if count >= limit then
+  local oldest = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
+  local retryAfter = 0
+  if oldest[2] then
+    retryAfter = math.max(1, math.ceil((tonumber(oldest[2]) + window - now) / 1000))
+  end
+  return { 0, count, -1, retryAfter }
+end
+
+redis.call('ZADD', key, now, member)
+redis.call('PEXPIRE', key, window)
+return { 1, count + 1, limit - count - 1, 0 }
+`;
+const PEEK_SCRIPT = `
+local key = KEYS[1]
+local now = tonumber(ARGV[1])
+local window = tonumber(ARGV[2])
+local limit = tonumber(ARGV[3])
+
+redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
+
+local count = redis.call('ZCARD', key)
+local retryAfter = 0
+if count >= limit then
+  local oldest = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
+  if oldest[2] then
+    retryAfter = math.max(1, math.ceil((tonumber(oldest[2]) + window - now) / 1000))
+  end
+end
+return { count, retryAfter }
+`;
+function failOpenResult(limit, duration) {
+    return {
+        allowed: true,
+        limit,
+        used: 0,
+        remaining: limit,
+        resetAt: Date.now() + duration * 1000,
+        retryAfter: 0,
+    };
+}
+/**
+ * Generic Redis-backed rate limiter that works for any resource: routes, API
+ * endpoints, users, IPs, databases, email sending, etc.
+ *
+ * Keys are namespaced as `ratelimit:{namespace}:{resource}:{identifier}` so each
+ * resource + identifier combination is tracked independently. Supports fixed-window
+ * (`INCR`/`EXPIRE`) and sliding-window (atomic Lua over a sorted set) algorithms.
+ * Fails open when Redis is unavailable.
+ *
+ * @example
+ * ```ts
+ * const limiter = new RateLimiter(client, { limit: 100, duration: 60 });
+ *
+ * const result = await limiter.consume('/api/login', 'ip-10.0.0.1');
+ * if (!result.allowed) {
+ *   throw new Error(`Slow down, retry in ${result.retryAfter}s`);
+ * }
+ * ```
+ */
+export class RateLimiter {
+    client;
+    logger;
+    defaultLimit;
+    defaultDuration;
+    defaultAlgorithm;
+    defaultNamespace;
+    /**
+     * Creates a rate limiter bound to a Redis client.
+     *
+     * @param client - The underlying {@link RedisClientWrapper}.
+     * @param options - Defaults applied when a call does not override them:
+     *   `limit` (default `100`), `duration` in seconds (default `60`),
+     *   `algorithm` (default `'sliding'`), `namespace` (default `'ratelimit'`).
+     * @param logger - Optional pino-compatible logger; defaults to `console`.
+     *
+     * @example
+     * ```ts
+     * const limiter = new RateLimiter(client, { limit: 10, duration: 1, algorithm: 'fixed' });
+     * ```
+     */
+    constructor(client, options = {}, logger = defaultLogger) {
+        this.client = client;
+        this.logger = logger.child({ component: 'RateLimiter' });
+        this.defaultLimit = options.limit ?? 100;
+        this.defaultDuration = options.duration ?? 60;
+        this.defaultAlgorithm = options.algorithm ?? 'sliding';
+        this.defaultNamespace = options.namespace ?? 'ratelimit';
+    }
+    /**
+     * Builds the Redis key for a resource + identifier combination.
+     *
+     * @param resource - The rate-limited resource, e.g. a route `'/api/login'` or
+     *   a resource name `'email:send'`.
+     * @param identifier - The caller identity, e.g. an IP, user id or API key.
+     * @param namespace - Key prefix (defaults to the limiter's namespace).
+     * @returns The full key, e.g. `'ratelimit:/api/login:ip-10.0.0.1'`.
+     *
+     * @example
+     * ```ts
+     * limiter.makeKey('/api/login', 'ip-10.0.0.1');
+     * // 'ratelimit:/api/login:ip-10.0.0.1'
+     * ```
+     */
+    makeKey(resource, identifier, namespace = this.defaultNamespace) {
+        return `${namespace}:${resource}:${identifier}`;
+    }
+    /**
+     * Consumes one unit of capacity for a resource + identifier and returns the
+     * resulting limit state.
+     *
+     * When the limit is reached the request is not recorded and `allowed` is
+     * `false` with `retryAfter` (seconds) and `resetAt` (epoch ms) hints.
+     * Fails open (allows the request) if Redis errors.
+     *
+     * @param resource - The rate-limited resource, e.g. a route `'/api/login'` or
+     *   a resource name `'db:write'`.
+     * @param identifier - The caller identity, e.g. an IP, user id or API key.
+     * @param options - Per-call overrides for `limit`, `duration`, `algorithm`,
+     *   and `namespace`.
+     * @returns The limit state: `allowed`, `limit`, `used`, `remaining`,
+     *   `resetAt` (epoch ms), `retryAfter` (seconds).
+     *
+     * @example
+     * ```ts
+     * const result = await limiter.consume('/api/orders', 'user-7', { limit: 5, duration: 60 });
+     * if (!result.allowed) {
+     *   res.setHeader('Retry-After', String(result.retryAfter));
+     *   return res.status(429).json({ error: 'Too many requests' });
+     * }
+     * ```
+     */
+    async consume(resource, identifier, options = {}) {
+        const limit = options.limit ?? this.defaultLimit;
+        const duration = options.duration ?? this.defaultDuration;
+        const algorithm = options.algorithm ?? this.defaultAlgorithm;
+        const namespace = options.namespace ?? this.defaultNamespace;
+        const key = this.makeKey(resource, identifier, namespace);
+        try {
+            if (algorithm === 'fixed') {
+                return await this.consumeFixed(key, limit, duration);
+            }
+            return await this.consumeSliding(key, limit, duration);
+        }
+        catch (error) {
+            this.logger.error('Rate limit consume failed, failing open', { key, error });
+            return failOpenResult(limit, duration);
+        }
+    }
+    /**
+     * Peeks at the current limit state without consuming capacity.
+     *
+     * Useful for pre-flight checks (e.g. showing "limit reached" in a UI before
+     * the actual request). Also fails open on Redis errors.
+     *
+     * @param resource - The rate-limited resource.
+     * @param identifier - The caller identity.
+     * @param options - Per-call overrides for `limit`, `duration`, `algorithm`,
+     *   and `namespace`.
+     * @returns The current limit state; `used` is not incremented.
+     *
+     * @example
+     * ```ts
+     * const state = await limiter.check('/api/search', 'user-1');
+     * if (state.remaining === 0) {
+     *   // disable the search button
+     * }
+     * ```
+     */
+    async check(resource, identifier, options = {}) {
+        const limit = options.limit ?? this.defaultLimit;
+        const duration = options.duration ?? this.defaultDuration;
+        const algorithm = options.algorithm ?? this.defaultAlgorithm;
+        const namespace = options.namespace ?? this.defaultNamespace;
+        const key = this.makeKey(resource, identifier, namespace);
+        try {
+            if (algorithm === 'fixed') {
+                return await this.checkFixed(key, limit, duration);
+            }
+            return await this.checkSliding(key, limit, duration);
+        }
+        catch (error) {
+            this.logger.error('Rate limit check failed, failing open', { key, error });
+            return failOpenResult(limit, duration);
+        }
+    }
+    /**
+     * Resets the counter for a resource + identifier, granting full capacity again.
+     *
+     * @param resource - The rate-limited resource.
+     * @param identifier - The caller identity.
+     * @param namespace - Key prefix (defaults to the limiter's namespace).
+     * @returns `true` if a counter existed and was removed.
+     *
+     * @example
+     * ```ts
+     * // user upgraded to a premium plan, lift their limits
+     * await limiter.reset('/api/export', 'user-7');
+     * ```
+     */
+    async reset(resource, identifier, namespace = this.defaultNamespace) {
+        const key = this.makeKey(resource, identifier, namespace);
+        try {
+            const deleted = await this.client.del(key);
+            return deleted > 0;
+        }
+        catch (error) {
+            this.logger.error('Rate limit reset failed', { key, error });
+            return false;
+        }
+    }
+    async consumeFixed(key, limit, duration) {
+        const now = Date.now();
+        const count = await this.client.incr(key);
+        if (count === 1) {
+            await this.client.expire(key, duration);
+        }
+        const ttl = await this.client.ttl(key);
+        const ttlSeconds = ttl > 0 ? ttl : duration;
+        const allowed = count <= limit;
+        return {
+            allowed,
+            limit,
+            used: count,
+            remaining: Math.max(0, limit - count),
+            resetAt: now + ttlSeconds * 1000,
+            retryAfter: allowed ? 0 : ttlSeconds,
+        };
+    }
+    async consumeSliding(key, limit, duration) {
+        const now = Date.now();
+        const member = `${now}:${randomUUID()}`;
+        const result = (await this.client.raw.eval(CONSUME_SCRIPT, 1, key, now, duration * 1000, limit, member));
+        const allowed = result[0] === 1;
+        const used = result[1] ?? 0;
+        const remaining = result[2] ?? 0;
+        const retryAfter = result[3] ?? 0;
+        return {
+            allowed,
+            limit,
+            used,
+            remaining: allowed ? remaining : 0,
+            resetAt: now + retryAfter * 1000,
+            retryAfter,
+        };
+    }
+    async checkFixed(key, limit, duration) {
+        const now = Date.now();
+        const raw = await this.client.get(key);
+        const used = raw === null || raw === undefined ? 0 : Number(raw) || 0;
+        const ttl = await this.client.ttl(key);
+        const ttlSeconds = ttl > 0 ? ttl : duration;
+        const allowed = used < limit;
+        return {
+            allowed,
+            limit,
+            used,
+            remaining: Math.max(0, limit - used),
+            resetAt: now + ttlSeconds * 1000,
+            retryAfter: allowed ? 0 : ttlSeconds,
+        };
+    }
+    async checkSliding(key, limit, duration) {
+        const now = Date.now();
+        const result = (await this.client.raw.eval(PEEK_SCRIPT, 1, key, now, duration * 1000, limit));
+        const used = result[0] ?? 0;
+        const retryAfter = result[1] ?? 0;
+        return {
+            allowed: used < limit,
+            limit,
+            used,
+            remaining: Math.max(0, limit - used),
+            resetAt: now + retryAfter * 1000,
+            retryAfter,
+        };
+    }
+}

package/dist/session/index.d.ts

@@ -0,0 +1,23 @@
+export { RedisRevocationStore } from './revocation-store.js';
+export type { RedisRevocationStoreOptions } from './revocation-store.js';
+export { RevocationBatchError, RevocationError } from './session-errors.js';
+export { createSessionManager, SessionManager } from './session-manager.js';
+export type { SessionManagerOptions } from './session-manager.js';
+export { SessionService } from './session-service.js';
+export type { SessionServiceDeps } from './session-service.js';
+export { SessionRepository } from './session-repository.js';
+export type { SessionScriptRegistryOptions } from './session-scripts.js';
+export { SessionScriptRegistry, SCRIPT_NAMES } from './session-scripts.js';
+export type { ScriptName } from './session-scripts.js';
+export { SessionKeyStrategy, encodeUserId } from './session-keys.js';
+export { SessionTokenManager } from './session-token.js';
+export { StaticSessionKeyProvider, createRandomSessionKeyProvider, toKeyBuffer, } from './session-encryption.js';
+export { serializeSession, serializeEncryptedSession, deserializeSession, validateSessionRecord, envelopeKind, encryptedHeaderOf, } from './session-serializer.js';
+export { parseSessionConfig, redactSessionConfig, SessionConfigSchema, TTL, IDLE_TIMEOUT, TOUCH_INTERVAL, } from './session-config.js';
+export type { SessionConfig, SessionConfigInput, PartialSessionConfig, } from './session-config.js';
+export { SessionError, SessionNotFoundError, SessionExpiredError, SessionRevokedError, SessionInvalidError, SessionRotationError, SessionReplayError, SessionStorageError, SessionSerializationError, SessionConfigurationError, SessionConcurrencyError, CircuitBreakerOpenError, redactIdentifier, } from './session-errors.js';
+export type { SessionRecord, SessionCreateInput, SessionUpdatePatch, CreatedSession, RotatedSession, SessionValidationResult, SessionInvalidReason, TouchOutcome, SessionEnvelope, } from './session-types.js';
+export { SessionMetrics, type SessionMetricsAdapter } from './session-metrics.js';
+export { SessionCircuitBreaker } from './session-circuit-breaker.js';
+export { SessionHealthChecker } from './session-health.js';
+export { SessionCookieManager, type SerializeCookieOptions, type SerializedCookie, type SerializedCookieAttributes, } from './session-cookie.js';

package/dist/session/index.js

@@ -0,0 +1,16 @@
+export { RedisRevocationStore } from './revocation-store.js';
+export { RevocationBatchError, RevocationError } from './session-errors.js';
+export { createSessionManager, SessionManager } from './session-manager.js';
+export { SessionService } from './session-service.js';
+export { SessionRepository } from './session-repository.js';
+export { SessionScriptRegistry, SCRIPT_NAMES } from './session-scripts.js';
+export { SessionKeyStrategy, encodeUserId } from './session-keys.js';
+export { SessionTokenManager } from './session-token.js';
+export { StaticSessionKeyProvider, createRandomSessionKeyProvider, toKeyBuffer, } from './session-encryption.js';
+export { serializeSession, serializeEncryptedSession, deserializeSession, validateSessionRecord, envelopeKind, encryptedHeaderOf, } from './session-serializer.js';
+export { parseSessionConfig, redactSessionConfig, SessionConfigSchema, TTL, IDLE_TIMEOUT, TOUCH_INTERVAL, } from './session-config.js';
+export { SessionError, SessionNotFoundError, SessionExpiredError, SessionRevokedError, SessionInvalidError, SessionRotationError, SessionReplayError, SessionStorageError, SessionSerializationError, SessionConfigurationError, SessionConcurrencyError, CircuitBreakerOpenError, redactIdentifier, } from './session-errors.js';
+export { SessionMetrics } from './session-metrics.js';
+export { SessionCircuitBreaker } from './session-circuit-breaker.js';
+export { SessionHealthChecker } from './session-health.js';
+export { SessionCookieManager, } from './session-cookie.js';

package/dist/session/revocation-store.d.ts

@@ -0,0 +1,171 @@
+import type { RevocationRecord, RevocationStore } from './session-types.js';
+import type { RedisClientWrapper } from '../client.js';
+export interface RedisRevocationStoreOptions {
+    /**
+     * Redis client.
+     *
+     * Compatible with:
+     * - ioredis standalone
+     * - ioredis Sentinel
+     * - ioredis Cluster
+     */
+    client: RedisClientWrapper;
+    /**
+     * Key prefix, so multiple apps can share a Redis instance safely.
+     * Default: `authcore:revoked:`.
+     *
+     * @example
+     * ```ts
+     * new RedisRevocationStore({ client, keyPrefix: 'auth:revoked:' });
+     * ```
+     */
+    keyPrefix?: string;
+}
+/**
+ * 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 declare class RedisRevocationStore implements RevocationStore {
+    private readonly client;
+    private readonly 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: RedisRevocationStoreOptions);
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    revoke(record: RevocationRecord): Promise<void>;
+    /**
+     * 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 },
+     * ]);
+     * ```
+     */
+    revokeMany(records: RevocationRecord[]): Promise<void>;
+    /**
+     * 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
+     * }
+     * ```
+     */
+    isRevoked(jti: string): Promise<boolean>;
+    /**
+     * 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
+     * }
+     * ```
+     */
+    isRevokedMany(jtis: string[]): Promise<Set<string>>;
+    private key;
+}