@exortek/apikey 1.1.1 → 1.1.3

package/dist/stores.cjs

@@ -124,11 +124,42 @@ function assertRedisClient(client, methods, wrap) {
  * 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.
+ * Consumed by `incr-store.js` and `record-store.js` here, and imported
+ * directly by the `oauth2`, `opaque` and `session` stores — so treat this
+ * module's surface as shared, not private to `@exortek/shared`.
  */
 
 
+/**
+ * Which calling convention a client expects for the commands whose
+ * signatures differ between drivers — Lua (`eval`) and `SET` with a TTL.
+ *
+ * Most helpers here can dispatch on a method name (`mget` vs `mGet`), but
+ * these two share a name and differ only in how arguments are passed, so
+ * they need an explicit answer.
+ *
+ * A real `ioredis` instance reports `constructor.name === 'EventEmitter'`
+ * — it extends EventEmitter and no class name survives to the instance —
+ * so a constructor-name probe alone never matches it. Detect on the API
+ * surface instead (`scanStream` / the `status` string), neither of which
+ * node-redis has, and keep the name check as a fallback for wrapped
+ * clients. Anything unrecognised is treated as node-redis, whose
+ * options-object form is also what `@upstash/redis` accepts.
+ *
+ * @param {any} client
+ * @returns {'ioredis' | 'node-redis'}
+ */
+function detectDialect(client) {
+  if (client && (isFunction(client.scanStream) || isString(client.status))) {
+    return 'ioredis';
+  }
+  const name = (client && client.constructor && client.constructor.name) || '';
+  if (name === 'Redis' || name === 'Cluster') {
+    return 'ioredis';
+  }
+  return 'node-redis';
+}
+
 /**
  * @param {object} client  A Redis-compatible client instance.
  * @returns {{
@@ -142,7 +173,11 @@ function assertRedisClient(client, methods, wrap) {
  * }}
  */
 function createRedisHelpers(client) {
+  const dialect = detectDialect(client);
+
   return {
+    dialect,
+
     async mget(keys) {
       if (keys.length === 0) {
         return [];
@@ -188,9 +223,13 @@ function createRedisHelpers(client) {
 
     async setWithTTL(key, value, ttlMs) {
       const px = Math.max(1, Math.ceil(ttlMs));
-      try {
+      // Must dispatch on the dialect, not on a try/catch: node-redis accepts
+      // the ioredis positional form without complaint and simply stores the
+      // key with no expiry, so a catch-based fallback never fires and the TTL
+      // is silently dropped.
+      if (dialect === 'ioredis') {
         await client.set(key, value, 'PX', px);
-      } catch {
+      } else {
         await client.set(key, value, { PX: px });
       }
     },
@@ -590,20 +629,33 @@ function memoryStore() {
  * `@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.
+ * Every guard is exported as a `make…` **factory** taking the binding
+ * package's `wrap` and returning the guard itself. A package binds the
+ * guards it calls once, in its `internal/guards.js`, so every argument
+ * failure throws that package's error class — `err instanceof
+ * CryptoError` holds, and users see at a glance which package raised it.
+ *
+ *   // packages/<pkg>/src/internal/guards.js
+ *   import { makeAssertString, makeInvalidArgument } from '@exortek/shared/asserts';
+ *   import { CryptoError, ErrorCode } from '../errors.js';
+ *
+ *   const wrap = (message, extra) => new CryptoError(ErrorCode.INVALID_ARGUMENT, message, extra);
+ *
+ *   export const assertString = makeAssertString(wrap);
+ *   export const invalidArgument = makeInvalidArgument(wrap);
+ *
+ * Importing each factory by name is what makes the module
+ * tree-shakeable. An earlier version handed back one object carrying
+ * every guard, so all of them shipped in every package's bundle no
+ * matter how few were used — `assertBoolean` reached fifteen published
+ * packages without a single call site. Import what you call.
  *
  * **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
+ *   - `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>"`,
@@ -612,289 +664,17 @@ function memoryStore() {
  * 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);
+ * Construct (not throw) the bound error with a free-form message — for
+ * `throw invalidArgument('…')` sites that don't fit the `X must be Y`
+ * shape (canonicalisation errors, cross-field constraint failures). Pass
+ * `{ cause }` when the failure was triggered by an underlying throw whose
+ * chain matters (e.g. `JSON.stringify` on a bigint).
  *
- * 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
+ * @type {(wrap: WrapFn) => (msg: string, extra?: WrapExtra) => Error}
  */
-function defineGuards(ErrorClass, code) {
-  return bindAsserts((message, extra) => new ErrorClass(code, message, extra));
-}
+const makeInvalidArgument = wrap => (msg, extra) => wrap(msg, extra);
 
 /**
  * Shared base error class — the single error structure behind every
@@ -1005,10 +785,15 @@ class ApiKeyError extends BaseError {
  */
 
 
-const { invalidArgument} = defineGuards(
-  ApiKeyError,
-  ErrorCode.INVALID_ARGUMENT,
-);
+/**
+ * Bind every guard this package calls to ApiKeyError, so an argument-shape
+ * failure anywhere carries one class and one code to branch on.
+ *
+ * @type {import('@exortek/shared/asserts').WrapFn}
+ */
+const wrap = (message, extra) => new ApiKeyError(ErrorCode.INVALID_ARGUMENT, message, extra);
+
+const invalidArgument = makeInvalidArgument(wrap);
 
 /**
  * Redis-backed store for API keys.
@@ -1112,39 +897,101 @@ function redisStore(client, options = {}) {
 }
 
 /**
- * Wrap a user-supplied store into the `ApiKeyStore` interface.
- * Validates that the required methods exist so a misconfiguration
- * surfaces at construction time, not on the first `createApiKey` /
- * `verifyApiKey` call. Sync implementations are wrapped transparently
- * — return a plain value or a Promise, either works.
+ * Family factory for the `customStore(impl)` wrapper every store-shipping
+ * package exposes.
  *
- * Required: `put`, `getById`, `update`, `revoke`, `revokeAllForUser`, `listByUser`.
+ * Each package used to hand-roll the same three steps: assert `impl` is an
+ * object, assert its required methods are functions, then `Promise.resolve()`
+ * -wrap every call so a sync implementation is transparently promoted to the
+ * async store interface. Only the method-name arrays and the typed error
+ * differ. This collapses all of that into one binding per package.
  *
- * @param {Partial<import('../index.js').ApiKeyStore>} impl
- * @returns {import('../index.js').ApiKeyStore}
+ * Consumers: `apikey`, `challenge`, `magic-link`, `opaque`, `session`.
  */
 
-const REQUIRED = ['put', 'getById', 'update', 'revoke', 'revokeAllForUser', 'listByUser'];
 
-function customStore(impl) {
+/**
+ * Assert `impl` is an object exposing every method in `required` as a function.
+ * Throws the caller's typed error (via `wrap`) on the first failure. Used on
+ * its own by stores that keep a caller's implementation verbatim (jwt / paseto
+ * token registries), and internally by {@link createCustomStoreValidator}.
+ *
+ * @param {unknown} impl
+ * @param {readonly string[]} required
+ * @param {(message: string) => Error} wrap
+ *   The package's error factory; its returned error is thrown. A `wrap` that
+ *   throws directly also works (the outer `throw` is then unreachable).
+ * @returns {void}
+ */
+function assertStoreShape(impl, required, wrap) {
   if (!isObject(impl)) {
-    throw invalidArgument(`customStore(impl) requires an object with { ${REQUIRED.join(', ')} } methods`);
+    throw wrap(`customStore(impl) requires an object with { ${required.join(', ')} } methods`);
   }
-  for (const name of REQUIRED) {
-    if (!isFunction(impl[name])) {
-      throw invalidArgument(`customStore: impl.${name} is required and must be a function`);
+  for (const name of required) {
+    if (!isFunction(/** @type {any} */ (impl)[name])) {
+      throw wrap(`customStore: impl.${name} is required and must be a function`);
     }
   }
-  return {
-    put: record => Promise.resolve(impl.put(record)),
-    getById: id => Promise.resolve(impl.getById(id)),
-    update: (id, patch) => Promise.resolve(impl.update(id, patch)),
-    revoke: (id, reason) => Promise.resolve(impl.revoke(id, reason)),
-    revokeAllForUser: (userId, reason) => Promise.resolve(impl.revokeAllForUser(userId, reason)),
-    listByUser: userId => Promise.resolve(impl.listByUser(userId)),
+}
+
+/**
+ * @param {object} spec
+ * @param {readonly string[]} spec.required
+ *   Methods that must exist on `impl`; missing ones fail at construction time.
+ * @param {readonly string[]} [spec.optional]
+ *   Methods wrapped through only when present (feature-gated store extras).
+ * @param {(message: string) => Error} spec.wrap
+ *   The package's error factory (its `invalidArgument`) — called with a
+ *   diagnostic message; its returned typed error is thrown so
+ *   `err instanceof <Pkg>Error` holds. A `wrap` that throws directly also
+ *   works (the outer `throw` is then unreachable).
+ * @param {Record<string, (result: any) => any>} [spec.coerce]
+ *   Optional per-method post-processor applied to the resolved result — e.g.
+ *   opaque coerces `set` to `undefined` so a native `Map.set` return value
+ *   can't leak out as `Promise<Map>`.
+ * @returns {(impl: object) => Record<string, (...args: any[]) => Promise<any>>}
+ */
+function createCustomStoreValidator({ required, optional = [], wrap, coerce = {} }) {
+  return function customStore(impl) {
+    assertStoreShape(impl, required, wrap);
+
+    /** @type {Record<string, (...args: any[]) => Promise<any>>} */
+    const store = {};
+    const bind = name => {
+      const post = coerce[name];
+      store[name] = post
+        ? (...args) => Promise.resolve(impl[name](...args)).then(post)
+        : (...args) => Promise.resolve(impl[name](...args));
+    };
+
+    for (const name of required) {
+      bind(name);
+    }
+    for (const name of optional) {
+      if (isFunction(impl[name])) {
+        bind(name);
+      }
+    }
+    return store;
   };
 }
 
+/**
+ * Wrap a user-supplied store into the `ApiKeyStore` interface. Validates the
+ * required methods at construction time (not on first use) and promotes sync
+ * implementations to the async interface.
+ *
+ * Required: `put`, `getById`, `update`, `revoke`, `revokeAllForUser`, `listByUser`.
+ *
+ * @param {Partial<import('../index.js').ApiKeyStore>} impl
+ * @returns {import('../index.js').ApiKeyStore}
+ */
+
+const customStore = createCustomStoreValidator({
+  required: ['put', 'getById', 'update', 'revoke', 'revokeAllForUser', 'listByUser'],
+  wrap: invalidArgument,
+});
+
 exports.customStore = customStore;
 exports.memoryStore = memoryStore;
 exports.redisStore = redisStore;