@exortek/apikey 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @exortek/apikey
 
+## 1.2.0
+
+### Minor Changes
+
+- d370002: - `rehashApiKey` checks the presented secret against the stored hash before replacing it (anyone knowing a key id could overwrite its hash).
+  - `verifyApiKey` compares the secret before reporting `revoked` / `expired`, and accepts only the canonical spelling of a key (lowercase / I / O variants no longer verify).
+
+### Patch Changes
+
+- 9953042: - Duration strings whose unit is the name of an `Object.prototype` member (for example `'1constructor'`) now throw instead of resolving to `NaN`.
+- 9953042: - When a record is stored again under the same id with a different owner (`userId` / `email`), the previous owner no longer lists it, and per-owner bulk revocation (`revokeAllForUser`, `revokeByEmail`) no longer reaches it.
+
+## 1.1.3
+
+### Patch Changes
+
+- 89aea87: Ship self-contained TypeScript declarations. Every package's emitted `.d.ts` referenced `@exortek/shared`
+  (e.g. `import { BaseError } from '@exortek/shared/errors'`), but `@exortek/shared` is a private, never-published
+  workspace package that is inlined into each bundle at build time. A TypeScript consumer therefore hit
+  `Cannot find module '@exortek/shared/…'` (with `skipLibCheck` off) or silently degraded error-class types like
+  `ApiKeyError` — losing its constructor signature and `.code` / `.message` — with `skipLibCheck` on.
+
+  The build now runs a declaration-bundling pass (`rollup-plugin-dts`) after `tsc`, flattening each entry's `.d.ts` and
+  inlining the `@exortek/shared` types so the shipped declarations are fully self-contained. Runtime deps and `node:*`
+  stay external. No runtime or API change — types only.
+
 ## 1.1.2
 
 ### Patch Changes

package/dist/index.cjs

@@ -107,11 +107,13 @@ function parseDuration(input) {
   }
   const value = Number(match[1]);
   const unit = (match[2] || 'ms').toLowerCase();
-  const multiplier = UNIT_MS[/** @type {keyof typeof UNIT_MS} */ (unit)];
-  if (multiplier === undefined) {
+  // Own keys only: a plain lookup would resolve `constructor` (and every
+  // other Object.prototype member) to a function, turning '1constructor'
+  // into NaN instead of an error.
+  if (!Object.hasOwn(UNIT_MS, unit)) {
     throw new Error(`parseDuration: unknown time unit ${JSON.stringify(unit)}. Supported: ${SUPPORTED_UNITS}.`);
   }
-  return Math.round(value * multiplier);
+  return Math.round(value * UNIT_MS[/** @type {keyof typeof UNIT_MS} */ (unit)]);
 }
 
 /**
@@ -887,6 +889,12 @@ function candidateHashesFor(rawSecret, peppers) {
   } catch {
     return { candidateHashes: [] };
   }
+  // Crockford decoding is forgiving (case, I/L→1, O→0), so one secret has
+  // many accepted spellings. A key must have exactly one: anything keyed on
+  // the wire string (logs, deny lists, dedupe) would otherwise miss variants.
+  if (encode(secretBytes) !== rawSecret) {
+    return { candidateHashes: [] };
+  }
   if (!peppers || peppers.length === 0) {
     return { candidateHashes: [hashSecret(secretBytes, null)] };
   }
@@ -1130,19 +1138,15 @@ async function verifyApiKey(rawKey, options) {
   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' };
   }
+  // The secret is checked before lifecycle state: the id is not secret (it
+  // is in every masked key), so answering 'revoked' / 'expired' first
+  // would tell anyone holding an id the key's status without its secret.
   const { candidateHashes } = candidateHashesFor(parsed.secret, peppers);
   let matched = false;
   let matchedIndex = -1;
@@ -1156,6 +1160,13 @@ async function verifyApiKey(rawKey, options) {
   if (!matched) {
     return { valid: false, reason: 'bad_secret' };
   }
+  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 (isArray(requiredScopes) && requiredScopes.length > 0 && !hasAll(record.scopes, requiredScopes)) {
     return { valid: false, reason: 'missing_scope' };
   }
@@ -1280,6 +1291,17 @@ async function rehashApiKey(rawKey, options) {
   if (!parsed) {
     return false;
   }
+  // Prove the caller holds the real secret before replacing its hash —
+  // otherwise anyone who knows a key id (it is in every masked key) could
+  // overwrite that key's hash with one for a secret of their choosing.
+  const record = await options.store.getById(parsed.id);
+  if (!record) {
+    return false;
+  }
+  const { candidateHashes: existing } = candidateHashesFor(parsed.secret, peppers);
+  if (!existing.some(candidate => hashesMatch(candidate, record.hash))) {
+    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 });

package/dist/index.d.ts

@@ -1,3 +1,131 @@
+/**
+ * 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}
+ */
+declare function parseApiKey(key: string): {
+    prefix: string;
+    id: string;
+    secret: string;
+} | null;
+/**
+ * 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}
+ */
+declare function mask(key: string): string;
+
+/**
+ * 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.
+ */
+declare 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: Record<string, number> | undefined;
+    /**
+     * Fallback status for codes missing from `statuses`.
+     *
+     * @type {number}
+     */
+    static defaultStatus: number;
+    /**
+     * @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: string, message: string, options?: {
+        cause?: unknown;
+        status?: number;
+        details?: Record<string, unknown>;
+    });
+    /** @type {string} */
+    code: string;
+    /** @type {number | undefined} */
+    status: number | undefined;
+    /** @type {Record<string, unknown> | undefined} */
+    details: Record<string, unknown> | undefined;
+}
+
+declare const ErrorCode: Readonly<{
+    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.
+ */
+declare class ApiKeyError extends BaseError {
+    static statuses: {
+        INVALID_ARGUMENT: number;
+        INVALID_PREFIX: number;
+        INVALID_PEPPER: number;
+        STORE_ERROR: number;
+    };
+}
+
+/**
+ * Does `granted` cover a single `required` scope?
+ * @param {string[]} granted
+ * @param {string} required
+ * @returns {boolean}
+ */
+declare function covers(granted: string[], required: string): boolean;
+/**
+ * All required scopes must be covered by granted.
+ * @param {string[]} granted
+ * @param {string[]} required
+ * @returns {boolean}
+ */
+declare function hasAll(granted: string[], required: string[]): boolean;
+/**
+ * At least one required scope must be covered.
+ * @param {string[]} granted
+ * @param {string[]} required
+ * @returns {boolean}
+ */
+declare function hasAny(granted: string[], required: string[]): boolean;
+
 /**
  * @typedef {object} ApiKeyRecord
  * @property {string} id                      Plaintext lookup key (128-bit b64u).
@@ -80,7 +208,7 @@
  * @param {CreateApiKeyOptions} options
  * @returns {Promise<CreateApiKeyResult>}
  */
-export function createApiKey(options: CreateApiKeyOptions): Promise<CreateApiKeyResult>;
+declare function createApiKey(options: CreateApiKeyOptions): Promise<CreateApiKeyResult>;
 /**
  * Verify a raw API key. Returns `{ valid: true, ... }` on success, or
  * `{ valid: false, reason }` on any expected failure. Never throws on
@@ -96,7 +224,7 @@ export function createApiKey(options: CreateApiKeyOptions): Promise<CreateApiKey
  * @param {VerifyApiKeyOptions} options
  * @returns {Promise<VerifyApiKeyResult>}
  */
-export function verifyApiKey(rawKey: string, options: VerifyApiKeyOptions): Promise<VerifyApiKeyResult>;
+declare function verifyApiKey(rawKey: string, options: VerifyApiKeyOptions): Promise<VerifyApiKeyResult>;
 /**
  * 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
@@ -106,7 +234,7 @@ export function verifyApiKey(rawKey: string, options: VerifyApiKeyOptions): Prom
  * @param {{ store: ApiKeyStore, reason?: string }} options
  * @returns {Promise<boolean>}
  */
-export function revokeApiKey(keyOrId: string, options: {
+declare function revokeApiKey(keyOrId: string, options: {
     store: ApiKeyStore;
     reason?: string;
 }): Promise<boolean>;
@@ -119,7 +247,7 @@ export function revokeApiKey(keyOrId: string, options: {
  * @param {{ store: ApiKeyStore, reason?: string }} options
  * @returns {Promise<number>}
  */
-export function revokeAllForUser(userId: string, options: {
+declare function revokeAllForUser(userId: string, options: {
     store: ApiKeyStore;
     reason?: string;
 }): Promise<number>;
@@ -133,7 +261,7 @@ export function revokeAllForUser(userId: string, options: {
  * @param {{ store: ApiKeyStore }} options
  * @returns {Promise<ApiKeyRecord[]>}
  */
-export function listApiKeys(userId: string, options: {
+declare function listApiKeys(userId: string, options: {
     store: ApiKeyStore;
 }): Promise<ApiKeyRecord[]>;
 /**
@@ -146,12 +274,12 @@ export function listApiKeys(userId: string, options: {
  * @param {{ store: ApiKeyStore, peppers: (Buffer | Uint8Array | string)[] }} options
  * @returns {Promise<boolean>}
  */
-export function rehashApiKey(rawKey: string, options: {
+declare function rehashApiKey(rawKey: string, options: {
     store: ApiKeyStore;
     peppers: (Buffer | Uint8Array | string)[];
 }): Promise<boolean>;
-export { maskKey as maskApiKey };
-export type ApiKeyRecord = {
+
+type ApiKeyRecord = {
     /**
      * Plaintext lookup key (128-bit b64u).
      */
@@ -197,7 +325,7 @@ export type ApiKeyRecord = {
      */
     pepperVersion?: number | undefined;
 };
-export type ApiKeyStore = {
+type ApiKeyStore = {
     put: (record: ApiKeyRecord) => Promise<void>;
     getById: (id: string) => Promise<ApiKeyRecord | null>;
     update: (id: string, patch: Partial<ApiKeyRecord>) => Promise<ApiKeyRecord | null>;
@@ -205,7 +333,7 @@ export type ApiKeyStore = {
     revokeAllForUser: (userId: string, reason?: string) => Promise<number>;
     listByUser: (userId: string) => Promise<ApiKeyRecord[]>;
 };
-export type CreateApiKeyOptions = {
+type CreateApiKeyOptions = {
     /**
      * Stripe-style; `sk_live`, `pk_test`, `svc_prod_v2`.
      */
@@ -229,7 +357,7 @@ export type CreateApiKeyOptions = {
      */
     now?: number | undefined;
 };
-export type CreateApiKeyResult = {
+type CreateApiKeyResult = {
     /**
      * Wire token — show ONCE to the caller and never again.
      */
@@ -243,7 +371,7 @@ export type CreateApiKeyResult = {
      */
     record: ApiKeyRecord;
 };
-export type VerifyApiKeyOptions = {
+type VerifyApiKeyOptions = {
     store: ApiKeyStore;
     peppers?: any[] | undefined;
     requiredScopes?: string[] | undefined;
@@ -257,8 +385,8 @@ export type VerifyApiKeyOptions = {
     updateLastUsed?: boolean | undefined;
     now?: number | undefined;
 };
-export type VerifyApiKeyFailureReason = "malformed" | "not_found" | "expired" | "revoked" | "bad_secret" | "prefix_mismatch" | "missing_scope" | "store_unavailable";
-export type VerifyApiKeyResult = {
+type VerifyApiKeyFailureReason = "malformed" | "not_found" | "expired" | "revoked" | "bad_secret" | "prefix_mismatch" | "missing_scope" | "store_unavailable";
+type VerifyApiKeyResult = {
     valid: true;
     id: string;
     userId: string;
@@ -272,7 +400,6 @@ export type VerifyApiKeyResult = {
     valid: false;
     reason: VerifyApiKeyFailureReason;
 };
-import { mask as maskKey } from './token.js';
-export { ApiKeyError, ErrorCode } from "./errors.js";
-export { covers, hasAll, hasAny } from "./scopes.js";
-export { parseApiKey, mask } from "./token.js";
+
+export { ApiKeyError, ErrorCode, covers, createApiKey, hasAll, hasAny, listApiKeys, mask, mask as maskApiKey, parseApiKey, rehashApiKey, revokeAllForUser, revokeApiKey, verifyApiKey };
+export type { ApiKeyRecord, ApiKeyStore, CreateApiKeyOptions, CreateApiKeyResult, VerifyApiKeyFailureReason, VerifyApiKeyOptions, VerifyApiKeyResult };

package/dist/index.mjs

@@ -105,11 +105,13 @@ function parseDuration(input) {
   }
   const value = Number(match[1]);
   const unit = (match[2] || 'ms').toLowerCase();
-  const multiplier = UNIT_MS[/** @type {keyof typeof UNIT_MS} */ (unit)];
-  if (multiplier === undefined) {
+  // Own keys only: a plain lookup would resolve `constructor` (and every
+  // other Object.prototype member) to a function, turning '1constructor'
+  // into NaN instead of an error.
+  if (!Object.hasOwn(UNIT_MS, unit)) {
     throw new Error(`parseDuration: unknown time unit ${JSON.stringify(unit)}. Supported: ${SUPPORTED_UNITS}.`);
   }
-  return Math.round(value * multiplier);
+  return Math.round(value * UNIT_MS[/** @type {keyof typeof UNIT_MS} */ (unit)]);
 }
 
 /**
@@ -885,6 +887,12 @@ function candidateHashesFor(rawSecret, peppers) {
   } catch {
     return { candidateHashes: [] };
   }
+  // Crockford decoding is forgiving (case, I/L→1, O→0), so one secret has
+  // many accepted spellings. A key must have exactly one: anything keyed on
+  // the wire string (logs, deny lists, dedupe) would otherwise miss variants.
+  if (encode(secretBytes) !== rawSecret) {
+    return { candidateHashes: [] };
+  }
   if (!peppers || peppers.length === 0) {
     return { candidateHashes: [hashSecret(secretBytes, null)] };
   }
@@ -1128,19 +1136,15 @@ async function verifyApiKey(rawKey, options) {
   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' };
   }
+  // The secret is checked before lifecycle state: the id is not secret (it
+  // is in every masked key), so answering 'revoked' / 'expired' first
+  // would tell anyone holding an id the key's status without its secret.
   const { candidateHashes } = candidateHashesFor(parsed.secret, peppers);
   let matched = false;
   let matchedIndex = -1;
@@ -1154,6 +1158,13 @@ async function verifyApiKey(rawKey, options) {
   if (!matched) {
     return { valid: false, reason: 'bad_secret' };
   }
+  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 (isArray(requiredScopes) && requiredScopes.length > 0 && !hasAll(record.scopes, requiredScopes)) {
     return { valid: false, reason: 'missing_scope' };
   }
@@ -1278,6 +1289,17 @@ async function rehashApiKey(rawKey, options) {
   if (!parsed) {
     return false;
   }
+  // Prove the caller holds the real secret before replacing its hash —
+  // otherwise anyone who knows a key id (it is in every masked key) could
+  // overwrite that key's hash with one for a secret of their choosing.
+  const record = await options.store.getById(parsed.id);
+  if (!record) {
+    return false;
+  }
+  const { candidateHashes: existing } = candidateHashesFor(parsed.secret, peppers);
+  if (!existing.some(candidate => hashesMatch(candidate, record.hash))) {
+    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 });

package/dist/middleware/express.cjs

@@ -389,7 +389,7 @@ const ALPHABET$1 = /^[A-Za-z0-9_-]*$/;
  * @param {Buffer | Uint8Array} bytes
  * @returns {string}
  */
-function encode(bytes) {
+function encode$1(bytes) {
   if (bytes == null || (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array))) {
     throw new TypeError('base64url.encode: expected Buffer or Uint8Array');
   }
@@ -453,6 +453,39 @@ for (const [alias, canonical] of [
   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.
  *
@@ -612,7 +645,7 @@ function hashSecret(secretBytes, pepper) {
   const digest = pepper
     ? node_crypto.createHmac('sha256', pepper).update(secretBytes).digest()
     : node_crypto.createHash('sha256').update(secretBytes).digest();
-  return encode(digest);
+  return encode$1(digest);
 }
 
 /**
@@ -704,6 +737,12 @@ function candidateHashesFor(rawSecret, peppers) {
   } catch {
     return { candidateHashes: [] };
   }
+  // Crockford decoding is forgiving (case, I/L→1, O→0), so one secret has
+  // many accepted spellings. A key must have exactly one: anything keyed on
+  // the wire string (logs, deny lists, dedupe) would otherwise miss variants.
+  if (encode(secretBytes) !== rawSecret) {
+    return { candidateHashes: [] };
+  }
   if (!peppers || peppers.length === 0) {
     return { candidateHashes: [hashSecret(secretBytes, null)] };
   }
@@ -774,19 +813,15 @@ async function verifyApiKey(rawKey, options) {
   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' };
   }
+  // The secret is checked before lifecycle state: the id is not secret (it
+  // is in every masked key), so answering 'revoked' / 'expired' first
+  // would tell anyone holding an id the key's status without its secret.
   const { candidateHashes } = candidateHashesFor(parsed.secret, peppers);
   let matched = false;
   let matchedIndex = -1;
@@ -800,6 +835,13 @@ async function verifyApiKey(rawKey, options) {
   if (!matched) {
     return { valid: false, reason: 'bad_secret' };
   }
+  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 (isArray(requiredScopes) && requiredScopes.length > 0 && !hasAll(record.scopes, requiredScopes)) {
     return { valid: false, reason: 'missing_scope' };
   }

package/dist/middleware/express.d.ts

@@ -1,4 +1,99 @@
+type ApiKeyRecord = {
+    /**
+     * Plaintext lookup key (128-bit b64u).
+     */
+    id: string;
+    /**
+     * Storage hash of the secret (43-char b64u).
+     */
+    hash: string;
+    /**
+     * The prefix the key was minted with.
+     */
+    prefix: string;
+    userId: string;
+    scopes: string[];
+    /**
+     * Human label ("Production Backend").
+     */
+    name?: string | undefined;
+    /**
+     * `'live'` / `'test'` / caller-defined.
+     */
+    environment?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    /**
+     * ms epoch.
+     */
+    createdAt: number;
+    /**
+     * ms epoch; absent = no expiry.
+     */
+    expiresAt?: number | undefined;
+    /**
+     * ms epoch when the record was revoked.
+     */
+    revokedAt?: number | undefined;
+    revokedReason?: string | undefined;
+    /**
+     * ms epoch of the last successful verify.
+     */
+    lastUsedAt?: number | undefined;
+    /**
+     * Index into the peppers array that was used at mint. 0 = newest.
+     */
+    pepperVersion?: number | undefined;
+};
+type ApiKeyStore = {
+    put: (record: ApiKeyRecord) => Promise<void>;
+    getById: (id: string) => Promise<ApiKeyRecord | null>;
+    update: (id: string, patch: Partial<ApiKeyRecord>) => Promise<ApiKeyRecord | null>;
+    revoke: (id: string, reason?: string) => Promise<boolean>;
+    revokeAllForUser: (userId: string, reason?: string) => Promise<number>;
+    listByUser: (userId: string) => Promise<ApiKeyRecord[]>;
+};
+
+type AdapterContext = {
+    getHeader: (name: string) => string | undefined;
+    method?: string | undefined;
+    ip?: string | undefined;
+    query?: Record<string, unknown> | undefined;
+};
+type ApiKeyMiddlewareOptions = {
+    store: ApiKeyStore;
+    peppers?: any[] | undefined;
+    requiredScopes?: string[] | undefined;
+    expectedPrefix?: string | undefined;
+    updateLastUsed?: boolean | undefined;
+    /**
+     * Case-insensitive. The default reads `Authorization: Bearer <key>`;
+     * a `x-api-key` config reads `X-API-Key: <key>` directly.
+     */
+    headerName?: string | undefined;
+    /**
+     * `'bearer'` expects `Bearer <key>`; `'raw'` uses the header value as-is.
+     */
+    scheme?: "bearer" | "raw" | undefined;
+    /**
+     * When true, falls back to `?api_key=<key>` if no matching header is
+     * found. Discouraged because query strings leak into access logs and
+     * referer headers — off by default.
+     */
+    allowQueryParam?: boolean | undefined;
+    queryParamName?: string | undefined;
+    /**
+     * Property name attached to the request object on success.
+     */
+    attach?: string | undefined;
+    /**
+     * Override the default extraction entirely.
+     */
+    tokenFromRequest?: ((ctx: AdapterContext) => string | undefined) | undefined;
+};
+
 /**
  * @param {import('./core.js').ApiKeyMiddlewareOptions} options
  */
-export function apiKeyMiddleware(options: import("./core.js").ApiKeyMiddlewareOptions): (req: any, res: any, next: any) => Promise<any>;
+declare function apiKeyMiddleware(options: ApiKeyMiddlewareOptions): (req: any, res: any, next: any) => Promise<any>;
+
+export { apiKeyMiddleware };