@exortek/challenge 1.0.0

package/dist/index.cjs

@@ -0,0 +1,1250 @@
+'use strict';
+
+var node_crypto = require('node:crypto');
+
+/**
+ * Human-duration parser — the single source of truth across the
+ * `@exortek/*` stack.
+ *
+ * Accepts:
+ *   - `number` → **milliseconds** (Node's native time unit —
+ *     `setTimeout`, `Date.now`, `PerformanceObserver` all use ms).
+ *     Consumer packages that historically treated bare numbers as
+ *     seconds (jwt, session) do the conversion at their own
+ *     surface boundary if they want to preserve that convention.
+ *   - `string` with a unit suffix — long / plural / short forms all
+ *     work. Whitespace and fractional values tolerated on the input
+ *     side; the output is always integer milliseconds after rounding.
+ *
+ * Returns: **milliseconds**. Callers that need integer seconds
+ * (e.g. JWT `exp` claims per RFC 7519 NumericDate) divide by 1000 at
+ * their surface boundary.
+ *
+ * Supported units:
+ *
+ *   | Unit | Short              | Long / plural                      |
+ *   | ---- | ------------------ | ---------------------------------- |
+ *   | ms   | `ms`               | `millisecond`, `milliseconds`      |
+ *   | s    | `s`, `sec`         | `second`, `seconds`                |
+ *   | m    | `m`, `min`         | `minute`, `minutes`                |
+ *   | h    | `h`, `hr`          | `hour`, `hours`                    |
+ *   | d    | `d`                | `day`, `days`                      |
+ *   | w    | `w`, `wk`          | `week`, `weeks`                    |
+ *   | y    | `y`, `yr`          | `year`, `years`  (365 d)           |
+ *
+ * Deliberately strict — anything the parser doesn't understand throws
+ * instead of silently defaulting.
+ */
+
+const UNIT_MS = Object.freeze({
+  ms: 1,
+  millisecond: 1,
+  milliseconds: 1,
+  s: 1000,
+  sec: 1000,
+  second: 1000,
+  seconds: 1000,
+  m: 60_000,
+  min: 60_000,
+  minute: 60_000,
+  minutes: 60_000,
+  h: 3_600_000,
+  hr: 3_600_000,
+  hour: 3_600_000,
+  hours: 3_600_000,
+  d: 86_400_000,
+  day: 86_400_000,
+  days: 86_400_000,
+  w: 604_800_000,
+  wk: 604_800_000,
+  week: 604_800_000,
+  weeks: 604_800_000,
+  y: 31_536_000_000,
+  yr: 31_536_000_000,
+  year: 31_536_000_000,
+  years: 31_536_000_000,
+});
+
+const DURATION_RE = /^\s*(-?\d+(?:\.\d+)?)\s*([a-z]+)?\s*$/i;
+
+const SUPPORTED_UNITS = 'ms, s, m, h, d, w, y (and long/plural forms)';
+
+/**
+ * Parse a human duration to milliseconds.
+ *
+ * @param {string | number} input
+ * @returns {number} milliseconds (integer)
+ * @throws {Error} on malformed input
+ *
+ * @example
+ *   parseDuration(900)        // → 900       (ms)
+ *   parseDuration('900')      // → 900       (unit-less string = ms too)
+ *   parseDuration('500ms')    // → 500
+ *   parseDuration('15m')      // → 900_000
+ *   parseDuration('2 hours')  // → 7_200_000
+ *   parseDuration('7d')       // → 604_800_000
+ */
+function parseDuration(input) {
+  if (typeof input === 'number') {
+    if (!Number.isFinite(input)) {
+      throw new Error(`parseDuration: numeric input must be finite; got ${input}`);
+    }
+    return Math.round(input);
+  }
+  if (typeof input !== 'string') {
+    throw new TypeError(`parseDuration: expected string or number; got ${typeof input}`);
+  }
+
+  const match = DURATION_RE.exec(input);
+  if (!match) {
+    throw new Error(
+      `parseDuration: could not parse ${JSON.stringify(input)}. Examples: 900 (ms), '15m', '2h', '7d', '500ms', '30s'.`,
+    );
+  }
+  const value = Number(match[1]);
+  const unit = (match[2] || 'ms').toLowerCase();
+  const multiplier = UNIT_MS[/** @type {keyof typeof UNIT_MS} */ (unit)];
+  if (multiplier === undefined) {
+    throw new Error(`parseDuration: unknown time unit ${JSON.stringify(unit)}. Supported: ${SUPPORTED_UNITS}.`);
+  }
+  return Math.round(value * multiplier);
+}
+
+/**
+ * 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 a `Buffer` or a `Uint8Array` — the two byte
+ * shapes every crypto surface in this repo accepts interchangeably.
+ * Rejects strings so dispatch code can decide whether a string input
+ * means "already-encoded bytes" (decode it) or "wrong type" (branch).
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isBytes(value) {
+  return Buffer.isBuffer(value) || value instanceof Uint8Array;
+}
+
+/**
+ * `true` when `value` is a number primitive. Rejects `NaN`, which is
+ * technically a number but almost never what the caller intends.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isNumber(value) {
+  return typeof value === 'number' && !Number.isNaN(value);
+}
+
+/**
+ * `true` when `value` is `undefined`.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isUndefined(value) {
+  return typeof value === 'undefined';
+}
+
+/**
+ * `true` when `value` is a Node.js `Buffer`. Uint8Array-only shapes are
+ * refused — use {@link isBytes} when either satisfies the contract.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isBuffer(value) {
+  return Buffer.isBuffer(value);
+}
+
+/**
+ * `true` for a finite `number` — `NaN`, `Infinity`, and `-Infinity` all
+ * fail. Use when the caller needs a number they can compute with;
+ * mirrors `Number.isFinite` semantics under a predicate-style name.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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));
+}
+
+/**
+ * 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,
+);
+
+/**
+ * RFC 4648 §5 base64url codec.
+ *
+ * Node's `Buffer.from(str, 'base64url')` is lenient: it accepts
+ * padding, `+`, `/`, and whitespace. Wire-level use (JWS / JWT
+ * compact serialisation, JWK ingest, etc.) requires strict rejection
+ * of everything that isn't a canonical unpadded encoding — hence the
+ * roundtrip check in `decode`.
+ *
+ * Throws plain `Error` / `TypeError` on malformed input. Callers that
+ * need typed errors wrap the call at their surface boundary.
+ */
+
+const ALPHABET = /^[A-Za-z0-9_-]*$/;
+
+/**
+ * @param {Buffer | Uint8Array} bytes
+ * @returns {string}
+ */
+function encode(bytes) {
+  if (bytes == null || (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array))) {
+    throw new TypeError('base64url.encode: expected Buffer or Uint8Array');
+  }
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64url');
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function encodeString(text) {
+  if (typeof text !== 'string') {
+    throw new TypeError('base64url.encodeString: expected a string');
+  }
+  return Buffer.from(text, 'utf8').toString('base64url');
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function encodeJson(value) {
+  return encodeString(JSON.stringify(value));
+}
+
+/**
+ * @param {string} text
+ * @returns {Buffer}
+ */
+function decode$1(text) {
+  if (typeof text !== 'string') {
+    throw new TypeError('base64url.decode: expected a string');
+  }
+  if (!ALPHABET.test(text)) {
+    throw new Error('base64url.decode: input contains characters outside the RFC 4648 §5 alphabet');
+  }
+  const bytes = Buffer.from(text, 'base64url');
+  if (bytes.toString('base64url') !== text) {
+    throw new Error('base64url.decode: input is not a canonical encoding');
+  }
+  return bytes;
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function decodeToString(text) {
+  return decode$1(text).toString('utf8');
+}
+
+/**
+ * @param {string} text
+ * @returns {unknown}
+ */
+function decodeJson(text) {
+  return JSON.parse(decodeToString(text));
+}
+
+/**
+ * Length-safe `timingSafeEqual`.
+ *
+ * `crypto.timingSafeEqual` throws when its two arguments have
+ * different lengths — the exception path is itself a side channel
+ * that leaks "lengths differ" to a timing attacker even when the
+ * caller catches the throw. This wrapper closes that channel by
+ * always running a `timingSafeEqual` (against the shorter buffer
+ * padded to itself) and returning `false` on length mismatch, so the
+ * caller sees a boolean either way and total runtime does not
+ * short-circuit on length alone.
+ */
+
+
+/**
+ * @param {Buffer | Uint8Array} a
+ * @param {Buffer | Uint8Array} b
+ * @returns {boolean}
+ */
+function timingSafeEqual(a, b) {
+  const aBuf = Buffer.isBuffer(a) ? a : Buffer.from(a.buffer, a.byteOffset, a.byteLength);
+  const bBuf = Buffer.isBuffer(b) ? b : Buffer.from(b.buffer, b.byteOffset, b.byteLength);
+  if (aBuf.length !== bBuf.length) {
+    // Burn a comparison so total time doesn't short-circuit on the
+    // length gate — the attacker can't distinguish "length mismatch"
+    // from "content mismatch" by observed runtime.
+    node_crypto.timingSafeEqual(aBuf, aBuf);
+    return false;
+  }
+  return node_crypto.timingSafeEqual(aBuf, bBuf);
+}
+
+/**
+ * Token codec for `@exortek/challenge`.
+ *
+ * Format:
+ *
+ *     <prefix>.<base64url(JSON payload)>.<base64url(HMAC-SHA256 tag)>
+ *
+ * The default prefix is {@link DEFAULT_PREFIX} (`chall_v1`) — deliberately
+ * unlike a JWT so the two token families cannot be confused at a call
+ * site. Callers may override it (e.g. `'server_challenge'`,
+ * `'myapp_v1'`) to brand the wire format for a specific service; the
+ * same prefix must be used at create and verify time, or verification
+ * returns `reason: 'malformed'`.
+ *
+ * HMAC covers `<prefix>.<b64u payload>` — the same string the caller
+ * received minus the trailing tag. Any change to prefix or payload
+ * invalidates the signature; a token minted with one prefix cannot be
+ * accepted under another even by the same secret.
+ */
+
+
+const DEFAULT_PREFIX = 'chall_v1';
+const HMAC_ALG = 'sha256';
+
+// Printable ASCII, no `.` (delimiter), no whitespace. Length capped so a
+// misused prefix can't grow the token unboundedly.
+const PREFIX_RE = /^[A-Za-z0-9_-]{1,32}$/;
+
+/**
+ * Assert a prefix is well-shaped. Throws via the caller's `invalidArg`
+ * function so `createChallenge` / `verifyChallenge` can raise
+ * `ChallengeError` with the right code — this module stays free of the
+ * error class dependency.
+ *
+ * @param {string} prefix
+ * @param {string} name
+ * @param {(msg: string) => Error} invalidArg
+ * @returns {string}
+ */
+function assertPrefix(prefix, name, invalidArg) {
+  if (!isString(prefix) || !PREFIX_RE.test(prefix)) {
+    throw invalidArg(
+      `${name} must match /^[A-Za-z0-9_-]{1,32}$/ (letters, digits, '_' or '-', 1-32 chars — no '.' since it's the token delimiter); got ${JSON.stringify(prefix)}`,
+    );
+  }
+  return prefix;
+}
+
+/**
+ * Random ID for the token's `jti` claim — 128 bits of entropy, encoded
+ * as 22 base64url characters. Used as the store key for single-use
+ * enforcement, so it must be unpredictable and unique per token.
+ *
+ * @returns {string}
+ */
+function newJti() {
+  return encode(node_crypto.randomBytes(16));
+}
+
+/**
+ * Sign a payload with `secret` and return the compact token string.
+ *
+ * @param {object} payload
+ * @param {Buffer} secret     32+ raw bytes; caller validates length.
+ * @param {string} [prefix]   Wire prefix; defaults to {@link DEFAULT_PREFIX}.
+ * @returns {string}
+ */
+function sign(payload, secret, prefix = DEFAULT_PREFIX) {
+  const body = `${prefix}.${encodeJson(payload)}`;
+  const tag = node_crypto.createHmac(HMAC_ALG, secret).update(body).digest();
+  return `${body}.${encode(tag)}`;
+}
+
+/**
+ * Parse + HMAC-verify a token. Returns the decoded payload on success,
+ * or a reason string on any failure. Never throws on user-input
+ * problems — a wrong token is a normal auth outcome.
+ *
+ * @param {string} token
+ * @param {Buffer} secret
+ * @param {string} [prefix]   Expected prefix; defaults to {@link DEFAULT_PREFIX}.
+ * @returns {{ payload: object } | { reason: 'malformed' | 'bad_signature' }}
+ */
+function decode(token, secret, prefix = DEFAULT_PREFIX) {
+  if (!isString(token) || token.length === 0) {
+    return { reason: 'malformed' };
+  }
+  const parts = token.split('.');
+  if (parts.length !== 3 || parts[0] !== prefix) {
+    return { reason: 'malformed' };
+  }
+  const [, encodedPayload, encodedTag] = parts;
+  let tag;
+  try {
+    tag = decode$1(encodedTag);
+  } catch {
+    return { reason: 'malformed' };
+  }
+  const expected = node_crypto.createHmac(HMAC_ALG, secret).update(`${prefix}.${encodedPayload}`).digest();
+  if (!timingSafeEqual(tag, expected)) {
+    return { reason: 'bad_signature' };
+  }
+  let payload;
+  try {
+    payload = decodeJson(encodedPayload);
+  } catch {
+    return { reason: 'malformed' };
+  }
+  if (!isObject(payload)) {
+    return { reason: 'malformed' };
+  }
+  return { payload };
+}
+
+/**
+ * `@exortek/challenge` — signed, single-use challenge tokens for
+ * multi-step auth flows.
+ *
+ * A challenge is a small, HMAC-signed envelope that carries context
+ * across a redirect or a follow-up request without a server-side
+ * session: who is being challenged (`userId`), how they proved
+ * themselves so far (`method`), what step of the flow they've cleared
+ * (`step`), and any bespoke metadata the caller needs on the other
+ * side. The token is stateless by default; single-use enforcement and
+ * revocation are opt-in via a store the caller supplies.
+ *
+ * See the README for the full API and worked examples.
+ */
+
+
+const MIN_SECRET_BYTES = 32;
+
+const KNOWN_METHODS = new Set([
+  'totp',
+  'hotp',
+  'email_otp',
+  'sms_otp',
+  'backup_code',
+  'passkey',
+  'magic_link',
+  'password',
+  'webauthn',
+  'oauth',
+  'oidc',
+]);
+
+/**
+ * @typedef {'totp' | 'hotp' | 'email_otp' | 'sms_otp' | 'backup_code'
+ *   | 'passkey' | 'magic_link' | 'password' | 'webauthn' | 'oauth' | 'oidc'
+ *   | string} ChallengeMethod
+ */
+
+/**
+ * @typedef {object} IncrStore
+ * @property {(key: string, ttlMs: number) => Promise<{ count: number }>} incr
+ *   Atomic increment-with-expiry. First call returns `{ count: 1 }` and
+ *   arms a TTL; subsequent calls before expiry return the incremented
+ *   count. Used as compare-and-set for single-use enforcement.
+ */
+
+/**
+ * @typedef {object} ChallengePayload
+ * @property {string} jti
+ * @property {number} iat
+ * @property {number} exp
+ * @property {string} [userId]
+ * @property {ChallengeMethod} [method]
+ * @property {string} [step]
+ * @property {string} [nextStep]
+ * @property {string} [ip]                      Only set when `ipBinding: true`.
+ * @property {string} [ua]                      Only set when `ua` supplied.
+ * @property {Record<string, unknown>} [meta]
+ */
+
+/**
+ * @typedef {object} CreateChallengeOptions
+ * @property {string | Buffer | Uint8Array} secret
+ *   HMAC-SHA256 secret. **Must be at least 32 raw bytes.** A string is
+ *   interpreted as UTF-8 — for a hex or base64 secret, decode to
+ *   Buffer first.
+ * @property {string} [userId]
+ * @property {ChallengeMethod} [method]
+ * @property {string} [step]
+ * @property {string} [nextStep]
+ * @property {string} [ip]
+ * @property {string} [ua]
+ * @property {Record<string, unknown>} [metadata]
+ * @property {string | number} expiresIn        Duration string (`'5m'`) or ms integer.
+ * @property {boolean} [singleUse=false]
+ *   When true, the returned token can only be verified once — subsequent
+ *   verifies with `consume: true` fail with `reason: 'replay'`. Requires
+ *   `store` to be supplied.
+ * @property {IncrStore} [store]
+ *   Any object exposing `incr(key, ttlMs) → { count }`. Compatible with
+ *   `@exortek/security`'s rate-limit stores; also easy to wrap Redis.
+ * @property {boolean} [ipBinding=false]
+ *   When true, the caller-supplied `ip` is stamped into the payload and
+ *   `verifyChallenge` will reject a request whose `ip` differs.
+ * @property {string} [prefix='chall_v1']
+ *   Wire-format prefix. Defaults to `'chall_v1'` — the value shipped
+ *   with this package. Callers can override to brand the token
+ *   family (e.g. `'server_challenge'`, `'myapp_v1'`); must match
+ *   `/^[A-Za-z0-9_-]{1,32}$/`. The same prefix must be passed at
+ *   verify time or verification returns `reason: 'malformed'`.
+ * @property {number} [now]                     Override `Date.now()` for testing.
+ */
+
+/**
+ * @typedef {object} VerifyChallengeOptions
+ * @property {string | Buffer | Uint8Array} secret
+ * @property {boolean} [consume=false]
+ *   Enforce single-use. Requires `store` (typically the same one used
+ *   at create time).
+ * @property {IncrStore} [store]
+ * @property {string} [expectedUserId]
+ * @property {ChallengeMethod} [expectedMethod]
+ * @property {string} [expectedStep]
+ * @property {string} [expectedNextStep]
+ * @property {string} [ip]
+ *   The current request's IP. Required to verify a token that was
+ *   created with `ipBinding: true`; ignored otherwise.
+ * @property {string} [prefix='chall_v1']
+ *   Wire-format prefix. Must match the value passed to
+ *   `createChallenge` — a token minted with a different prefix will
+ *   fail with `reason: 'malformed'`.
+ * @property {number} [now]                     Override `Date.now()` for testing.
+ */
+
+/**
+ * @typedef {'malformed' | 'bad_signature' | 'expired' | 'not_yet_valid'
+ *   | 'user_mismatch' | 'method_mismatch' | 'step_mismatch'
+ *   | 'next_step_mismatch' | 'ip_mismatch' | 'ip_missing' | 'replay'
+ *   | 'store_unavailable'} VerifyFailureReason
+ */
+
+/**
+ * @typedef {{ valid: true, payload: ChallengePayload }
+ *   | { valid: false, reason: VerifyFailureReason }} VerifyChallengeResult
+ */
+
+/**
+ * Create a signed challenge token.
+ *
+ *   const token = await createChallenge({
+ *     secret: process.env.CHALLENGE_SECRET,
+ *     userId: 'usr_123',
+ *     method: 'totp',
+ *     step: 'mfa_verified',
+ *     nextStep: 'login',
+ *     expiresIn: '5m',
+ *     singleUse: true,
+ *     store,
+ *   })
+ *
+ * @param {CreateChallengeOptions} options
+ * @returns {Promise<string>}
+ */
+async function createChallenge(options) {
+  if (!isObject(options)) {
+    throw invalidArgument('createChallenge.options must be an object');
+  }
+  const secret = _coerceSecret(options.secret, 'createChallenge.options.secret');
+  let ttlMs;
+  try {
+    ttlMs = parseDuration(options.expiresIn);
+  } catch (err) {
+    throw invalidArgument(`createChallenge.options.expiresIn: ${err.message}`, { cause: err });
+  }
+  if (!isFiniteNumber(ttlMs) || ttlMs <= 0) {
+    throw invalidArgument(`createChallenge.options.expiresIn must resolve to a positive duration; got ${ttlMs}ms`);
+  }
+  const prefix = isUndefined(options.prefix)
+    ? DEFAULT_PREFIX
+    : assertPrefix(options.prefix, 'createChallenge.options.prefix', invalidArgument);
+  _assertStringOrUndef(options.userId, 'createChallenge.options.userId');
+  _assertMethod(options.method, 'createChallenge.options.method');
+  _assertStringOrUndef(options.step, 'createChallenge.options.step');
+  _assertStringOrUndef(options.nextStep, 'createChallenge.options.nextStep');
+  _assertStringOrUndef(options.ua, 'createChallenge.options.ua');
+
+  const singleUse = options.singleUse === true;
+  const ipBinding = options.ipBinding === true;
+
+  if (singleUse && !_isStore(options.store)) {
+    throw invalidArgument(
+      'createChallenge.options.store is required when singleUse: true — pass an object exposing incr(key, ttlMs) → { count }',
+    );
+  }
+  if (ipBinding && !isString(options.ip)) {
+    throw invalidArgument('createChallenge.options.ip must be a string when ipBinding: true');
+  }
+  if (!isUndefined(options.metadata) && !isObject(options.metadata)) {
+    throw invalidArgument('createChallenge.options.metadata must be a plain object when provided');
+  }
+
+  const now = _now(options.now);
+  const jti = newJti();
+
+  /** @type {ChallengePayload} */
+  const payload = {
+    jti,
+    iat: Math.floor(now / 1000),
+    exp: Math.floor((now + ttlMs) / 1000),
+  };
+  if (options.userId) {
+    payload.userId = options.userId;
+  }
+  if (options.method) {
+    payload.method = options.method;
+  }
+  if (options.step) {
+    payload.step = options.step;
+  }
+  if (options.nextStep) {
+    payload.nextStep = options.nextStep;
+  }
+  if (ipBinding) {
+    payload.ip = options.ip;
+  }
+  if (isString(options.ua)) {
+    payload.ua = options.ua;
+  }
+  if (!isUndefined(options.metadata)) {
+    payload.meta = options.metadata;
+  }
+  if (singleUse) {
+    payload.su = 1;
+  }
+
+  return sign(payload, secret, prefix);
+}
+
+/**
+ * Verify a challenge token. Returns `{ valid: true, payload }` on
+ * success or `{ valid: false, reason }` on any expected failure. Only
+ * throws on programmer errors (bad options, missing secret).
+ *
+ *   const res = await verifyChallenge(token, {
+ *     secret: process.env.CHALLENGE_SECRET,
+ *     consume: true,
+ *     store,
+ *     expectedUserId: pendingUserId,
+ *     expectedMethod: 'totp',
+ *     ip: req.ip,
+ *   })
+ *   if (!res.valid) return reply.code(401).send({ error: res.reason })
+ *
+ * @param {string} token
+ * @param {VerifyChallengeOptions} options
+ * @returns {Promise<VerifyChallengeResult>}
+ */
+async function verifyChallenge(token, options) {
+  if (!isObject(options)) {
+    throw invalidArgument('verifyChallenge.options must be an object');
+  }
+  const secret = _coerceSecret(options.secret, 'verifyChallenge.options.secret');
+  const consume = options.consume === true;
+  if (consume && !_isStore(options.store)) {
+    throw invalidArgument(
+      'verifyChallenge.options.store is required when consume: true — pass the same store used at create time',
+    );
+  }
+  const prefix = isUndefined(options.prefix)
+    ? DEFAULT_PREFIX
+    : assertPrefix(options.prefix, 'verifyChallenge.options.prefix', invalidArgument);
+
+  const parsed = decode(token, secret, prefix);
+  if ('reason' in parsed) {
+    return { valid: false, reason: parsed.reason };
+  }
+  const payload = /** @type {ChallengePayload & { su?: 1 }} */ (parsed.payload);
+  const now = _now(options.now);
+  const nowSec = Math.floor(now / 1000);
+
+  if (!isNumber(payload.exp) || payload.exp <= nowSec) {
+    return { valid: false, reason: 'expired' };
+  }
+  if (isNumber(payload.iat) && payload.iat > nowSec + 60) {
+    // Small clock-skew tolerance (60s) — reject only if clearly future-dated.
+    return { valid: false, reason: 'not_yet_valid' };
+  }
+  if (!isUndefined(options.expectedUserId) && payload.userId !== options.expectedUserId) {
+    return { valid: false, reason: 'user_mismatch' };
+  }
+  if (!isUndefined(options.expectedMethod) && payload.method !== options.expectedMethod) {
+    return { valid: false, reason: 'method_mismatch' };
+  }
+  if (!isUndefined(options.expectedStep) && payload.step !== options.expectedStep) {
+    return { valid: false, reason: 'step_mismatch' };
+  }
+  if (!isUndefined(options.expectedNextStep) && payload.nextStep !== options.expectedNextStep) {
+    return { valid: false, reason: 'next_step_mismatch' };
+  }
+  if (!isUndefined(payload.ip)) {
+    if (!isString(options.ip)) {
+      return { valid: false, reason: 'ip_missing' };
+    }
+    if (options.ip !== payload.ip) {
+      return { valid: false, reason: 'ip_mismatch' };
+    }
+  }
+  if (consume && payload.su === 1) {
+    const ttlMs = Math.max(1, payload.exp * 1000 - now);
+    let count;
+    try {
+      // Namespace lives in the store's own keyPrefix (redisStore defaults
+      // to 'chall:'). verifyChallenge passes the raw jti so a store shared
+      // with other purposes can prefix once — no double 'chall:chall:'.
+      const res = await options.store.incr(payload.jti, ttlMs);
+      count = res?.count;
+    } catch {
+      return { valid: false, reason: 'store_unavailable' };
+    }
+    if (!isNumber(count) || count > 1) {
+      return { valid: false, reason: 'replay' };
+    }
+  }
+  // Strip internal fields so callers see only their own payload.
+  const { su: _su, ...clean } = payload;
+  return { valid: true, payload: clean };
+}
+
+function _coerceSecret(input, name) {
+  if (isString(input)) {
+    const buf = Buffer.from(input, 'utf8');
+    if (buf.length < MIN_SECRET_BYTES) {
+      throw new ChallengeError(
+        ErrorCode.INVALID_SECRET,
+        `${name} must be at least ${MIN_SECRET_BYTES} bytes; got ${buf.length}. Generate one with: node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"`,
+      );
+    }
+    return buf;
+  }
+  if (isBytes(input)) {
+    if (input.length < MIN_SECRET_BYTES) {
+      throw new ChallengeError(
+        ErrorCode.INVALID_SECRET,
+        `${name} must be at least ${MIN_SECRET_BYTES} bytes; got ${input.length}`,
+      );
+    }
+    return isBuffer(input) ? input : Buffer.from(input);
+  }
+  throw invalidArgument(`${name} must be a string, Buffer, or Uint8Array`);
+}
+
+function _assertStringOrUndef(v, name) {
+  if (!isUndefined(v) && !isString(v)) {
+    throw invalidArgument(`${name} must be a string when provided`);
+  }
+}
+
+function _assertMethod(v, name) {
+  if (isUndefined(v)) {
+    return;
+  }
+  if (!isString(v)) {
+    throw invalidArgument(`${name} must be a string when provided`);
+  }
+  if (!KNOWN_METHODS.has(v)) ;
+}
+
+function _isStore(v) {
+  return isObject(v) && isFunction(v.incr);
+}
+
+function _now(override) {
+  return isNumber(override) ? override : Date.now();
+}
+
+exports.ChallengeError = ChallengeError;
+exports.ErrorCode = ErrorCode;
+exports.createChallenge = createChallenge;
+exports.verifyChallenge = verifyChallenge;