@exortek/apikey 1.0.0

package/dist/stores.cjs

@@ -0,0 +1,880 @@
+'use strict';
+
+/**
+ * Non-throwing type predicates. Companion to `asserts.js`.
+ *
+ * ### When to reach for which
+ *
+ * - Writing a **throw-guard** at a function boundary — a bad shape
+ *   should fail with the caller's typed error class? Use
+ *   `asserts` + `defineGuards` (`assertObject`, `assertString`, …).
+ *   The `assert*` family bundles the check with the correctly-bound
+ *   throw and preserves the "one error class per package" contract.
+ *
+ * - Writing a **dispatch / branch / fallback** where the wrong shape
+ *   is meant to be handled, not thrown? Use these predicates.
+ *   Typical shapes:
+ *
+ *     if (isObject(config.store)) { ... } else { ... }
+ *
+ *     const isManager = isObject(v) && isFunction(v.issue);
+ *
+ * The two APIs deliberately do not overlap in intent: `assert*` throws,
+ * `is*` never does. Bypassing an `assert*` with an `if (!is*(x)) throw
+ * new PkgError(...)` pattern skips the package's guards binding and
+ * duplicates work the assert family already handles — don't.
+ */
+
+/**
+ * `true` when `value` is a plain object *or* a class instance — anything
+ * whose property access is safe. Rejects `null`, arrays, and every
+ * primitive.
+ *
+ * The Node convention `typeof x === 'object' && x !== null` accepts
+ * arrays, which almost never matches caller intent (an array is not a
+ * "config object"). This predicate additionally rules arrays out, so
+ * `isObject(x)` really means "I can read `x.foo` without exploding on
+ * a numeric index".
+ *
+ * Class instances (Node `KeyObject`, `URL`, user-defined classes) pass
+ * because they carry `typeof === 'object'` — the check is duck-typed,
+ * not prototype-restricted.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * `true` when `value` is a string primitive. `String` boxed objects
+ * (from `new String('x')`) are refused — those are a footgun almost no
+ * one wants, and every place in this codebase reads strings by
+ * primitive access.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isString(value) {
+  return typeof value === 'string';
+}
+
+/**
+ * `true` when `value` is a function. Class constructors, arrow
+ * functions, and generator functions all pass — `typeof` on any
+ * callable is `'function'`.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isFunction(value) {
+  return typeof value === 'function';
+}
+
+/**
+ * `true` when `value` is `undefined`.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isUndefined(value) {
+  return typeof value === 'undefined';
+}
+
+/**
+ * Imperative single-argument guard helpers — the everyday
+ * `assertPositiveInt(x, 'name')` shape used at API boundaries.
+ * Companion to the compound schema builder in
+ * `@exortek/shared/validate`: **schema** for whole options objects,
+ * **asserts** for one-liner argument guards at the call site.
+ *
+ * The consumer surface is {@link defineGuards} (or the raw
+ * {@link bindAsserts} for full control). Each package binds the assert
+ * set to its own typed error class once (in `internal/guards.js`), so
+ * every argument failure throws that package's class —
+ * `err instanceof CryptoError` holds and users see at a glance which
+ * package raised the error. The bound `parse` bridges
+ * `@exortek/shared/validate` schemas to the same error class.
+ *
+ * **Path naming convention** (used as the `name` argument):
+ *
+ *   `<publicFunction>[.options|.config][.<field>]`
+ *
+ *   - `assertString(name, 'createUser.name')`          — top-level arg
+ *   - `assertPositiveInt(n, 'scrypt.options.r')`       — nested option
+ *   - `assertBytesOrString(pwd, 'pepper.wrap.password')` — method arg
+ *
+ * Keep the path short: the emitted error is `"<name> must be <desc>"`,
+ * so a stack-line grep already tells the caller which function fired.
+ * Reserve `hint` for actionable follow-ups ("pass the bytes returned by
+ * encryptSymmetric()"), not for restating the field.
+ */
+
+/**
+ * @typedef {{ cause?: unknown }} WrapExtra
+ *   Extra options forwarded to the wrap function, so `invalidArgument`
+ *   sites that catch an underlying error can preserve the `cause` chain
+ *   without falling back to a raw `new PackageError(...)`.
+ *
+ * @typedef {(message: string, extra?: WrapExtra) => Error} WrapFn
+ *   Constructs (never throws) the binding package's error, e.g.
+ *   `(m, { cause } = {}) => new CryptoError(ErrorCode.INVALID_ARGUMENT, m, { cause })`.
+ *
+ * @typedef {{ hint?: string }} AssertOptions
+ *   `hint` is appended to the message after an em-dash — use it for
+ *   actionable guidance ("pass the exact bytes returned by …").
+ *
+ * @typedef {{ safeParse: (input: unknown, path?: string) => { ok: true, value: unknown } | { ok: false, errors: string[] } }} ParseableSchema
+ */
+
+/**
+ * Build the failure message. `description` completes the sentence
+ * `"<name> must be <description>"`; `hint` (optional) follows an
+ * em-dash.
+ *
+ * @param {string} name
+ * @param {string} description
+ * @param {string} [hint]
+ * @returns {string}
+ */
+function message(name, description, hint) {
+  return `${name} must be ${description}${hint ? ` — ${hint}` : ''}`;
+}
+
+const ENCODINGS = new Set(['hex', 'base64', 'base64url']);
+
+/**
+ * Bind the assert set to a package's error class. Call once per
+ * package (conventionally in `internal/guards.js`) and import the
+ * bound object everywhere:
+ *
+ *   import { bindAsserts } from '@exortek/shared/asserts';
+ *   import { CryptoError, ErrorCode } from '../errors.js';
+ *   export const g = bindAsserts((m) => new CryptoError(ErrorCode.INVALID_ARGUMENT, m));
+ *
+ *   // call sites:
+ *   g.assertPositiveInt(options.iterations, 'options.iterations');
+ *   const cfg = g.parse(OptionsSchema, options, 'options');
+ *
+ * @param {WrapFn} wrap
+ */
+function bindAsserts(wrap) {
+  /**
+   * @param {string} name
+   * @param {string} description
+   * @param {AssertOptions} [opts]
+   * @returns {never}
+   */
+  function fail(name, description, opts) {
+    throw wrap(message(name, description, opts?.hint));
+  }
+
+  /**
+   * Assert that `value` is a plain object (not `null`, not an array,
+   * not a primitive).
+   * @param {unknown} value
+   * @param {string}  name
+   * @param {AssertOptions} [opts]
+   */
+  function assertObject(value, name, opts) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      fail(name, 'an object', opts);
+    }
+  }
+
+  return {
+    /**
+     * Construct (not throw) the bound error with a free-form message —
+     * for `throw g.invalidArgument('…')` sites that don't fit the
+     * `X must be Y` shape (canonicalisation errors, cross-field
+     * constraint failures). Pass `{ cause }` when the argument-shape
+     * failure was triggered by an underlying throw whose chain matters
+     * (e.g. `JSON.stringify` on a bigint).
+     *
+     * @param {string} msg
+     * @param {WrapExtra} [extra]
+     * @returns {Error}
+     */
+    invalidArgument(msg, extra) {
+      return wrap(msg, extra);
+    },
+
+    /**
+     * Validate `input` against a `@exortek/shared/validate` schema;
+     * failures throw the bound error carrying every collected message.
+     * The bridge that keeps schema validation on the package's own
+     * error surface.
+     *
+     * @param {ParseableSchema} schema
+     * @param {unknown} input
+     * @param {string} [path='options']
+     * @returns {unknown} the parsed (possibly defaulted) value
+     */
+    parse(schema, input, path = 'options') {
+      const r = schema.safeParse(input, path);
+      if (!r.ok) {
+        throw wrap(r.errors.join('; '));
+      }
+      return r.value;
+    },
+
+    /**
+     * Assert that `value` is a non-negative safe integer (`0, 1, 2, …`).
+     * @param {unknown} value
+     * @param {string}  name  Argument name to include in the error message.
+     * @param {AssertOptions} [opts]
+     */
+    assertNonNegativeInt(value, name, opts) {
+      if (!Number.isSafeInteger(value) || /** @type {number} */ (value) < 0) {
+        fail(name, 'a non-negative safe integer', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` is a strictly positive safe integer (`1, 2, 3, …`).
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertPositiveInt(value, name, opts) {
+      if (!Number.isSafeInteger(value) || /** @type {number} */ (value) <= 0) {
+        fail(name, 'a positive integer', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` fits in a 48-bit unsigned integer (`0 … 2^48 − 1`).
+     * Used for Unix millisecond timestamps in UUID v7 / ULID.
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertUint48(value, name, opts) {
+      if (
+        !Number.isSafeInteger(value) ||
+        /** @type {number} */ (value) < 0 ||
+        /** @type {number} */ (value) > 0xffffffffffff
+      ) {
+        fail(name, 'a non-negative safe integer ≤ 2^48 − 1 (Unix ms since epoch)', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` is a string (may be empty).
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertString(value, name, opts) {
+      if (typeof value !== 'string') {
+        fail(name, 'a string', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` is a non-empty string.
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertNonEmptyString(value, name, opts) {
+      if (typeof value !== 'string' || value.length === 0) {
+        fail(name, 'a non-empty string', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` is a boolean.
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertBoolean(value, name, opts) {
+      if (typeof value !== 'boolean') {
+        fail(name, 'a boolean', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` is a function.
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertFunction(value, name, opts) {
+      if (typeof value !== 'function') {
+        fail(name, 'a function', opts);
+      }
+    },
+
+    assertObject,
+
+    /**
+     * Assert that `value` is either `undefined` or a plain object —
+     * the "optional options object" pattern.
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertOptionalObject(value, name, opts) {
+      if (value === undefined) {
+        return;
+      }
+      assertObject(value, name, opts);
+    },
+
+    /**
+     * Assert that `value` is a byte buffer (`Buffer` or `Uint8Array`) —
+     * strings are NOT accepted. For already-encoded material where a
+     * string would be ambiguous (ciphertext, signatures, raw key bytes).
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertBytes(value, name, opts) {
+      if (!Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+        fail(name, 'a Buffer or Uint8Array', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` is either a string or a byte buffer (`Buffer`
+     * or `Uint8Array`).
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertBytesOrString(value, name, opts) {
+      if (typeof value !== 'string' && !Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+        fail(name, 'a string or Buffer', opts);
+      }
+    },
+
+    /**
+     * Assert that `encoding` is one of the accepted output/input
+     * encodings. Pass `allowBuffer: false` where a `Buffer` output makes
+     * no sense (verifying a string signature, decoding a token payload).
+     *
+     * @param {unknown} encoding
+     * @param {string}  name
+     * @param {AssertOptions & { allowBuffer?: boolean }} [opts]
+     */
+    assertEncoding(encoding, name, opts) {
+      const allowBuffer = opts?.allowBuffer !== false;
+      const valid = (typeof encoding === 'string' && ENCODINGS.has(encoding)) || (allowBuffer && encoding === 'buffer');
+      if (!valid) {
+        const list = allowBuffer ? "'hex', 'base64', 'base64url', or 'buffer'" : "'hex', 'base64', or 'base64url'";
+        fail(name, list, opts);
+      }
+    },
+  };
+}
+
+/**
+ * One-line sugar over {@link bindAsserts} — the overwhelmingly common
+ * pattern where a package binds every argument-shape failure to its
+ * own error class + `INVALID_ARGUMENT` code. Emits the standard
+ * `new ErrorClass(code, message, { cause })` shape, so the underlying
+ * `BaseError` `{ cause, status, details }` options object is respected.
+ *
+ *   // packages/<pkg>/src/internal/guards.js
+ *   import { defineGuards } from '@exortek/shared/asserts';
+ *   import { PasswordError, ErrorCode } from '../errors.js';
+ *
+ *   export const { assertString, invalidArgument, parse } =
+ *     defineGuards(PasswordError, ErrorCode.INVALID_ARGUMENT);
+ *
+ * Reach for the raw {@link bindAsserts} when you need a different
+ * mapping (an alt code, a decorated message) — it stays available.
+ *
+ * @param {new (code: string, message: string, options?: { cause?: unknown }) => Error} ErrorClass
+ * @param {string} code
+ */
+function defineGuards(ErrorClass, code) {
+  return bindAsserts((message, extra) => new ErrorClass(code, message, extra));
+}
+
+/**
+ * Shared base error class — the single error structure behind every
+ * `@exortek/*` package's `errors.js`.
+ *
+ * Every package keeps its own class identity with a one-liner subclass;
+ * codes stay per-package frozen maps, status mapping is declared as a
+ * static field:
+ *
+ *   import { BaseError } from '@exortek/shared/errors';
+ *
+ *   export const ErrorCode = Object.freeze({
+ *     INVALID_ARGUMENT: 'INVALID_ARGUMENT',
+ *     INVALID_TOKEN: 'INVALID_TOKEN',
+ *   });
+ *
+ *   export class JwtError extends BaseError {
+ *     static statuses = { INVALID_ARGUMENT: 400, INVALID_TOKEN: 401 };
+ *     static defaultStatus = 500;
+ *   }
+ *
+ * Instances carry a stable machine-readable `code` (branch on this,
+ * never on the message), an optional HTTP `status`, an optional
+ * `details` object, and the standard `cause` chain.
+ */
+class BaseError extends Error {
+  /**
+   * Optional `code → HTTP status` map declared on the subclass. When
+   * absent the instance carries no `status` at all — for HTTP-agnostic
+   * packages like `@exortek/crypto`.
+   *
+   * @type {Record<string, number> | undefined}
+   */
+  static statuses = undefined;
+
+  /**
+   * Fallback status for codes missing from `statuses`.
+   *
+   * @type {number}
+   */
+  static defaultStatus = 500;
+
+  /**
+   * @param {string} code    Stable machine-readable code; branch on this.
+   * @param {string} message Human-readable diagnostic. Free-form; may
+   *                         change across versions.
+   * @param {{ cause?: unknown, status?: number, details?: Record<string, unknown> }} [options]
+   */
+  constructor(code, message, options = {}) {
+    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+    this.name = new.target.name;
+    /** @type {string} */
+    this.code = code;
+    const statuses = /** @type {typeof BaseError} */ (new.target).statuses;
+    if (options.status !== undefined) {
+      /** @type {number | undefined} */
+      this.status = options.status;
+    } else if (statuses !== undefined) {
+      // Object.hasOwn guards against inherited-property lookups for
+      // exotic code values ('toString', 'constructor', …).
+      this.status = Object.hasOwn(statuses, code)
+        ? statuses[code]
+        : /** @type {typeof BaseError} */ (new.target).defaultStatus;
+    }
+    if (options.details) {
+      /** @type {Record<string, unknown> | undefined} */
+      this.details = options.details;
+    }
+  }
+}
+
+/**
+ * Stable machine-readable codes for every programmer-error failure that
+ * `@exortek/apikey` can raise. Branch on `code`, never on the message.
+ * Note: expected verify failures (bad secret, expired, revoked,
+ * missing scope) are NOT thrown — `verifyApiKey` returns
+ * `{ valid: false, reason }` so a wrong or stale key is a normal auth
+ * outcome, not an exception. Errors below fire only when the caller
+ * configured something wrong or the store misbehaved.
+ */
+
+const ErrorCode = Object.freeze({
+  INVALID_ARGUMENT: 'INVALID_ARGUMENT',
+  INVALID_PREFIX: 'INVALID_PREFIX',
+  INVALID_PEPPER: 'INVALID_PEPPER',
+  STORE_ERROR: 'STORE_ERROR',
+});
+
+/**
+ * Every recoverable failure raised by this package. Carries a stable
+ * `code` (from {@link ErrorCode}) and a `status` — the HTTP response
+ * status a middleware layer would use when translating the error.
+ */
+class ApiKeyError extends BaseError {
+  static statuses = {
+    [ErrorCode.INVALID_ARGUMENT]: 400,
+    [ErrorCode.INVALID_PREFIX]: 400,
+    [ErrorCode.INVALID_PEPPER]: 400,
+    [ErrorCode.STORE_ERROR]: 500,
+  };
+  static defaultStatus = 500;
+}
+
+/**
+ * Argument guards bound to `ApiKeyError` — the package-wide binding of
+ * `@exortek/shared/asserts`. Import guards from here, never from the
+ * shared module directly.
+ */
+
+
+const { invalidArgument} = defineGuards(
+  ApiKeyError,
+  ErrorCode.INVALID_ARGUMENT,
+);
+
+/**
+ * In-process memory store for API keys.
+ *
+ * Not cluster-safe — every worker has its own state. Use for dev,
+ * single-node deployments, and tests. For multi-worker production use
+ * {@link redisStore} or bring your own DB-backed implementation of
+ * `ApiKeyStore`.
+ *
+ * Backed by two Maps: one keyed by `id` (the primary lookup path),
+ * one keyed by `userId` holding a `Set<id>` reverse index for
+ * `listByUser` / `revokeAllForUser`. Both are pruned on write.
+ */
+
+
+/**
+ * @returns {import('../index.js').ApiKeyStore & { _size: () => number }}
+ */
+function memoryStore() {
+  /** @type {Map<string, import('../index.js').ApiKeyRecord>} */
+  const byId = new Map();
+  /** @type {Map<string, Set<string>>} */
+  const byUser = new Map();
+
+  function indexUser(uid, id) {
+    if (!isString(uid)) {
+      return;
+    }
+    let set = byUser.get(uid);
+    if (!set) {
+      set = new Set();
+      byUser.set(uid, set);
+    }
+    set.add(id);
+  }
+
+  function unindexUser(uid, id) {
+    if (!isString(uid)) {
+      return;
+    }
+    const set = byUser.get(uid);
+    if (!set) {
+      return;
+    }
+    set.delete(id);
+    if (set.size === 0) {
+      byUser.delete(uid);
+    }
+  }
+
+  return {
+    async put(record) {
+      if (!isObject(record) || !isString(record.id)) {
+        throw invalidArgument('memoryStore.put.record.id must be a string');
+      }
+      // Store a shallow copy so a caller mutating the record they
+      // passed in doesn't retroactively mutate what we've stored —
+      // matches the copy-on-read contract of getById / update.
+      byId.set(record.id, { ...record });
+      indexUser(record.userId, record.id);
+    },
+
+    async getById(id) {
+      const record = byId.get(id);
+      return record ? { ...record } : null;
+    },
+
+    async update(id, patch) {
+      const existing = byId.get(id);
+      if (!existing) {
+        return null;
+      }
+      const oldUserId = existing.userId;
+      const next = { ...existing, ...patch };
+      byId.set(id, next);
+      if (!isUndefined(patch.userId) && patch.userId !== oldUserId) {
+        unindexUser(oldUserId, id);
+        indexUser(next.userId, id);
+      }
+      return { ...next };
+    },
+
+    async revoke(id, reason) {
+      const existing = byId.get(id);
+      if (!existing || existing.revokedAt) {
+        return false;
+      }
+      existing.revokedAt = Date.now();
+      if (isString(reason)) {
+        existing.revokedReason = reason;
+      }
+      return true;
+    },
+
+    async revokeAllForUser(userId, reason) {
+      const set = byUser.get(userId);
+      if (!set) {
+        return 0;
+      }
+      const now = Date.now();
+      let count = 0;
+      for (const id of set) {
+        const record = byId.get(id);
+        if (record && !record.revokedAt) {
+          record.revokedAt = now;
+          if (isString(reason)) {
+            record.revokedReason = reason;
+          }
+          count += 1;
+        }
+      }
+      return count;
+    },
+
+    async listByUser(userId) {
+      const set = byUser.get(userId);
+      if (!set) {
+        return [];
+      }
+      const out = [];
+      for (const id of set) {
+        const record = byId.get(id);
+        if (record) {
+          out.push({ ...record });
+        }
+      }
+      return out;
+    },
+
+    _size: () => byId.size,
+  };
+}
+
+/**
+ * Duck-type guard for a Redis-compatible client. Every `@exortek/*`
+ * package that ships a Redis store (jwt blacklist, session store,
+ * security rate-limit) does the same "not null + required methods
+ * are functions" check up front so a missing dependency surfaces as
+ * a clean typed error instead of `TypeError: client.get is not a
+ * function` deep in a store operation.
+ *
+ * Callers pass their own `wrap` callback that throws their typed
+ * error class with the message — this file has no opinion on the
+ * error surface.
+ */
+
+/**
+ * @param {unknown} client
+ * @param {readonly string[]} methods  Method names that must be functions on the client.
+ * @param {(message: string) => never} wrap
+ *   Called with a diagnostic message when the check fails; must throw.
+ *   The caller's typed error class is emitted from inside this callback.
+ * @returns {void}
+ */
+function assertRedisClient(client, methods, wrap) {
+  if (!client || typeof client !== 'object') {
+    wrap('client is required — pass a Redis-compatible instance (ioredis / node-redis / @upstash/redis)');
+  }
+  const c = /** @type {Record<string, unknown>} */ (client);
+  for (const method of methods) {
+    if (typeof c[method] !== 'function') {
+      wrap(`client is missing '${method}()' — is this a Redis-compatible client?`);
+    }
+  }
+}
+
+/**
+ * Redis-backed store for API keys.
+ *
+ * Layout:
+ *
+ *   <keyPrefix><id>            — JSON blob of the record (primary lookup)
+ *   <keyPrefix>u:<userId>      — SADD-set of the user's key ids
+ *
+ * Cluster-safe: state lives in Redis, so a key put on one worker is
+ * immediately visible to every other. Works with any client exposing
+ * `get / set / del / sadd / srem / smembers / mget` — verified against
+ * `ioredis`, `node-redis@4+`, and `@upstash/redis`.
+ *
+ * There is no TTL on the record — API keys are meant to be long-lived
+ * and their `expiresAt` field is authoritative. Revocation is a
+ * flip-in-place on the record itself, not a tombstone, since
+ * `verifyApiKey` re-reads the full record every time.
+ */
+
+
+/**
+ * @typedef {object} RedisStoreOptions
+ * @property {string} [keyPrefix='apikey:']
+ */
+
+/**
+ * @param {any} client
+ * @param {RedisStoreOptions} [options]
+ * @returns {import('../index.js').ApiKeyStore}
+ */
+function redisStore(client, options = {}) {
+  assertRedisClient(client, ['get', 'set', 'del'], msg => {
+    throw invalidArgument(`redisStore.client: ${msg}`);
+  });
+  const keyPrefix = options.keyPrefix ?? 'apikey:';
+  const rk = id => `${keyPrefix}${id}`;
+  const uk = uid => `${keyPrefix}u:${uid}`;
+
+  async function readRecord(id) {
+    const raw = await client.get(rk(id));
+    if (!raw) {
+      return null;
+    }
+    try {
+      return isString(raw) ? JSON.parse(raw) : raw;
+    } catch {
+      return null;
+    }
+  }
+
+  async function writeRecord(record) {
+    await client.set(rk(record.id), JSON.stringify(record));
+  }
+
+  async function sadd(uid, id) {
+    if (isFunction(client.sadd)) {
+      return client.sadd(uk(uid), id);
+    }
+    if (isFunction(client.sAdd)) {
+      return client.sAdd(uk(uid), id);
+    }
+    return null;
+  }
+
+  async function srem(uid, id) {
+    if (isFunction(client.srem)) {
+      return client.srem(uk(uid), id);
+    }
+    if (isFunction(client.sRem)) {
+      return client.sRem(uk(uid), id);
+    }
+    return null;
+  }
+
+  async function smembers(uid) {
+    if (isFunction(client.smembers)) {
+      return client.smembers(uk(uid));
+    }
+    if (isFunction(client.sMembers)) {
+      return client.sMembers(uk(uid));
+    }
+    return [];
+  }
+
+  async function mget(keys) {
+    if (keys.length === 0) {
+      return [];
+    }
+    if (isFunction(client.mget)) {
+      return client.mget(...keys);
+    }
+    if (isFunction(client.mGet)) {
+      return client.mGet(keys);
+    }
+    return Promise.all(keys.map(k => client.get(k)));
+  }
+
+  return {
+    async put(record) {
+      if (!isObject(record) || !isString(record.id)) {
+        throw invalidArgument('redisStore.put.record.id must be a string');
+      }
+      await writeRecord(record);
+      if (record.userId) {
+        await sadd(record.userId, record.id);
+      }
+    },
+
+    async getById(id) {
+      return readRecord(id);
+    },
+
+    async update(id, patch) {
+      const existing = await readRecord(id);
+      if (!existing) {
+        return null;
+      }
+      const oldUserId = existing.userId;
+      const next = { ...existing, ...patch };
+      await writeRecord(next);
+      if (patch.userId !== undefined && patch.userId !== oldUserId) {
+        if (oldUserId) {
+          await srem(oldUserId, id);
+        }
+        if (next.userId) {
+          await sadd(next.userId, id);
+        }
+      }
+      return next;
+    },
+
+    async revoke(id, reason) {
+      const existing = await readRecord(id);
+      if (!existing || existing.revokedAt) {
+        return false;
+      }
+      existing.revokedAt = Date.now();
+      if (isString(reason)) {
+        existing.revokedReason = reason;
+      }
+      await writeRecord(existing);
+      return true;
+    },
+
+    async revokeAllForUser(userId, reason) {
+      const ids = await smembers(userId);
+      if (!ids || ids.length === 0) {
+        return 0;
+      }
+      const rows = await mget(ids.map(rk));
+      let count = 0;
+      const writes = [];
+      for (let i = 0; i < ids.length; i++) {
+        const raw = rows[i];
+        if (!raw) {
+          continue;
+        }
+        let record;
+        try {
+          record = isString(raw) ? JSON.parse(raw) : raw;
+        } catch {
+          continue;
+        }
+        if (record.revokedAt) {
+          continue;
+        }
+        record.revokedAt = Date.now();
+        if (isString(reason)) {
+          record.revokedReason = reason;
+        }
+        writes.push(writeRecord(record));
+        count += 1;
+      }
+      await Promise.all(writes);
+      return count;
+    },
+
+    async listByUser(userId) {
+      const ids = await smembers(userId);
+      if (!ids || ids.length === 0) {
+        return [];
+      }
+      const rows = await mget(ids.map(rk));
+      const out = [];
+      for (let i = 0; i < ids.length; i++) {
+        const raw = rows[i];
+        if (!raw) {
+          // Dead index reference — prune.
+          await srem(userId, ids[i]);
+          continue;
+        }
+        try {
+          out.push(isString(raw) ? JSON.parse(raw) : raw);
+        } catch {
+          // Skip corrupt row.
+        }
+      }
+      return out;
+    },
+  };
+}
+
+exports.memoryStore = memoryStore;
+exports.redisStore = redisStore;