@exortek/challenge 1.0.0

package/dist/internal/guards.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export declare const invalidArgument: (msg: string, extra?: import("@exortek/shared/asserts").WrapExtra) => Error, parse: (schema: import("@exortek/shared/asserts").ParseableSchema, input: unknown, path?: string) => unknown, assertObject: (value: unknown, name: string, opts?: import("@exortek/shared/asserts").AssertOptions) => void, assertNonEmptyString: (value: unknown, name: string, opts?: import("@exortek/shared/asserts").AssertOptions) => void, assertBytes: (value: unknown, name: string, opts?: import("@exortek/shared/asserts").AssertOptions) => void;

package/dist/stores/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Store implementations shipped with `@exortek/challenge`. Any object
+ * exposing the {@link IncrStore} shape works — these are provided as
+ * a zero-config default (memory) and a cluster-safe default (Redis).
+ * `@exortek/security`'s rate-limit stores are wire-compatible.
+ */
+export { memoryStore } from './memory.js';
+export { redisStore } from './redis.js';
+export type IncrStore = {
+    /**
+     *   Atomic increment-with-expiry. First call for a fresh key returns
+     *   `{ count: 1 }` and arms a TTL of `ttlMs`; subsequent calls before
+     *   expiry return the incremented count. `verifyChallenge` reads
+     *   `count > 1` as "already consumed".
+     */
+    incr: (key: string, ttlMs: number) => Promise<{
+        count: number;
+        expiresAt?: number;
+    }>;
+};
+/**
+ * @typedef {object} IncrStore
+ * @property {(key: string, ttlMs: number) => Promise<{ count: number, expiresAt?: number }>} incr
+ *   Atomic increment-with-expiry. First call for a fresh key returns
+ *   `{ count: 1 }` and arms a TTL of `ttlMs`; subsequent calls before
+ *   expiry return the incremented count. `verifyChallenge` reads
+ *   `count > 1` as "already consumed".
+ */

package/dist/stores/memory.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+export type MemoryStoreOptions = {
+    /**
+     * Hard cap; oldest entry dropped when exceeded.
+     */
+    maxKeys?: number;
+    /**
+     * Interval for the background TTL sweep.
+     */
+    sweepMs?: number;
+};
+/**
+ * @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 }}
+ */
+export declare function memoryStore(options?: MemoryStoreOptions): import('./index.js').IncrStore & {
+    _size: () => number;
+    _stop: () => void;
+};

package/dist/stores/redis.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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).
+ */
+export type RedisStoreOptions = {
+    /**
+     * Prepended to every key.
+     */
+    keyPrefix?: string;
+};
+/**
+ * @typedef {object} RedisStoreOptions
+ * @property {string} [keyPrefix='chall:']   Prepended to every key.
+ */
+/**
+ * @param {any} client
+ * @param {RedisStoreOptions} [options]
+ * @returns {import('./index.js').IncrStore}
+ */
+export declare function redisStore(client: any, options?: RedisStoreOptions): import('./index.js').IncrStore;