@exortek/challenge 1.0.0

package/dist/stores.mjs

@@ -0,0 +1,707 @@
+/**
+ * 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 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';
+}
+
+/**
+ * `true` for a safe integer — a finite `number` inside `[MIN_SAFE_INTEGER,
+ * MAX_SAFE_INTEGER]` with no fractional part. Mirrors `Number.isSafeInteger`.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isInteger(value) {
+  return Number.isSafeInteger(value);
+}
+
+/**
+ * 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/challenge` can raise. Branch on `code`, never on the
+ * message. Note: expected verify failures (bad signature, expired,
+ * mismatched claim) are NOT thrown — `verifyChallenge` returns
+ * `{ valid: false, reason }` for those so a wrong or stale token is a
+ * normal auth outcome, not an exception. Errors below fire only when
+ * the caller configured something wrong.
+ */
+
+const ErrorCode = Object.freeze({
+  INVALID_ARGUMENT: 'INVALID_ARGUMENT',
+  INVALID_SECRET: 'INVALID_SECRET',
+});
+
+/**
+ * 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 ChallengeError extends BaseError {
+  static statuses = {
+    [ErrorCode.INVALID_ARGUMENT]: 400,
+    [ErrorCode.INVALID_SECRET]: 400,
+  };
+  static defaultStatus = 500;
+}
+
+/**
+ * Argument guards bound to `ChallengeError` — the package-wide binding
+ * of `@exortek/shared/asserts`. Import guards from here, never from the
+ * shared module directly: every argument-shape failure must throw
+ * `ChallengeError` with `ErrorCode.INVALID_ARGUMENT` so callers get one
+ * error class for the whole package.
+ */
+
+
+const { invalidArgument} = defineGuards(
+  ChallengeError,
+  ErrorCode.INVALID_ARGUMENT,
+);
+
+/**
+ * In-process memory store for challenge single-use enforcement.
+ *
+ * Not cluster-safe: every worker has its own state, so a token accepted
+ * on one worker could still be replayed on another. Use for dev,
+ * single-node deploys, sticky-session behind an LB, and tests. For
+ * multi-worker production, use {@link redisStore} or pass any object
+ * exposing `incr(key, ttlMs) → { count }` (e.g.
+ * `@exortek/security`'s rate-limit stores).
+ *
+ * Eviction: true LRU (least-recently-used). Every `incr` on an existing
+ * key re-inserts it so it becomes the newest entry;
+ * `map.keys().next().value` is then the least-recently-touched key and
+ * is dropped when `maxKeys` is exceeded. This matters for the
+ * replay-guard tombstone: a repeated verify attempt refreshes the
+ * `count > 1` entry so it stays authoritative until its TTL expires.
+ * FIFO would let an idle tombstone age out prematurely and a third
+ * replay attempt could see a fresh counter.
+ *
+ * Textbook pattern, popularised in the JS community by projects like
+ * `toad-cache` (MIT); no code copied, only the same ES2015
+ * iteration-order guarantee.
+ *
+ * Expired entries are pruned lazily on read, plus a `setInterval` sweep
+ * (unref'd so it never blocks process exit). The `maxKeys` cap
+ * protects against unbounded growth if the caller forgets to clean up.
+ */
+
+
+/**
+ * @typedef {object} MemoryStoreOptions
+ * @property {number} [maxKeys=10000]   Hard cap; oldest entry dropped when exceeded.
+ * @property {number} [sweepMs=60000]   Interval for the background TTL sweep.
+ */
+
+/**
+ * @param {MemoryStoreOptions} [options]
+ * @returns {import('./index.js').IncrStore & { _size: () => number, _stop: () => void }}
+ */
+function memoryStore(options = {}) {
+  const maxKeys = options.maxKeys ?? 10_000;
+  const sweepMs = options.sweepMs ?? 60_000;
+
+  if (!isInteger(maxKeys) || maxKeys < 1) {
+    throw invalidArgument(`memoryStore.options.maxKeys must be a positive integer; got ${maxKeys}`);
+  }
+  if (!isInteger(sweepMs) || sweepMs < 1000) {
+    throw invalidArgument(`memoryStore.options.sweepMs must be an integer >= 1000; got ${sweepMs}`);
+  }
+
+  /** @type {Map<string, { count: number, expiresAt: number }>} */
+  const map = new Map();
+  let timer = null;
+
+  function peekFresh(key) {
+    const entry = map.get(key);
+    if (!entry) {
+      return null;
+    }
+    if (entry.expiresAt <= Date.now()) {
+      map.delete(key);
+      return null;
+    }
+    return entry;
+  }
+
+  function sweep() {
+    const t = Date.now();
+    for (const [key, entry] of map) {
+      if (entry.expiresAt <= t) {
+        map.delete(key);
+      }
+    }
+  }
+
+  function scheduleSweeper() {
+    if (timer) {
+      return;
+    }
+    timer = setInterval(sweep, sweepMs);
+    if (isFunction(timer.unref)) {
+      timer.unref();
+    }
+  }
+
+  function evictIfFull() {
+    if (map.size < maxKeys) {
+      return;
+    }
+    const oldest = map.keys().next().value;
+    if (!isUndefined(oldest)) {
+      map.delete(oldest);
+    }
+  }
+
+  return {
+    async incr(key, ttlMs) {
+      scheduleSweeper();
+      const existing = peekFresh(key);
+      if (existing) {
+        existing.count += 1;
+        // Refresh LRU position on activity — the replay-guard tombstone
+        // must stay warm until its TTL fires, or a third replay attempt
+        // could see the entry evicted and get a fresh count.
+        map.delete(key);
+        map.set(key, existing);
+        return { count: existing.count, expiresAt: existing.expiresAt };
+      }
+      evictIfFull();
+      const expiresAt = Date.now() + ttlMs;
+      map.set(key, { count: 1, expiresAt });
+      return { count: 1, expiresAt };
+    },
+
+    _size: () => map.size,
+    _stop: () => {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+  };
+}
+
+/**
+ * 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 challenge single-use enforcement.
+ *
+ * Cluster-safe: state lives in Redis, so a challenge accepted on one
+ * worker cannot be replayed on another. Works with any client exposing
+ * `eval(script, numkeys, ...args)` — verified against `ioredis`,
+ * `node-redis` v4+, and `@upstash/redis` (HTTP client, runs on
+ * Cloudflare Workers / Vercel Edge / Deno Deploy).
+ *
+ * Atomicity: `incr` runs a single Lua script that INCR's the key and
+ * PEXPIRE's it only when the key is fresh (count === 1). The TTL
+ * anchors to the first increment — exactly what single-use enforcement
+ * needs (the tombstone lives as long as the token could still verify,
+ * then rolls off).
+ */
+
+
+const INCR_SCRIPT = `
+local key = KEYS[1]
+local ttl = tonumber(ARGV[1])
+local count = redis.call('INCR', key)
+local pttl
+if count == 1 then
+  redis.call('PEXPIRE', key, ttl)
+  pttl = ttl
+else
+  pttl = redis.call('PTTL', key)
+  if pttl < 0 then
+    redis.call('PEXPIRE', key, ttl)
+    pttl = ttl
+  end
+end
+return { count, pttl }
+`.trim();
+
+/**
+ * @typedef {object} RedisStoreOptions
+ * @property {string} [keyPrefix='chall:']   Prepended to every key.
+ */
+
+/**
+ * @param {any} client
+ * @param {RedisStoreOptions} [options]
+ * @returns {import('./index.js').IncrStore}
+ */
+function redisStore(client, options = {}) {
+  assertRedisClient(client, ['eval'], msg => {
+    throw invalidArgument(`redisStore.client: ${msg}`);
+  });
+  const keyPrefix = options.keyPrefix ?? 'chall:';
+  const k = key => `${keyPrefix}${key}`;
+
+  return {
+    async incr(key, ttlMs) {
+      const raw = await client.eval(INCR_SCRIPT, 1, k(key), String(Math.max(1, Math.ceil(ttlMs))));
+      // ioredis returns [count, pttl] as numbers; node-redis v4 does too;
+      // Upstash HTTP driver returns strings. Coerce defensively.
+      const arr = Array.isArray(raw) ? raw : [raw, ttlMs];
+      const count = Number(arr[0]);
+      const pttl = Number(arr[1]);
+      return { count, expiresAt: Date.now() + (Number.isFinite(pttl) && pttl > 0 ? pttl : ttlMs) };
+    },
+  };
+}
+
+export { memoryStore, redisStore };