@exortek/apikey 1.0.0

package/dist/middleware/fastify.cjs

@@ -0,0 +1,1374 @@
+'use strict';
+
+var fp = require('fastify-plugin');
+var node_crypto = require('node:crypto');
+
+/**
+ * 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);
+}
+
+/**
+ * Imperative single-argument guard helpers — the everyday
+ * `assertPositiveInt(x, 'name')` shape used at API boundaries.
+ * Companion to the compound schema builder in
+ * `@exortek/shared/validate`: **schema** for whole options objects,
+ * **asserts** for one-liner argument guards at the call site.
+ *
+ * The consumer surface is {@link defineGuards} (or the raw
+ * {@link bindAsserts} for full control). Each package binds the assert
+ * set to its own typed error class once (in `internal/guards.js`), so
+ * every argument failure throws that package's class —
+ * `err instanceof CryptoError` holds and users see at a glance which
+ * package raised the error. The bound `parse` bridges
+ * `@exortek/shared/validate` schemas to the same error class.
+ *
+ * **Path naming convention** (used as the `name` argument):
+ *
+ *   `<publicFunction>[.options|.config][.<field>]`
+ *
+ *   - `assertString(name, 'createUser.name')`          — top-level arg
+ *   - `assertPositiveInt(n, 'scrypt.options.r')`       — nested option
+ *   - `assertBytesOrString(pwd, 'pepper.wrap.password')` — method arg
+ *
+ * Keep the path short: the emitted error is `"<name> must be <desc>"`,
+ * so a stack-line grep already tells the caller which function fired.
+ * Reserve `hint` for actionable follow-ups ("pass the bytes returned by
+ * encryptSymmetric()"), not for restating the field.
+ */
+
+/**
+ * @typedef {{ cause?: unknown }} WrapExtra
+ *   Extra options forwarded to the wrap function, so `invalidArgument`
+ *   sites that catch an underlying error can preserve the `cause` chain
+ *   without falling back to a raw `new PackageError(...)`.
+ *
+ * @typedef {(message: string, extra?: WrapExtra) => Error} WrapFn
+ *   Constructs (never throws) the binding package's error, e.g.
+ *   `(m, { cause } = {}) => new CryptoError(ErrorCode.INVALID_ARGUMENT, m, { cause })`.
+ *
+ * @typedef {{ hint?: string }} AssertOptions
+ *   `hint` is appended to the message after an em-dash — use it for
+ *   actionable guidance ("pass the exact bytes returned by …").
+ *
+ * @typedef {{ safeParse: (input: unknown, path?: string) => { ok: true, value: unknown } | { ok: false, errors: string[] } }} ParseableSchema
+ */
+
+/**
+ * Build the failure message. `description` completes the sentence
+ * `"<name> must be <description>"`; `hint` (optional) follows an
+ * em-dash.
+ *
+ * @param {string} name
+ * @param {string} description
+ * @param {string} [hint]
+ * @returns {string}
+ */
+function message(name, description, hint) {
+  return `${name} must be ${description}${hint ? ` — ${hint}` : ''}`;
+}
+
+const ENCODINGS = new Set(['hex', 'base64', 'base64url']);
+
+/**
+ * Bind the assert set to a package's error class. Call once per
+ * package (conventionally in `internal/guards.js`) and import the
+ * bound object everywhere:
+ *
+ *   import { bindAsserts } from '@exortek/shared/asserts';
+ *   import { CryptoError, ErrorCode } from '../errors.js';
+ *   export const g = bindAsserts((m) => new CryptoError(ErrorCode.INVALID_ARGUMENT, m));
+ *
+ *   // call sites:
+ *   g.assertPositiveInt(options.iterations, 'options.iterations');
+ *   const cfg = g.parse(OptionsSchema, options, 'options');
+ *
+ * @param {WrapFn} wrap
+ */
+function bindAsserts(wrap) {
+  /**
+   * @param {string} name
+   * @param {string} description
+   * @param {AssertOptions} [opts]
+   * @returns {never}
+   */
+  function fail(name, description, opts) {
+    throw wrap(message(name, description, opts?.hint));
+  }
+
+  /**
+   * Assert that `value` is a plain object (not `null`, not an array,
+   * not a primitive).
+   * @param {unknown} value
+   * @param {string}  name
+   * @param {AssertOptions} [opts]
+   */
+  function assertObject(value, name, opts) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      fail(name, 'an object', opts);
+    }
+  }
+
+  return {
+    /**
+     * Construct (not throw) the bound error with a free-form message —
+     * for `throw g.invalidArgument('…')` sites that don't fit the
+     * `X must be Y` shape (canonicalisation errors, cross-field
+     * constraint failures). Pass `{ cause }` when the argument-shape
+     * failure was triggered by an underlying throw whose chain matters
+     * (e.g. `JSON.stringify` on a bigint).
+     *
+     * @param {string} msg
+     * @param {WrapExtra} [extra]
+     * @returns {Error}
+     */
+    invalidArgument(msg, extra) {
+      return wrap(msg, extra);
+    },
+
+    /**
+     * Validate `input` against a `@exortek/shared/validate` schema;
+     * failures throw the bound error carrying every collected message.
+     * The bridge that keeps schema validation on the package's own
+     * error surface.
+     *
+     * @param {ParseableSchema} schema
+     * @param {unknown} input
+     * @param {string} [path='options']
+     * @returns {unknown} the parsed (possibly defaulted) value
+     */
+    parse(schema, input, path = 'options') {
+      const r = schema.safeParse(input, path);
+      if (!r.ok) {
+        throw wrap(r.errors.join('; '));
+      }
+      return r.value;
+    },
+
+    /**
+     * Assert that `value` is a non-negative safe integer (`0, 1, 2, …`).
+     * @param {unknown} value
+     * @param {string}  name  Argument name to include in the error message.
+     * @param {AssertOptions} [opts]
+     */
+    assertNonNegativeInt(value, name, opts) {
+      if (!Number.isSafeInteger(value) || /** @type {number} */ (value) < 0) {
+        fail(name, 'a non-negative safe integer', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` is a strictly positive safe integer (`1, 2, 3, …`).
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertPositiveInt(value, name, opts) {
+      if (!Number.isSafeInteger(value) || /** @type {number} */ (value) <= 0) {
+        fail(name, 'a positive integer', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` fits in a 48-bit unsigned integer (`0 … 2^48 − 1`).
+     * Used for Unix millisecond timestamps in UUID v7 / ULID.
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertUint48(value, name, opts) {
+      if (
+        !Number.isSafeInteger(value) ||
+        /** @type {number} */ (value) < 0 ||
+        /** @type {number} */ (value) > 0xffffffffffff
+      ) {
+        fail(name, 'a non-negative safe integer ≤ 2^48 − 1 (Unix ms since epoch)', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` is a string (may be empty).
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertString(value, name, opts) {
+      if (typeof value !== 'string') {
+        fail(name, 'a string', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` is a non-empty string.
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertNonEmptyString(value, name, opts) {
+      if (typeof value !== 'string' || value.length === 0) {
+        fail(name, 'a non-empty string', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` is a boolean.
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertBoolean(value, name, opts) {
+      if (typeof value !== 'boolean') {
+        fail(name, 'a boolean', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` is a function.
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertFunction(value, name, opts) {
+      if (typeof value !== 'function') {
+        fail(name, 'a function', opts);
+      }
+    },
+
+    assertObject,
+
+    /**
+     * Assert that `value` is either `undefined` or a plain object —
+     * the "optional options object" pattern.
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertOptionalObject(value, name, opts) {
+      if (value === undefined) {
+        return;
+      }
+      assertObject(value, name, opts);
+    },
+
+    /**
+     * Assert that `value` is a byte buffer (`Buffer` or `Uint8Array`) —
+     * strings are NOT accepted. For already-encoded material where a
+     * string would be ambiguous (ciphertext, signatures, raw key bytes).
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertBytes(value, name, opts) {
+      if (!Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+        fail(name, 'a Buffer or Uint8Array', opts);
+      }
+    },
+
+    /**
+     * Assert that `value` is either a string or a byte buffer (`Buffer`
+     * or `Uint8Array`).
+     * @param {unknown} value
+     * @param {string}  name
+     * @param {AssertOptions} [opts]
+     */
+    assertBytesOrString(value, name, opts) {
+      if (typeof value !== 'string' && !Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+        fail(name, 'a string or Buffer', opts);
+      }
+    },
+
+    /**
+     * Assert that `encoding` is one of the accepted output/input
+     * encodings. Pass `allowBuffer: false` where a `Buffer` output makes
+     * no sense (verifying a string signature, decoding a token payload).
+     *
+     * @param {unknown} encoding
+     * @param {string}  name
+     * @param {AssertOptions & { allowBuffer?: boolean }} [opts]
+     */
+    assertEncoding(encoding, name, opts) {
+      const allowBuffer = opts?.allowBuffer !== false;
+      const valid = (typeof encoding === 'string' && ENCODINGS.has(encoding)) || (allowBuffer && encoding === 'buffer');
+      if (!valid) {
+        const list = allowBuffer ? "'hex', 'base64', 'base64url', or 'buffer'" : "'hex', 'base64', or 'base64url'";
+        fail(name, list, opts);
+      }
+    },
+  };
+}
+
+/**
+ * One-line sugar over {@link bindAsserts} — the overwhelmingly common
+ * pattern where a package binds every argument-shape failure to its
+ * own error class + `INVALID_ARGUMENT` code. Emits the standard
+ * `new ErrorClass(code, message, { cause })` shape, so the underlying
+ * `BaseError` `{ cause, status, details }` options object is respected.
+ *
+ *   // packages/<pkg>/src/internal/guards.js
+ *   import { defineGuards } from '@exortek/shared/asserts';
+ *   import { PasswordError, ErrorCode } from '../errors.js';
+ *
+ *   export const { assertString, invalidArgument, parse } =
+ *     defineGuards(PasswordError, ErrorCode.INVALID_ARGUMENT);
+ *
+ * Reach for the raw {@link bindAsserts} when you need a different
+ * mapping (an alt code, a decorated message) — it stays available.
+ *
+ * @param {new (code: string, message: string, options?: { cause?: unknown }) => Error} ErrorClass
+ * @param {string} code
+ */
+function defineGuards(ErrorClass, code) {
+  return bindAsserts((message, extra) => new ErrorClass(code, message, extra));
+}
+
+/**
+ * Shared base error class — the single error structure behind every
+ * `@exortek/*` package's `errors.js`.
+ *
+ * Every package keeps its own class identity with a one-liner subclass;
+ * codes stay per-package frozen maps, status mapping is declared as a
+ * static field:
+ *
+ *   import { BaseError } from '@exortek/shared/errors';
+ *
+ *   export const ErrorCode = Object.freeze({
+ *     INVALID_ARGUMENT: 'INVALID_ARGUMENT',
+ *     INVALID_TOKEN: 'INVALID_TOKEN',
+ *   });
+ *
+ *   export class JwtError extends BaseError {
+ *     static statuses = { INVALID_ARGUMENT: 400, INVALID_TOKEN: 401 };
+ *     static defaultStatus = 500;
+ *   }
+ *
+ * Instances carry a stable machine-readable `code` (branch on this,
+ * never on the message), an optional HTTP `status`, an optional
+ * `details` object, and the standard `cause` chain.
+ */
+class BaseError extends Error {
+  /**
+   * Optional `code → HTTP status` map declared on the subclass. When
+   * absent the instance carries no `status` at all — for HTTP-agnostic
+   * packages like `@exortek/crypto`.
+   *
+   * @type {Record<string, number> | undefined}
+   */
+  static statuses = undefined;
+
+  /**
+   * Fallback status for codes missing from `statuses`.
+   *
+   * @type {number}
+   */
+  static defaultStatus = 500;
+
+  /**
+   * @param {string} code    Stable machine-readable code; branch on this.
+   * @param {string} message Human-readable diagnostic. Free-form; may
+   *                         change across versions.
+   * @param {{ cause?: unknown, status?: number, details?: Record<string, unknown> }} [options]
+   */
+  constructor(code, message, options = {}) {
+    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+    this.name = new.target.name;
+    /** @type {string} */
+    this.code = code;
+    const statuses = /** @type {typeof BaseError} */ (new.target).statuses;
+    if (options.status !== undefined) {
+      /** @type {number | undefined} */
+      this.status = options.status;
+    } else if (statuses !== undefined) {
+      // Object.hasOwn guards against inherited-property lookups for
+      // exotic code values ('toString', 'constructor', …).
+      this.status = Object.hasOwn(statuses, code)
+        ? statuses[code]
+        : /** @type {typeof BaseError} */ (new.target).defaultStatus;
+    }
+    if (options.details) {
+      /** @type {Record<string, unknown> | undefined} */
+      this.details = options.details;
+    }
+  }
+}
+
+/**
+ * Stable machine-readable codes for every programmer-error failure that
+ * `@exortek/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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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(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)];
+}
+
+/**
+ * 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.
+    node_crypto.timingSafeEqual(aBuf, aBuf);
+    return false;
+  }
+  return node_crypto.timingSafeEqual(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.
+ */
+
+
+// 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;
+}
+
+/**
+ * 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
+    ? node_crypto.createHmac('sha256', pepper).update(secretBytes).digest()
+    : node_crypto.createHash('sha256').update(secretBytes).digest();
+  return encode(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)),
+  };
+}
+
+/**
+ * `@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;
+
+/**
+ * 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;
+}
+
+// ---------------------------------------------------------------------
+// internals
+
+function _now(override) {
+  return isNumber(override) ? override : Date.now();
+}
+
+function _isStringArray(v) {
+  if (!isArray(v)) {
+    return false;
+  }
+  for (const item of v) {
+    if (!isString(item)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+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;
+}
+
+/**
+ * Adapter-kit core for `@exortek/apikey` middleware.
+ *
+ * The framework-neutral logic lives here. The Express and Fastify
+ * adapters (`middleware/express.js`, `middleware/fastify.js`) are
+ * thin translators: request → `AdapterContext`, then hand off to
+ * `runApiKey`, then translate the returned `AdapterResult` back into
+ * the framework's own reply / next call.
+ *
+ * External integrators writing their own framework binding only need
+ * to implement the two-line translation — every auth decision,
+ * error-code, and header choice already lives here.
+ */
+
+
+/**
+ * @typedef {object} AdapterContext
+ * @property {(name: string) => string | undefined} getHeader
+ * @property {string} [method]
+ * @property {string} [ip]
+ * @property {Record<string, unknown>} [query]
+ */
+
+/**
+ * @typedef {object} ApiKeyMiddlewareOptions
+ * @property {import('../index.js').ApiKeyStore} store
+ * @property {(Buffer | Uint8Array | string)[]} [peppers]
+ * @property {string[]} [requiredScopes]
+ * @property {string} [expectedPrefix]
+ * @property {boolean} [updateLastUsed=false]
+ * @property {string} [headerName='authorization']
+ *   Case-insensitive. The default reads `Authorization: Bearer <key>`;
+ *   a `x-api-key` config reads `X-API-Key: <key>` directly.
+ * @property {'bearer' | 'raw'} [scheme='bearer']
+ *   `'bearer'` expects `Bearer <key>`; `'raw'` uses the header value as-is.
+ * @property {boolean} [allowQueryParam=false]
+ *   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.
+ * @property {string} [queryParamName='api_key']
+ * @property {string} [attach='apiKey']
+ *   Property name attached to the request object on success.
+ * @property {(ctx: AdapterContext) => string | undefined} [tokenFromRequest]
+ *   Override the default extraction entirely.
+ */
+
+/**
+ * @typedef {{
+ *   verifyResult: import('../index.js').VerifyApiKeyResult,
+ *   response?: { status: number, body: { error: string, reason?: string } }
+ * }} AdapterResult
+ */
+
+const DEFAULT_HEADER = 'authorization';
+const DEFAULT_QUERY = 'api_key';
+
+/**
+ * Normalize + validate middleware options. Throws `ApiKeyError` on
+ * misconfig so the mistake surfaces at boot, not per-request.
+ *
+ * @param {ApiKeyMiddlewareOptions} options
+ */
+function normalizeOptions(options) {
+  if (!options || typeof options !== 'object') {
+    throw invalidArgument('apiKey middleware options must be an object');
+  }
+  if (!options.store) {
+    throw invalidArgument('apiKey middleware options.store is required');
+  }
+  if (!isUndefined(options.tokenFromRequest) && !isFunction(options.tokenFromRequest)) {
+    throw invalidArgument('apiKey middleware options.tokenFromRequest must be a function when provided');
+  }
+  const attach = options.attach ?? 'apiKey';
+  if (!isString(attach) || attach.length === 0) {
+    throw invalidArgument('apiKey middleware options.attach must be a non-empty string');
+  }
+  return {
+    store: options.store,
+    peppers: options.peppers,
+    requiredScopes: options.requiredScopes,
+    expectedPrefix: options.expectedPrefix,
+    updateLastUsed: options.updateLastUsed === true,
+    headerName: (options.headerName ?? DEFAULT_HEADER).toLowerCase(),
+    scheme: options.scheme ?? 'bearer',
+    allowQueryParam: options.allowQueryParam === true,
+    queryParamName: options.queryParamName ?? DEFAULT_QUERY,
+    attach,
+    tokenFromRequest: options.tokenFromRequest,
+  };
+}
+
+/**
+ * Extract the raw key from a request context per the configured
+ * scheme. Returns `null` when no candidate was found (the caller then
+ * responds with 401 `missing_key`).
+ *
+ * @param {AdapterContext} ctx
+ * @param {ReturnType<typeof normalizeOptions>} config
+ * @returns {string | null}
+ */
+function extractKey(ctx, config) {
+  if (config.tokenFromRequest) {
+    const custom = config.tokenFromRequest(ctx);
+    return isString(custom) && custom.length > 0 ? custom : null;
+  }
+  const raw = ctx.getHeader(config.headerName);
+  if (isString(raw) && raw.length > 0) {
+    if (config.scheme === 'bearer') {
+      const m = /^bearer\s+(.+)$/i.exec(raw.trim());
+      if (m) {
+        return m[1].trim();
+      }
+    } else {
+      return raw.trim();
+    }
+  }
+  if (config.allowQueryParam && ctx.query) {
+    const q = ctx.query[config.queryParamName];
+    if (isString(q) && q.length > 0) {
+      return q;
+    }
+  }
+  return null;
+}
+
+/**
+ * Run the verify against the request. Returns a discriminated result:
+ * on success the caller attaches `verifyResult` to the request and
+ * proceeds; on failure the caller sends the returned `response`.
+ *
+ * @param {AdapterContext} ctx
+ * @param {ReturnType<typeof normalizeOptions>} config
+ * @returns {Promise<AdapterResult>}
+ */
+async function runApiKey(ctx, config) {
+  const raw = extractKey(ctx, config);
+  if (!raw) {
+    return {
+      verifyResult: { valid: false, reason: 'malformed' },
+      response: { status: 401, body: { error: 'missing_api_key' } },
+    };
+  }
+  const verifyResult = await verifyApiKey(raw, {
+    store: config.store,
+    peppers: config.peppers,
+    requiredScopes: config.requiredScopes,
+    expectedPrefix: config.expectedPrefix,
+    updateLastUsed: config.updateLastUsed,
+  });
+  if (!verifyResult.valid) {
+    const status = _statusFor(verifyResult.reason);
+    return {
+      verifyResult,
+      response: { status, body: { error: 'invalid_api_key', reason: verifyResult.reason } },
+    };
+  }
+  return { verifyResult };
+}
+
+function _statusFor(reason) {
+  switch (reason) {
+    case 'missing_scope':
+      return 403;
+    case 'store_unavailable':
+      return 503;
+    default:
+      return 401;
+  }
+}
+
+/**
+ * Fastify plugin for `@exortek/apikey`.
+ *
+ *   import Fastify from 'fastify';
+ *   import { apiKeyPlugin } from '@exortek/apikey/middleware/fastify';
+ *   import { memoryStore } from '@exortek/apikey/stores';
+ *
+ *   const app = Fastify();
+ *   await app.register(apiKeyPlugin, {
+ *     store: memoryStore(),
+ *     requiredScopes: ['read'],
+ *     updateLastUsed: true,
+ *   });
+ *
+ *   app.get('/v1/whoami', async req => req.apiKey);
+ *
+ * Wrapped with `fastify-plugin` so the `preHandler` hook and the
+ * `req.apiKey` decorator escape encapsulation and apply to routes
+ * registered as siblings in the parent scope. Register the plugin
+ * inside a scoped `app.register(async scope => …)` block to control
+ * which route group needs an API key — the usual Fastify pattern for
+ * "protect only these routes with auth".
+ *
+ * `fastify-plugin` is an **optional peer** — install it with
+ * `npm i fastify fastify-plugin` (or `yarn add`) alongside the fastify
+ * runtime.  Not a hard dependency because Express-only consumers of
+ * `@exortek/apikey` should not have to install it.
+ */
+
+
+async function apiKeyPluginFn(app, options) {
+  const config = normalizeOptions(options);
+
+  app.decorateRequest(config.attach, null);
+
+  app.addHook('preHandler', async (req, reply) => {
+    const ctx = {
+      getHeader: name => req.headers?.[name],
+      method: req.method,
+      ip: req.ip,
+      query: req.query,
+    };
+    const result = await runApiKey(ctx, config);
+    if (result.response) {
+      reply.code(result.response.status).send(result.response.body);
+      return reply;
+    }
+    req[config.attach] = result.verifyResult;
+    return undefined;
+  });
+}
+
+const apiKeyPlugin = fp(apiKeyPluginFn, {
+  fastify: '4.x || 5.x',
+  name: '@exortek/apikey',
+});
+
+exports.apiKeyPlugin = apiKeyPlugin;