@exortek/apikey 1.0.0

package/dist/index.mjs

@@ -0,0 +1,1617 @@
+import { timingSafeEqual as timingSafeEqual$1, randomBytes, createHmac, createHash } from '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` for arrays. Thin wrapper over `Array.isArray` so predicates
+ * live under one import; identical behaviour.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isArray(value) {
+  return Array.isArray(value);
+}
+
+/**
+ * `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);
+}
+
+/**
+ * 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/apikey` can raise. Branch on `code`, never on the message.
+ * Note: expected verify failures (bad secret, expired, revoked,
+ * missing scope) are NOT thrown — `verifyApiKey` returns
+ * `{ valid: false, reason }` so a wrong or stale key is a normal auth
+ * outcome, not an exception. Errors below fire only when the caller
+ * configured something wrong or the store misbehaved.
+ */
+
+const ErrorCode = Object.freeze({
+  INVALID_ARGUMENT: 'INVALID_ARGUMENT',
+  INVALID_PREFIX: 'INVALID_PREFIX',
+  INVALID_PEPPER: 'INVALID_PEPPER',
+  STORE_ERROR: 'STORE_ERROR',
+});
+
+/**
+ * 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 ApiKeyError extends BaseError {
+  static statuses = {
+    [ErrorCode.INVALID_ARGUMENT]: 400,
+    [ErrorCode.INVALID_PREFIX]: 400,
+    [ErrorCode.INVALID_PEPPER]: 400,
+    [ErrorCode.STORE_ERROR]: 500,
+  };
+  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 `ApiKeyError` — the package-wide binding of
+ * `@exortek/shared/asserts`. Import guards from here, never from the
+ * shared module directly.
+ */
+
+
+const { invalidArgument} = defineGuards(
+  ApiKeyError,
+  ErrorCode.INVALID_ARGUMENT,
+);
+
+/**
+ * Scope match helpers.
+ *
+ * A **granted** scope authorises access. A **required** scope names the
+ * access an endpoint needs. `hasAll` / `hasAny` decide whether the
+ * granted set covers the requirement, with wildcard support:
+ *
+ * - `'*'` in the granted list → matches every required scope.
+ * - A `'ns:*'` suffix wildcard → matches any scope under the namespace
+ *   (`'read:*'` covers `'read:users'` and `'read:posts'`).
+ * - Exact string match otherwise.
+ *
+ * Wildcards apply only on the granted side. `required` values must be
+ * concrete — an API cannot demand "some read:* scope"; it must state
+ * exactly which one it needs.
+ */
+
+
+/**
+ * Does `granted` cover a single `required` scope?
+ * @param {string[]} granted
+ * @param {string} required
+ * @returns {boolean}
+ */
+function covers(granted, required) {
+  if (!isArray(granted) || !isString(required) || required.length === 0) {
+    return false;
+  }
+  for (const g of granted) {
+    if (!isString(g)) {
+      continue;
+    }
+    if (g === '*' || g === required) {
+      return true;
+    }
+    // Suffix wildcard: `read:*` matches `read:users`.
+    if (g.endsWith(':*')) {
+      const ns = g.slice(0, -1); // 'read:'
+      if (required.startsWith(ns) && required.length > ns.length) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * All required scopes must be covered by granted.
+ * @param {string[]} granted
+ * @param {string[]} required
+ * @returns {boolean}
+ */
+function hasAll(granted, required) {
+  if (!isArray(required)) {
+    return false;
+  }
+  if (required.length === 0) {
+    return true;
+  }
+  for (const r of required) {
+    if (!covers(granted, r)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * At least one required scope must be covered.
+ * @param {string[]} granted
+ * @param {string[]} required
+ * @returns {boolean}
+ */
+function hasAny(granted, required) {
+  if (!isArray(required) || required.length === 0) {
+    return false;
+  }
+  for (const r of required) {
+    if (covers(granted, r)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * 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$1 = /^[A-Za-z0-9_-]*$/;
+
+/**
+ * @param {Buffer | Uint8Array} bytes
+ * @returns {string}
+ */
+function encode$1(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 {Buffer}
+ */
+function decode$1(text) {
+  if (typeof text !== 'string') {
+    throw new TypeError('base64url.decode: expected a string');
+  }
+  if (!ALPHABET$1.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;
+}
+
+/**
+ * Crockford Base32 codec — RFC 4648-style but with the four look-alike
+ * glyphs `I`, `L`, `O`, `U` dropped for human legibility. Uppercase on
+ * encode, case-insensitive on decode with Crockford check aliases:
+ * `I` / `L` decode as `1`, `O` decodes as `0`. The four uppercase check
+ * symbols (`*`, `~`, `$`, `=`) that some tooling appends are **not**
+ * supported.
+ *
+ * Consumers (crypto public codec, otp backup codes, jwt polymorphic
+ * encoding) all reach for the same alphabet + encode loop; this file
+ * is the single implementation. Errors here are plain `Error` /
+ * `TypeError`; each consumer wraps them into its own typed error at
+ * the surface boundary.
+ */
+
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+const DECODE_TABLE = new Int8Array(128).fill(-1);
+for (let i = 0; i < ALPHABET.length; i++) {
+  DECODE_TABLE[ALPHABET.charCodeAt(i)] = i;
+  const c = ALPHABET[i];
+  if (c >= 'A' && c <= 'Z') {
+    // Lowercase alias for letters only. Digits share code point rows
+    // that would collide with the +32 shift used for uppercase.
+    DECODE_TABLE[ALPHABET.charCodeAt(i) + 32] = i;
+  }
+}
+// Crockford check aliases: I / L → 1, O → 0 (case-insensitive).
+for (const [alias, canonical] of [
+  ['I', '1'],
+  ['i', '1'],
+  ['L', '1'],
+  ['l', '1'],
+  ['O', '0'],
+  ['o', '0'],
+]) {
+  DECODE_TABLE[alias.charCodeAt(0)] = DECODE_TABLE[canonical.charCodeAt(0)];
+}
+
+/**
+ * Encode bytes as a Crockford base32 string.
+ *
+ * @param {Buffer | Uint8Array} bytes
+ * @returns {string}
+ * @throws {TypeError} if `bytes` is not a Buffer or Uint8Array.
+ */
+function encode(bytes) {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError('encode: input must be a Buffer or Uint8Array.');
+  }
+  if (bytes.length === 0) {
+    return '';
+  }
+
+  let out = '';
+  let bits = 0;
+  let value = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    value = (value << 8) | bytes[i];
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += ALPHABET[(value >>> bits) & 0x1f];
+      value &= (1 << bits) - 1;
+    }
+  }
+  if (bits > 0) {
+    out += ALPHABET[(value << (5 - bits)) & 0x1f];
+  }
+  return out;
+}
+
+/**
+ * Decode a Crockford base32 string into a Buffer.
+ *
+ * Case-insensitive. `I` / `L` → `1`, `O` → `0`. Any other non-alphabet
+ * character throws.
+ *
+ * @param {string} input
+ * @returns {Buffer}
+ * @throws {TypeError} if `input` is not a string.
+ * @throws {Error}     if `input` contains a character outside the alphabet.
+ */
+function decode(input) {
+  if (typeof input !== 'string') {
+    throw new TypeError('decode: input must be a string.');
+  }
+  if (input.length === 0) {
+    return Buffer.alloc(0);
+  }
+
+  const outLength = Math.floor((input.length * 5) / 8);
+  const out = Buffer.alloc(outLength);
+  let bits = 0;
+  let value = 0;
+  let index = 0;
+  for (let i = 0; i < input.length; i++) {
+    const code = input.charCodeAt(i);
+    const v = code < 128 ? DECODE_TABLE[code] : -1;
+    if (v === -1) {
+      throw new Error(
+        `input contains a non-Crockford character '${input[i]}' at index ${i}. Crockford base32 alphabet is 0-9 A-Z minus I L O U (case-insensitive); I/L decode as 1, O decodes as 0.`,
+      );
+    }
+    value = (value << 5) | v;
+    bits += 5;
+    if (bits >= 8) {
+      bits -= 8;
+      out[index++] = (value >>> bits) & 0xff;
+      value &= (1 << bits) - 1;
+    }
+  }
+  return out;
+}
+
+/**
+ * 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.
+    timingSafeEqual$1(aBuf, aBuf);
+    return false;
+  }
+  return timingSafeEqual$1(aBuf, bBuf);
+}
+
+/**
+ * Token codec for `@exortek/apikey`.
+ *
+ * **Wire format:**
+ *
+ *     <prefix>_<base64url(16 random bytes)>_<base64url(32 random bytes)>
+ *     ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ *     type     id (128-bit — plaintext DB key)   secret (256-bit — HMAC'd)
+ *
+ *   sk_live_QVI0RExDX01Fbg_pTk9UX0FfUkVBTF9LRVlfNDJfQVJUSVNBTkFMX1BJWk
+ *
+ * Stripe / GitHub / Anthropic all use this three-segment shape. The
+ * split matters:
+ *
+ * - The **id** is stored in the clear so a request's incoming key can
+ *   be found in the DB with a single O(1) primary-key lookup. It is not
+ *   secret: an attacker who guesses an id alone cannot verify — the
+ *   secret half is still gated by the HMAC compare.
+ * - The **secret** is never stored in the clear. Storage keeps only
+ *   `HMAC-SHA256(secret, pepper)` (or plain SHA-256 when no pepper is
+ *   configured). API keys are random 256-bit values — a fast hash is
+ *   fine for storage; slow KDFs like Argon2 exist for low-entropy
+ *   passwords, not for cryptographically random secrets.
+ * - The **pepper** (optional) is a server-side secret held in the app
+ *   env, not the DB. A stolen database on its own does not let an
+ *   attacker offline-brute the stored hashes; they also need the
+ *   pepper. Peppers rotate via a newest-first array.
+ *
+ * The whole key is opaque to holders — do not parse the segments in
+ * client code; only the server's `parseApiKey` sees them.
+ */
+
+
+const ID_BYTES = 16;
+const SECRET_BYTES = 32;
+
+// Base32-Crockford alphabet is [0-9A-HJKMNP-TV-Z] — no ambiguous
+// glyphs (`I`, `L`, `O`, `U` excluded), no separators (`_` reserved as
+// our own delimiter), URL-safe, human-transcribable. 16 bytes → 26
+// chars for the id; 32 bytes → 52 chars for the secret. The wire key
+// is unambiguously three underscore-separated segments.
+const ID_CHARS = 26;
+const SECRET_CHARS = 52;
+const CROCKFORD_RE = /^[0-9A-HJKMNP-TV-Z]+$/;
+
+/**
+ * Prefix grammar — Stripe-style: lowercase alpha, digits, underscore
+ * separators between 1-4 lower-alphanumeric segments. Keeps the token
+ * unambiguously parseable and safe to embed in URLs / headers.
+ *
+ *   sk_live      ✓
+ *   pk_test      ✓
+ *   svc_prod_v2  ✓
+ *   sk__live     ✗ (empty segment)
+ *   sk_live_     ✗ (trailing underscore)
+ *   Sk_Live      ✗ (uppercase)
+ */
+const PREFIX_RE = /^[a-z][a-z0-9]{0,15}(_[a-z0-9]{1,15}){0,3}$/;
+
+/**
+ * @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-z][a-z0-9]{0,15}(_[a-z0-9]{1,15}){0,3}$/ — Stripe-style lowercase with underscore-separated segments (e.g. 'sk_live', 'pk_test'); got ${JSON.stringify(prefix)}`,
+    );
+  }
+  return prefix;
+}
+
+/**
+ * Mint the raw pieces of a new key. Returns the wire token, the
+ * plaintext id (for DB lookup), and the storage hash of the secret.
+ *
+ * @param {string} prefix
+ * @param {Buffer | null} pepper   Newest pepper, or null when unconfigured.
+ * @returns {{ key: string, id: string, hash: string }}
+ */
+function mint(prefix, pepper) {
+  const id = encode(randomBytes(ID_BYTES));
+  const secretBytes = randomBytes(SECRET_BYTES);
+  const secret = encode(secretBytes);
+  const key = `${prefix}_${id}_${secret}`;
+  const hash = hashSecret(secretBytes, pepper);
+  return { key, id, hash };
+}
+
+/**
+ * Compute the storage hash of a raw secret. With a pepper: HMAC-SHA256
+ * keyed by the pepper. Without: plain SHA-256. Both return the digest
+ * as a 43-char base64url string.
+ *
+ * @param {Buffer} secretBytes
+ * @param {Buffer | null} pepper
+ * @returns {string}
+ */
+function hashSecret(secretBytes, pepper) {
+  const digest = pepper
+    ? createHmac('sha256', pepper).update(secretBytes).digest()
+    : createHash('sha256').update(secretBytes).digest();
+  return encode$1(digest);
+}
+
+/**
+ * Timing-safe compare of a candidate hash against a stored hash. Both
+ * inputs are base64url strings of equal length — a length mismatch is
+ * treated as a mismatch after a fixed decode step, so an outside
+ * observer cannot learn the stored hash's length via timing.
+ *
+ * @param {string} candidate
+ * @param {string} stored
+ * @returns {boolean}
+ */
+function hashesMatch(candidate, stored) {
+  if (!isString(candidate) || !isString(stored) || candidate.length !== stored.length) {
+    return false;
+  }
+  let a;
+  let b;
+  try {
+    a = decode$1(candidate);
+    b = decode$1(stored);
+  } catch {
+    return false;
+  }
+  return timingSafeEqual(a, b);
+}
+
+/**
+ * Parse a raw key without verifying it. Returns the segments, or
+ * `null` when the shape is wrong. Never throws.
+ *
+ * Callers can use `parseApiKey(key).prefix` to route by key family
+ * in a middleware before hitting the store — but the parse result
+ * MUST NOT be trusted as authenticated. Only `verifyApiKey` proves
+ * the holder possesses the real secret.
+ *
+ * @param {string} key
+ * @returns {{ prefix: string, id: string, secret: string } | null}
+ */
+function parseApiKey(key) {
+  if (!isString(key)) {
+    return null;
+  }
+  // The prefix may contain '_' (`sk_live`, `svc_prod_v2`), but id and
+  // secret use the base32-crockford alphabet which contains no
+  // underscores — so the last two '_' cleanly bound them.
+  const lastUnderscore = key.lastIndexOf('_');
+  if (lastUnderscore <= 0) {return null;}
+  const prevUnderscore = key.lastIndexOf('_', lastUnderscore - 1);
+  if (prevUnderscore <= 0) {return null;}
+  const prefix = key.slice(0, prevUnderscore);
+  const id = key.slice(prevUnderscore + 1, lastUnderscore);
+  const secret = key.slice(lastUnderscore + 1);
+  if (!PREFIX_RE.test(prefix)) {return null;}
+  if (id.length !== ID_CHARS || !CROCKFORD_RE.test(id)) {return null;}
+  if (secret.length !== SECRET_CHARS || !CROCKFORD_RE.test(secret)) {return null;}
+  return { prefix, id, secret };
+}
+
+/**
+ * Compute the storage hash for a candidate raw key's secret half,
+ * trying peppers newest-first. Returns the hash + which pepper matched
+ * (or null if no pepper array was supplied).
+ *
+ * Used by `verifyApiKey` — it hashes the incoming secret with each
+ * pepper in the rotation and lets the caller decide which one to
+ * compare against. The needsRehash signal (secret matched an older
+ * pepper) is exposed to consumers so they can silently upgrade
+ * storage on the next successful auth.
+ *
+ * @param {string} rawSecret     The base64url secret segment.
+ * @param {Buffer[] | null} peppers
+ * @returns {{ candidateHashes: string[] }}
+ */
+function candidateHashesFor(rawSecret, peppers) {
+  let secretBytes;
+  try {
+    secretBytes = decode(rawSecret);
+  } catch {
+    return { candidateHashes: [] };
+  }
+  if (!peppers || peppers.length === 0) {
+    return { candidateHashes: [hashSecret(secretBytes, null)] };
+  }
+  return {
+    candidateHashes: peppers.map(p => hashSecret(secretBytes, p)),
+  };
+}
+
+/**
+ * Log-safe display for a key. Returns `<prefix>_<first-N-of-id>…<last-M-of-secret>`
+ * so the value is recognisable in an audit log without disclosing the
+ * secret. The default masks all but the first 6 chars of the id and
+ * the last 4 chars of the secret.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+function mask(key) {
+  const parsed = parseApiKey(key);
+  if (!parsed) {
+    return typeof key === 'string' ? key.slice(0, 3) + '…' : '<invalid>';
+  }
+  const idHint = parsed.id.slice(0, 6);
+  const secretTail = parsed.secret.slice(-4);
+  return `${parsed.prefix}_${idHint}…${secretTail}`;
+}
+
+/**
+ * `@exortek/apikey` — Stripe-style prefixed API keys with HMAC-hashed
+ * storage, scope allowlists, and opt-in pepper rotation.
+ *
+ * See the README for the full API and worked examples.
+ */
+
+
+/** Prefix-specific factory so `assertPrefix` throws `INVALID_PREFIX`,
+ *  not the generic `INVALID_ARGUMENT`. Callers can `catch (err)` and
+ *  branch on `err.code === ErrorCode.INVALID_PREFIX` — a specific
+ *  code beats a generic one for pinpointing config drift. */
+const invalidPrefix = msg => new ApiKeyError(ErrorCode.INVALID_PREFIX, msg);
+
+const MIN_PEPPER_BYTES = 16;
+
+/**
+ * @typedef {object} ApiKeyRecord
+ * @property {string} id                      Plaintext lookup key (128-bit b64u).
+ * @property {string} hash                    Storage hash of the secret (43-char b64u).
+ * @property {string} prefix                  The prefix the key was minted with.
+ * @property {string} userId
+ * @property {string[]} scopes
+ * @property {string} [name]                  Human label ("Production Backend").
+ * @property {string} [environment]           `'live'` / `'test'` / caller-defined.
+ * @property {Record<string, unknown>} [metadata]
+ * @property {number} createdAt               ms epoch.
+ * @property {number} [expiresAt]             ms epoch; absent = no expiry.
+ * @property {number} [revokedAt]             ms epoch when the record was revoked.
+ * @property {string} [revokedReason]
+ * @property {number} [lastUsedAt]            ms epoch of the last successful verify.
+ * @property {number} [pepperVersion]         Index into the peppers array that was used at mint. 0 = newest.
+ */
+
+/**
+ * @typedef {object} ApiKeyStore
+ * @property {(record: ApiKeyRecord) => Promise<void>} put
+ * @property {(id: string) => Promise<ApiKeyRecord | null>} getById
+ * @property {(id: string, patch: Partial<ApiKeyRecord>) => Promise<ApiKeyRecord | null>} update
+ * @property {(id: string, reason?: string) => Promise<boolean>} revoke
+ * @property {(userId: string, reason?: string) => Promise<number>} revokeAllForUser
+ * @property {(userId: string) => Promise<ApiKeyRecord[]>} listByUser
+ */
+
+/**
+ * @typedef {object} CreateApiKeyOptions
+ * @property {string} prefix                       Stripe-style; `sk_live`, `pk_test`, `svc_prod_v2`.
+ * @property {string} userId
+ * @property {string[]} scopes
+ * @property {string} [name]
+ * @property {string} [environment]
+ * @property {Record<string, unknown>} [metadata]
+ * @property {string | number} [expiresIn]         `'1y'` / `'30d'` / ms integer. Omit for no expiry.
+ * @property {ApiKeyStore} store
+ * @property {(Buffer | Uint8Array | string)[]} [peppers]
+ *   Newest first. Each ≥16 bytes. Omit for plain SHA-256 storage.
+ * @property {number} [now]                        Override `Date.now()` for testing.
+ */
+
+/**
+ * @typedef {object} CreateApiKeyResult
+ * @property {string} key       Wire token — show ONCE to the caller and never again.
+ * @property {string} id        Plaintext lookup key; safe to store / log / display.
+ * @property {ApiKeyRecord} record  What was persisted to the store.
+ */
+
+/**
+ * @typedef {object} VerifyApiKeyOptions
+ * @property {ApiKeyStore} store
+ * @property {(Buffer | Uint8Array | string)[]} [peppers]
+ * @property {string[]} [requiredScopes]
+ * @property {string} [expectedPrefix]             Reject a valid key whose prefix differs.
+ * @property {boolean} [updateLastUsed=false]      Bump `lastUsedAt` on success (one extra store write).
+ * @property {number} [now]
+ */
+
+/**
+ * @typedef {'malformed' | 'not_found' | 'expired' | 'revoked'
+ *   | 'bad_secret' | 'prefix_mismatch' | 'missing_scope'
+ *   | 'store_unavailable'} VerifyApiKeyFailureReason
+ */
+
+/**
+ * @typedef {{
+ *   valid: true,
+ *   id: string,
+ *   userId: string,
+ *   scopes: string[],
+ *   prefix: string,
+ *   name?: string,
+ *   environment?: string,
+ *   metadata?: Record<string, unknown>,
+ *   needsRehash?: boolean,
+ * } | { valid: false, reason: VerifyApiKeyFailureReason }} VerifyApiKeyResult
+ */
+
+/**
+ * Mint a new API key. The wire `key` is returned once — the caller
+ * MUST show it to the end user immediately and never persist it in
+ * the clear (only the storage `hash` inside the returned `record` is
+ * safe to keep).
+ *
+ * @param {CreateApiKeyOptions} options
+ * @returns {Promise<CreateApiKeyResult>}
+ */
+async function createApiKey(options) {
+  if (!isObject(options)) {
+    throw invalidArgument('createApiKey.options must be an object');
+  }
+  const prefix = assertPrefix(options.prefix, 'createApiKey.options.prefix', invalidPrefix);
+  const userId = _requireString(options.userId, 'createApiKey.options.userId');
+  const scopes = _requireStringArray(options.scopes, 'createApiKey.options.scopes');
+  _assertStore(options.store, 'createApiKey.options.store');
+  _assertStringOrUndef(options.name, 'createApiKey.options.name');
+  _assertStringOrUndef(options.environment, 'createApiKey.options.environment');
+  if (!isUndefined(options.metadata) && !isObject(options.metadata)) {
+    throw invalidArgument('createApiKey.options.metadata must be a plain object when provided');
+  }
+  const peppers = _normalizePeppers(options.peppers, 'createApiKey.options.peppers');
+  const now = _now(options.now);
+  let expiresAt;
+  if (!isUndefined(options.expiresIn)) {
+    let ttlMs;
+    try {
+      ttlMs = parseDuration(options.expiresIn);
+    } catch (err) {
+      throw invalidArgument(`createApiKey.options.expiresIn: ${err.message}`, { cause: err });
+    }
+    if (!isNumber(ttlMs) || ttlMs <= 0) {
+      throw invalidArgument(`createApiKey.options.expiresIn must resolve to a positive duration; got ${ttlMs}ms`);
+    }
+    expiresAt = now + ttlMs;
+  }
+
+  const newestPepper = peppers && peppers.length > 0 ? peppers[0] : null;
+  const { key, id, hash } = mint(prefix, newestPepper);
+
+  /** @type {ApiKeyRecord} */
+  const record = {
+    id,
+    hash,
+    prefix,
+    userId,
+    scopes: [...scopes],
+    createdAt: now,
+  };
+  if (!isUndefined(options.name)) {
+    record.name = options.name;
+  }
+  if (!isUndefined(options.environment)) {
+    record.environment = options.environment;
+  }
+  if (!isUndefined(options.metadata)) {
+    record.metadata = { ...options.metadata };
+  }
+  if (!isUndefined(expiresAt)) {
+    record.expiresAt = expiresAt;
+  }
+  if (peppers) {
+    record.pepperVersion = 0;
+  }
+
+  try {
+    await options.store.put(record);
+  } catch (err) {
+    throw new ApiKeyError(ErrorCode.STORE_ERROR, `createApiKey.store.put failed: ${err.message}`, { cause: err });
+  }
+  return { key, id, record };
+}
+
+/**
+ * Verify a raw API key. Returns `{ valid: true, ... }` on success, or
+ * `{ valid: false, reason }` on any expected failure. Never throws on
+ * a bad key — a wrong or stale key is a normal auth outcome.
+ *
+ * On success, callers get the stored `userId` / `scopes` / `metadata`
+ * and can pass them straight to their app's auth context.
+ * `needsRehash: true` in the success result signals the secret matched
+ * an older pepper — call `rehashApiKey(id, options)` to silently
+ * migrate storage to the newest pepper on the next natural chance.
+ *
+ * @param {string} rawKey
+ * @param {VerifyApiKeyOptions} options
+ * @returns {Promise<VerifyApiKeyResult>}
+ */
+async function verifyApiKey(rawKey, options) {
+  if (!isObject(options)) {
+    throw invalidArgument('verifyApiKey.options must be an object');
+  }
+  _assertStore(options.store, 'verifyApiKey.options.store');
+  const peppers = _normalizePeppers(options.peppers, 'verifyApiKey.options.peppers');
+  const requiredScopes = options.requiredScopes;
+  if (!isUndefined(requiredScopes) && !_isStringArray(requiredScopes)) {
+    throw invalidArgument('verifyApiKey.options.requiredScopes must be a string[] when provided');
+  }
+  if (!isUndefined(options.expectedPrefix)) {
+    assertPrefix(options.expectedPrefix, 'verifyApiKey.options.expectedPrefix', invalidPrefix);
+  }
+
+  const parsed = parseApiKey(rawKey);
+  if (!parsed) {
+    return { valid: false, reason: 'malformed' };
+  }
+  if (!isUndefined(options.expectedPrefix) && parsed.prefix !== options.expectedPrefix) {
+    return { valid: false, reason: 'prefix_mismatch' };
+  }
+
+  let record;
+  try {
+    record = await options.store.getById(parsed.id);
+  } catch {
+    return { valid: false, reason: 'store_unavailable' };
+  }
+  if (!record) {
+    return { valid: false, reason: 'not_found' };
+  }
+  const now = _now(options.now);
+  if (record.revokedAt) {
+    return { valid: false, reason: 'revoked' };
+  }
+  if (record.expiresAt && record.expiresAt <= now) {
+    return { valid: false, reason: 'expired' };
+  }
+  if (parsed.prefix !== record.prefix) {
+    // Someone submitted a key whose id belongs to a different prefix —
+    // treat as bad, not merely 'prefix_mismatch', because the id half
+    // was correct: the attacker guessed the id and swapped the prefix.
+    return { valid: false, reason: 'prefix_mismatch' };
+  }
+  const { candidateHashes } = candidateHashesFor(parsed.secret, peppers);
+  let matched = false;
+  let matchedIndex = -1;
+  for (let i = 0; i < candidateHashes.length; i++) {
+    if (hashesMatch(candidateHashes[i], record.hash)) {
+      matched = true;
+      matchedIndex = i;
+      break;
+    }
+  }
+  if (!matched) {
+    return { valid: false, reason: 'bad_secret' };
+  }
+  if (isArray(requiredScopes) && requiredScopes.length > 0 && !hasAll(record.scopes, requiredScopes)) {
+    return { valid: false, reason: 'missing_scope' };
+  }
+  if (options.updateLastUsed === true) {
+    // Fire-and-forget on the store side — failure to bump lastUsedAt
+    // must not fail the verify itself. Await it so callers can wait
+    // for consistency if they want.
+    try {
+      await options.store.update(parsed.id, { lastUsedAt: now });
+    } catch {
+      // Ignore — lastUsedAt is telemetry, not correctness.
+    }
+  }
+
+  /** @type {VerifyApiKeyResult} */
+  const result = {
+    valid: true,
+    id: record.id,
+    userId: record.userId,
+    scopes: record.scopes,
+    prefix: record.prefix,
+  };
+  if (record.name) {
+    result.name = record.name;
+  }
+  if (record.environment) {
+    result.environment = record.environment;
+  }
+  if (record.metadata) {
+    result.metadata = record.metadata;
+  }
+  // Peppers rotate newest-first; non-zero index means the secret
+  // matched an older pepper — the storage hash should migrate.
+  if (peppers && matchedIndex > 0) {
+    result.needsRehash = true;
+  }
+  return result;
+}
+
+/**
+ * Revoke an API key by id or by the raw wire key. Returns `true` if
+ * a record was actually revoked, `false` if the id was unknown or
+ * the record was already revoked.
+ *
+ * @param {string} keyOrId    Either the raw wire key or its id half.
+ * @param {{ store: ApiKeyStore, reason?: string }} options
+ * @returns {Promise<boolean>}
+ */
+async function revokeApiKey(keyOrId, options) {
+  if (!isObject(options)) {
+    throw invalidArgument('revokeApiKey.options must be an object');
+  }
+  _assertStore(options.store, 'revokeApiKey.options.store');
+  const id = _asId(keyOrId);
+  if (!id) {
+    return false;
+  }
+  return options.store.revoke(id, options.reason);
+}
+
+/**
+ * Revoke every non-revoked key belonging to `userId`. Useful on
+ * password reset, account termination, etc. Returns the number of
+ * records actually revoked.
+ *
+ * @param {string} userId
+ * @param {{ store: ApiKeyStore, reason?: string }} options
+ * @returns {Promise<number>}
+ */
+async function revokeAllForUser(userId, options) {
+  if (!isObject(options)) {
+    throw invalidArgument('revokeAllForUser.options must be an object');
+  }
+  _assertStore(options.store, 'revokeAllForUser.options.store');
+  _requireString(userId, 'revokeAllForUser.userId');
+  return options.store.revokeAllForUser(userId, options.reason);
+}
+
+/**
+ * List every key belonging to `userId` — for a "manage API keys" UI.
+ * Callers should hide the storage `hash` before rendering; only the
+ * plaintext `id` is safe to display. Returns most-recently-used first
+ * (falling back to createdAt) so active keys float to the top.
+ *
+ * @param {string} userId
+ * @param {{ store: ApiKeyStore }} options
+ * @returns {Promise<ApiKeyRecord[]>}
+ */
+async function listApiKeys(userId, options) {
+  if (!isObject(options)) {
+    throw invalidArgument('listApiKeys.options must be an object');
+  }
+  _assertStore(options.store, 'listApiKeys.options.store');
+  _requireString(userId, 'listApiKeys.userId');
+  const rows = await options.store.listByUser(userId);
+  if (!isArray(rows)) {
+    return [];
+  }
+  return rows.slice().sort((a, b) => (b.lastUsedAt ?? b.createdAt) - (a.lastUsedAt ?? a.createdAt));
+}
+
+/**
+ * Migrate the storage hash of an existing key to the newest pepper.
+ * Requires the raw wire key (the plaintext secret is the input to the
+ * new HMAC). Called opportunistically when `verifyApiKey` reports
+ * `needsRehash: true`.
+ *
+ * @param {string} rawKey
+ * @param {{ store: ApiKeyStore, peppers: (Buffer | Uint8Array | string)[] }} options
+ * @returns {Promise<boolean>}
+ */
+async function rehashApiKey(rawKey, options) {
+  if (!isObject(options)) {
+    throw invalidArgument('rehashApiKey.options must be an object');
+  }
+  _assertStore(options.store, 'rehashApiKey.options.store');
+  const peppers = _normalizePeppers(options.peppers, 'rehashApiKey.options.peppers');
+  if (!peppers || peppers.length === 0) {
+    throw invalidArgument('rehashApiKey.options.peppers must be a non-empty array');
+  }
+  const parsed = parseApiKey(rawKey);
+  if (!parsed) {
+    return false;
+  }
+  const { candidateHashes } = candidateHashesFor(parsed.secret, [peppers[0]]);
+  const newHash = candidateHashes[0];
+  const updated = await options.store.update(parsed.id, { hash: newHash, pepperVersion: 0 });
+  return Boolean(updated);
+}
+
+// ---------------------------------------------------------------------
+// internals
+
+function _now(override) {
+  return isNumber(override) ? override : Date.now();
+}
+
+function _asId(keyOrId) {
+  if (!isString(keyOrId)) {
+    return null;
+  }
+  // If it looks like a full wire key, extract the id half; otherwise
+  // treat the string itself as an id.
+  const parsed = parseApiKey(keyOrId);
+  return parsed ? parsed.id : keyOrId;
+}
+
+function _requireString(v, name) {
+  if (!isString(v) || v.length === 0) {
+    throw invalidArgument(`${name} must be a non-empty string`);
+  }
+  return v;
+}
+
+function _assertStringOrUndef(v, name) {
+  if (!isUndefined(v) && !isString(v)) {
+    throw invalidArgument(`${name} must be a string when provided`);
+  }
+}
+
+function _isStringArray(v) {
+  if (!isArray(v)) {
+    return false;
+  }
+  for (const item of v) {
+    if (!isString(item)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function _requireStringArray(v, name) {
+  if (!_isStringArray(v) || v.length === 0) {
+    throw invalidArgument(`${name} must be a non-empty string[]`);
+  }
+  return v;
+}
+
+function _assertStore(v, name) {
+  if (
+    !isObject(v) ||
+    !isFunction(v.put) ||
+    !isFunction(v.getById) ||
+    !isFunction(v.update) ||
+    !isFunction(v.revoke) ||
+    !isFunction(v.revokeAllForUser) ||
+    !isFunction(v.listByUser)
+  ) {
+    throw invalidArgument(
+      `${name} must be an object with put / getById / update / revoke / revokeAllForUser / listByUser methods`,
+    );
+  }
+}
+
+function _normalizePeppers(input, name) {
+  if (isUndefined(input)) {
+    return null;
+  }
+  if (!isArray(input) || input.length === 0) {
+    throw new ApiKeyError(ErrorCode.INVALID_PEPPER, `${name} must be a non-empty array when provided (newest first)`);
+  }
+  const out = [];
+  for (let i = 0; i < input.length; i++) {
+    const p = input[i];
+    const buf = isString(p) ? Buffer.from(p, 'utf8') : isBytes(p) ? (isBuffer(p) ? p : Buffer.from(p)) : null;
+    if (!buf) {
+      throw new ApiKeyError(ErrorCode.INVALID_PEPPER, `${name}[${i}] must be a string / Buffer / Uint8Array`);
+    }
+    if (buf.length < MIN_PEPPER_BYTES) {
+      throw new ApiKeyError(
+        ErrorCode.INVALID_PEPPER,
+        `${name}[${i}] must be at least ${MIN_PEPPER_BYTES} bytes; got ${buf.length}`,
+      );
+    }
+    out.push(buf);
+  }
+  return out;
+}
+
+export { ApiKeyError, ErrorCode, covers, createApiKey, hasAll, hasAny, listApiKeys, mask, mask as maskApiKey, parseApiKey, rehashApiKey, revokeAllForUser, revokeApiKey, verifyApiKey };