@exortek/apikey 1.0.0 → 1.0.1

package/dist/stores.cjs

@@ -25,27 +25,6 @@
  * 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
@@ -82,6 +61,503 @@ function isUndefined(value) {
   return typeof value === 'undefined';
 }
 
+/**
+ * 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 client-shape compatibility helpers.
+ *
+ * ioredis, node-redis v4+, and @upstash/redis all expose the same
+ * operations under slightly different names and calling conventions.
+ * This module creates a normalised adapter so every store in the repo
+ * can share a single detection path instead of copy-pasting the same
+ * three-way dispatch.
+ *
+ * Internal to `@exortek/shared` — consumed by `incr-store.js` and
+ * `record-store.js`, not re-exported to consuming packages.
+ */
+
+
+/**
+ * @param {object} client  A Redis-compatible client instance.
+ * @returns {{
+ *   mget: (keys: string[]) => Promise<(string|null)[]>,
+ *   sadd: (key: string, member: string) => Promise<any>,
+ *   srem: (key: string, member: string) => Promise<any>,
+ *   smembers: (key: string) => Promise<string[]>,
+ *   setWithTTL: (key: string, value: string, ttlMs: number) => Promise<void>,
+ *   setPlain: (key: string, value: string) => Promise<void>,
+ *   parseRecord: (raw: string|object|null) => object|null,
+ * }}
+ */
+function createRedisHelpers(client) {
+  return {
+    async 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)));
+    },
+
+    async sadd(key, member) {
+      if (isFunction(client.sadd)) {
+        return client.sadd(key, member);
+      }
+      if (isFunction(client.sAdd)) {
+        return client.sAdd(key, member);
+      }
+      return null;
+    },
+
+    async srem(key, member) {
+      if (isFunction(client.srem)) {
+        return client.srem(key, member);
+      }
+      if (isFunction(client.sRem)) {
+        return client.sRem(key, member);
+      }
+      return null;
+    },
+
+    async smembers(key) {
+      if (isFunction(client.smembers)) {
+        return client.smembers(key);
+      }
+      if (isFunction(client.sMembers)) {
+        return client.sMembers(key);
+      }
+      return [];
+    },
+
+    async setWithTTL(key, value, ttlMs) {
+      const px = Math.max(1, Math.ceil(ttlMs));
+      try {
+        await client.set(key, value, 'PX', px);
+      } catch {
+        await client.set(key, value, { PX: px });
+      }
+    },
+
+    async setPlain(key, value) {
+      await client.set(key, value);
+    },
+
+    parseRecord(raw) {
+      if (!raw) {
+        return null;
+      }
+      try {
+        return isString(raw) ? JSON.parse(raw) : raw;
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Shared indexed record store — primary key + secondary owner-index.
+ *
+ * Memory and Redis factories for the CRUD + index pattern used by
+ * `@exortek/apikey`, `@exortek/magic-link`, and `@exortek/session`.
+ *
+ * Each consuming package wraps these factories and adds its own
+ * domain-specific methods (revoke, consume, etc.). The factories
+ * provide the common put/get/update/list + index management.
+ */
+
+
+// Memory
+
+/**
+ * @typedef {object} MemoryRecordStoreConfig
+ * @property {string} idField         Primary key field name ('id' | 'sid').
+ * @property {string} indexField      Secondary index field name ('userId' | 'email' | 'uid').
+ * @property {'shallow' | 'deep' | 'none'} [copyStrategy='shallow']
+ */
+
+/**
+ * @param {MemoryRecordStoreConfig} config
+ * @returns {{
+ *   put: (record: object) => Promise<void>,
+ *   getById: (id: string) => Promise<object|null>,
+ *   update: (id: string, patch: object) => Promise<object|null>,
+ *   listByIndex: (indexValue: string) => Promise<object[]>,
+ *   byId: Map<string, object>,
+ *   byIndex: Map<string, Set<string>>,
+ *   _size: () => number,
+ * }}
+ */
+function createMemoryRecordStore(config) {
+  const { idField, indexField, copyStrategy = 'shallow' } = config;
+
+  /** @type {Map<string, object>} */
+  const byId = new Map();
+  /** @type {Map<string, Set<string>>} */
+  const byIndex = new Map();
+
+  function copy(record) {
+    if (copyStrategy === 'deep') {
+      return structuredClone(record);
+    }
+    if (copyStrategy === 'shallow') {
+      return { ...record };
+    }
+    return record;
+  }
+
+  function addIndex(indexValue, id) {
+    if (!isString(indexValue)) {
+      return;
+    }
+    let set = byIndex.get(indexValue);
+    if (!set) {
+      set = new Set();
+      byIndex.set(indexValue, set);
+    }
+    set.add(id);
+  }
+
+  function removeIndex(indexValue, id) {
+    if (!isString(indexValue)) {
+      return;
+    }
+    const set = byIndex.get(indexValue);
+    if (!set) {
+      return;
+    }
+    set.delete(id);
+    if (set.size === 0) {
+      byIndex.delete(indexValue);
+    }
+  }
+
+  return {
+    byId,
+    byIndex,
+
+    async put(record) {
+      byId.set(record[idField], copy(record));
+      addIndex(record[indexField], record[idField]);
+    },
+
+    async getById(id) {
+      const record = byId.get(id);
+      return record ? copy(record) : null;
+    },
+
+    async update(id, patch) {
+      const existing = byId.get(id);
+      if (!existing) {
+        return null;
+      }
+      const oldIndex = existing[indexField];
+      const next = { ...existing, ...patch };
+      byId.set(id, next);
+      if (!isUndefined(patch[indexField]) && patch[indexField] !== oldIndex) {
+        removeIndex(oldIndex, id);
+        addIndex(next[indexField], id);
+      }
+      return copy(next);
+    },
+
+    async listByIndex(indexValue) {
+      const set = byIndex.get(indexValue);
+      if (!set) {
+        return [];
+      }
+      const out = [];
+      for (const id of set) {
+        const record = byId.get(id);
+        if (record) {
+          out.push(copy(record));
+        }
+      }
+      return out;
+    },
+
+    _size: () => byId.size,
+  };
+}
+
+// Redis
+
+/**
+ * @typedef {object} RedisRecordStoreConfig
+ * @property {string} idField            Primary key field name.
+ * @property {string} indexField         Secondary index field name.
+ * @property {string} [keyPrefix='']
+ * @property {boolean} [tombstones=false]
+ * @property {string} [tombstonePrefix='rev:']
+ * @property {string} [indexPrefix='u:']
+ * @property {boolean} [ttl=false]       Whether records have TTL.
+ * @property {(record: object, parsedTomb: object) => object} [applyTombstone]
+ *   Required when `tombstones: true`. Receives the parsed record and
+ *   the parsed tombstone — must mutate and return the record.
+ * @property {(msg: string) => never} [wrap]
+ */
+
+/**
+ * @param {object} client
+ * @param {RedisRecordStoreConfig} config
+ * @returns {{
+ *   put: (record: object, ttlMs?: number) => Promise<void>,
+ *   getById: (id: string) => Promise<object|null>,
+ *   update: (id: string, patch: object, ttlMs?: number) => Promise<object|null>,
+ *   listByIndex: (indexValue: string) => Promise<object[]>,
+ *   readRecord: (id: string) => Promise<object|null>,
+ *   writeRecord: (record: object, ttlMs?: number) => Promise<void>,
+ *   writeTombstone: (id: string, data: object, ttlMs?: number) => Promise<void>,
+ *   fetchIndexRecords: (indexValue: string) => Promise<[string, object|null][]>,
+ *   indexAdd: (indexValue: string, id: string) => Promise<void>,
+ *   indexRemove: (indexValue: string, id: string) => Promise<void>,
+ *   helpers: ReturnType<typeof createRedisHelpers>,
+ * }}
+ */
+function createRedisRecordStore(client, config) {
+  const wrap = config.wrap ?? (msg => { throw new TypeError(msg); });
+  assertRedisClient(client, ['get', 'set', 'del'], wrap);
+
+  const {
+    idField,
+    indexField,
+    keyPrefix = '',
+    tombstones = false,
+    tombstonePrefix = 'rev:',
+    indexPrefix = 'u:',
+    ttl = false,
+    applyTombstone,
+  } = config;
+
+  const helpers = createRedisHelpers(client);
+
+  const rk = id => `${keyPrefix}${id}`;
+  const revk = id => `${keyPrefix}${tombstonePrefix}${id}`;
+  const ik = indexValue => `${keyPrefix}${indexPrefix}${indexValue}`;
+
+  function overlayTombstone(record, rawTomb) {
+    if (!record || !rawTomb || !applyTombstone) {
+      return record;
+    }
+    const tomb = helpers.parseRecord(rawTomb);
+    if (!tomb) {
+      return record;
+    }
+    return applyTombstone(record, tomb);
+  }
+
+  async function readRecord(id) {
+    if (tombstones) {
+      const [rawRecord, rawTomb] = await helpers.mget([rk(id), revk(id)]);
+      const record = helpers.parseRecord(rawRecord);
+      return record ? overlayTombstone(record, rawTomb) : null;
+    }
+    return helpers.parseRecord(await client.get(rk(id)));
+  }
+
+  async function writeRecord(record, ttlMs) {
+    const value = JSON.stringify(record);
+    if (ttl && ttlMs !== undefined) {
+      await helpers.setWithTTL(rk(record[idField]), value, ttlMs);
+    } else {
+      await helpers.setPlain(rk(record[idField]), value);
+    }
+  }
+
+  async function writeTombstone(id, data, ttlMs) {
+    const value = JSON.stringify(data);
+    if (ttl && ttlMs !== undefined) {
+      await helpers.setWithTTL(revk(id), value, ttlMs);
+    } else {
+      await helpers.setPlain(revk(id), value);
+    }
+  }
+
+  async function indexAdd(indexValue, id) {
+    await helpers.sadd(ik(indexValue), id);
+  }
+
+  async function indexRemove(indexValue, id) {
+    await helpers.srem(ik(indexValue), id);
+  }
+
+  async function fetchIndexRecords(indexValue) {
+    const ids = await helpers.smembers(ik(indexValue));
+    if (!ids || ids.length === 0) {
+      return [];
+    }
+    const keys = [];
+    for (const id of ids) {
+      keys.push(rk(id));
+      if (tombstones) {
+        keys.push(revk(id));
+      }
+    }
+    const rows = await helpers.mget(keys);
+    const stride = tombstones ? 2 : 1;
+    const pairs = [];
+    for (let i = 0; i < ids.length; i++) {
+      const raw = rows[i * stride];
+      const rawTomb = tombstones ? rows[i * stride + 1] : null;
+      const record = helpers.parseRecord(raw);
+      if (!record) {
+        await indexRemove(indexValue, ids[i]);
+        pairs.push([ids[i], null]);
+        continue;
+      }
+      pairs.push([ids[i], overlayTombstone(record, rawTomb)]);
+    }
+    return pairs;
+  }
+
+  return {
+    async put(record, ttlMs) {
+      await writeRecord(record, ttlMs);
+      if (isString(record[indexField])) {
+        await indexAdd(record[indexField], record[idField]);
+      }
+    },
+
+    async getById(id) {
+      return readRecord(id);
+    },
+
+    async update(id, patch, ttlMs) {
+      const existing = await readRecord(id);
+      if (!existing) {
+        return null;
+      }
+      const oldIndex = existing[indexField];
+      const next = { ...existing, ...patch };
+      await writeRecord(next, ttlMs);
+      if (!isUndefined(patch[indexField]) && patch[indexField] !== oldIndex) {
+        if (isString(oldIndex)) {
+          await indexRemove(oldIndex, id);
+        }
+        if (isString(next[indexField])) {
+          await indexAdd(next[indexField], id);
+        }
+      }
+      return next;
+    },
+
+    async listByIndex(indexValue) {
+      const pairs = await fetchIndexRecords(indexValue);
+      return pairs.filter(([, r]) => r !== null).map(([, r]) => r);
+    },
+
+    readRecord,
+    writeRecord,
+    writeTombstone,
+    fetchIndexRecords,
+    indexAdd,
+    indexRemove,
+    helpers,
+  };
+}
+
+/**
+ * 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() {
+  const store = createMemoryRecordStore({
+    idField: 'id',
+    indexField: 'userId',
+    copyStrategy: 'shallow',
+  });
+
+  return {
+    put: record => store.put(record),
+    getById: id => store.getById(id),
+    update: (id, patch) => store.update(id, patch),
+    listByUser: userId => store.listByIndex(userId),
+
+    async revoke(id, reason) {
+      const existing = store.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 = store.byIndex.get(userId);
+      if (!set) {
+        return 0;
+      }
+      const now = Date.now();
+      let count = 0;
+      for (const id of set) {
+        const record = store.byId.get(id);
+        if (record && !record.revokedAt) {
+          record.revokedAt = now;
+          if (isString(reason)) {
+            record.revokedReason = reason;
+          }
+          count += 1;
+        }
+      }
+      return count;
+    },
+
+    _size: () => store._size(),
+  };
+}
+
 /**
  * Imperative single-argument guard helpers — the everyday
  * `assertPositiveInt(x, 'name')` shape used at API boundaries.
@@ -509,177 +985,13 @@ const { invalidArgument} = defineGuards(
   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>rev:<id>        — revocation tombstone (see below)
  *   <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
@@ -688,9 +1000,15 @@ function assertRedisClient(client, methods, wrap) {
  * `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.
+ * and their `expiresAt` field is authoritative.
+ *
+ * **Why tombstones:** `update()` is a read-modify-write (GET → SET), so
+ * a concurrent `revoke()` on another worker could be overwritten by an
+ * in-flight update carrying the pre-revoke copy — silently un-revoking
+ * the key. Revocations are therefore written to a separate
+ * `<keyPrefix>rev:<id>` key that no update path ever touches; `getById()`
+ * and `listByUser()` overlay it onto the record. A revocation can never
+ * be lost to a lost-update race.
  */
 
 
@@ -705,174 +1023,64 @@ function assertRedisClient(client, methods, wrap) {
  * @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);
+  const store = createRedisRecordStore(client, {
+    idField: 'id',
+    indexField: 'userId',
+    keyPrefix,
+    tombstones: true,
+    tombstonePrefix: 'rev:',
+    indexPrefix: 'u:',
+    applyTombstone(record, tomb) {
+      record.revokedAt = record.revokedAt ?? Date.now();
+      if (isString(tomb.reason) && record.revokedReason === undefined) {
+        record.revokedReason = tomb.reason;
       }
+      return record;
     },
+    wrap: msg => { throw invalidArgument(msg); },
+  });
 
-    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;
-    },
+  return {
+    put: record => store.put(record),
+    getById: id => store.getById(id),
+    update: (id, patch) => store.update(id, patch),
+    listByUser: userId => store.listByIndex(userId),
 
     async revoke(id, reason) {
-      const existing = await readRecord(id);
+      const existing = await store.readRecord(id);
       if (!existing || existing.revokedAt) {
         return false;
       }
+      await store.writeTombstone(id, { reason: reason ?? null, at: Date.now() });
       existing.revokedAt = Date.now();
       if (isString(reason)) {
         existing.revokedReason = reason;
       }
-      await writeRecord(existing);
+      await store.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));
+      const pairs = await store.fetchIndexRecords(userId);
       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) {
+      for (const [id, record] of pairs) {
+        if (!record || record.revokedAt) {
           continue;
         }
         record.revokedAt = Date.now();
         if (isString(reason)) {
           record.revokedReason = reason;
         }
-        writes.push(writeRecord(record));
+        writes.push(store.writeTombstone(id, { reason: reason ?? null, at: Date.now() }));
+        writes.push(store.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;
-    },
   };
 }