@exortek/apikey 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,38 +1,48 @@
 # @exortek/apikey
 
+## 1.0.2
+
+### Patch Changes
+
+- 689cf87: Remove workspace-only `devDependencies` from published package.json — `@exortek/shared` no longer appears as
+  `"0.0.0"` on the npm registry.
+- 689cf87: Replace `fastify-plugin` npm dependency with `@exortek/shared/fastify-plugin` — a built-in drop-in that
+  covers skip-override, display-name, plugin-meta, version constraints, and encapsulate. Users no longer need to
+  `npm i fastify-plugin` alongside fastify.
+
+## 1.0.1
+
+### Patch Changes
+
+- 31223e4: Consolidate duplicated store internals into @exortek/shared utilities (redis-helpers, incr-store,
+  record-store). No public API changes.
+
+  apikey: fix Redis store race condition where a concurrent update() could silently un-revoke a key — revocations now
+  use a tombstone key that update() never touches.
+
+  apikey: fix memory store put() storing by reference instead of copying — now consistent with getById()'s copy-on-read
+  contract.
+
 ## 1.0.0
 
 ### Initial release
 
-- **`createApiKey(options)`** — mint a Stripe-style 3-segment token
-  `<prefix>_<id>_<secret>` (base32-crockford, no ambiguous glyphs).
-  Stores an HMAC-SHA256 hash of the secret plus a plaintext id for
-  O(1) lookup. Optional peppers (newest-first array, each ≥16 bytes)
-  turn a stolen DB into a non-crackable artifact.
-- **`verifyApiKey(rawKey, options)`** — parse, look up by id, timing-safe
-  hash compare, expiry / revocation / scope enforcement. Returns
-  `{ valid: true, userId, scopes, id, prefix, name?, environment?, metadata?, needsRehash? }`
-  or `{ valid: false, reason }` — never throws on a bad key.
-- **Scopes:** `hasAll` / `hasAny` / `covers` with `*` super wildcard and
-  `namespace:*` suffix wildcard.
-- **Pepper rotation:** verify against every pepper, mint with the
-  newest; `needsRehash: true` in the verify result signals the secret
-  matched an older pepper so `rehashApiKey` can silently migrate
-  storage.
-- **`revokeApiKey`** (by key or id), **`revokeAllForUser`**,
-  **`listApiKeys`** (sorted most-recently-used first).
-- **`mask(key)`** log-safe display, **`parseApiKey(key)`** unverified
-  segment extraction.
-- **Stores:** `memoryStore()` and `redisStore(client, options?)` under
-  the `@exortek/apikey/stores` subpath. Standard CRUD (`put` /
-  `getById` / `update` / `revoke` / `revokeAllForUser` / `listByUser`)
-  — bring your own by implementing the interface.
-- **Middleware:** Express (`@exortek/apikey/middleware/express`) and
-  Fastify (`@exortek/apikey/middleware/fastify`) adapters over a
-  shared `middleware/core.js` — `Authorization: Bearer <key>` by
-  default, configurable header + raw scheme + opt-in query-param
-  fallback. Attaches the verify result to `req.apiKey`.
-- **Errors:** `ApiKeyError` + `ErrorCode` catalogue
-  (`INVALID_ARGUMENT` / `INVALID_PREFIX` / `INVALID_PEPPER` /
-  `STORE_ERROR`). Expected verify failures surface as
-  `{ valid: false, reason }`, not exceptions.
+- **`createApiKey(options)`** — mint a Stripe-style 3-segment token `<prefix>_<id>_<secret>` (base32-crockford, no
+  ambiguous glyphs). Stores an HMAC-SHA256 hash of the secret plus a plaintext id for O(1) lookup. Optional peppers
+  (newest-first array, each ≥16 bytes) turn a stolen DB into a non-crackable artifact.
+- **`verifyApiKey(rawKey, options)`** — parse, look up by id, timing-safe hash compare, expiry / revocation / scope
+  enforcement. Returns `{ valid: true, userId, scopes, id, prefix, name?, environment?, metadata?, needsRehash? }` or
+  `{ valid: false, reason }` — never throws on a bad key.
+- **Scopes:** `hasAll` / `hasAny` / `covers` with `*` super wildcard and `namespace:*` suffix wildcard.
+- **Pepper rotation:** verify against every pepper, mint with the newest; `needsRehash: true` in the verify result
+  signals the secret matched an older pepper so `rehashApiKey` can silently migrate storage.
+- **`revokeApiKey`** (by key or id), **`revokeAllForUser`**, **`listApiKeys`** (sorted most-recently-used first).
+- **`mask(key)`** log-safe display, **`parseApiKey(key)`** unverified segment extraction.
+- **Stores:** `memoryStore()` and `redisStore(client, options?)` under the `@exortek/apikey/stores` subpath. Standard
+  CRUD (`put` / `getById` / `update` / `revoke` / `revokeAllForUser` / `listByUser`) — bring your own by implementing
+  the interface.
+- **Middleware:** Express (`@exortek/apikey/middleware/express`) and Fastify (`@exortek/apikey/middleware/fastify`)
+  adapters over a shared `middleware/core.js` — `Authorization: Bearer <key>` by default, configurable header + raw
+  scheme + opt-in query-param fallback. Attaches the verify result to `req.apiKey`.
+- **Errors:** `ApiKeyError` + `ErrorCode` catalogue (`INVALID_ARGUMENT` / `INVALID_PREFIX` / `INVALID_PEPPER` /
+  `STORE_ERROR`). Expected verify failures surface as `{ valid: false, reason }`, not exceptions.

package/dist/index.cjs

@@ -946,11 +946,11 @@ function timingSafeEqual(a, b) {
  *
  * **Wire format:**
  *
- *     <prefix>_<base64url(16 random bytes)>_<base64url(32 random bytes)>
- *     ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^
- *     type     id (128-bit — plaintext DB key)   secret (256-bit — HMAC'd)
+ *     <prefix>_<crockford-base32(16 random bytes)>_<crockford-base32(32 random bytes)>
+ *     ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ *     type     id (128-bit, 26 chars)                secret (256-bit, 52 chars)
  *
- *   sk_live_QVI0RExDX01Fbg_pTk9UX0FfUkVBTF9LRVlfNDJfQVJUSVNBTkFMX1BJWk
+ *   sk_live_<id-26-chars>_<secret-52-chars>
  *
  * Stripe / GitHub / Anthropic all use this three-segment shape. The
  * split matters:
@@ -1050,9 +1050,9 @@ function hashSecret(secretBytes, pepper) {
 
 /**
  * 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.
+ * inputs are base64url strings. A length mismatch early-returns `false`
+ * — all stored hashes are fixed-length (43-char SHA-256 digests), so
+ * the length check leaks no information about the stored value.
  *
  * @param {string} candidate
  * @param {string} stored
@@ -1093,15 +1093,25 @@ function parseApiKey(key) {
   // 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;}
+  if (lastUnderscore <= 0) {
+    return null;
+  }
   const prevUnderscore = key.lastIndexOf('_', lastUnderscore - 1);
-  if (prevUnderscore <= 0) {return null;}
+  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;}
+  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 };
 }
 

package/dist/index.d.ts

@@ -223,7 +223,7 @@ export type CreateApiKeyOptions = {
     /**
      * Newest first. Each ≥16 bytes. Omit for plain SHA-256 storage.
      */
-    peppers?: (string | Buffer | Uint8Array<ArrayBufferLike>)[] | undefined;
+    peppers?: any[] | undefined;
     /**
      * Override `Date.now()` for testing.
      */
@@ -245,7 +245,7 @@ export type CreateApiKeyResult = {
 };
 export type VerifyApiKeyOptions = {
     store: ApiKeyStore;
-    peppers?: (string | Buffer | Uint8Array<ArrayBufferLike>)[] | undefined;
+    peppers?: any[] | undefined;
     requiredScopes?: string[] | undefined;
     /**
      * Reject a valid key whose prefix differs.

package/dist/index.mjs

@@ -944,11 +944,11 @@ function timingSafeEqual(a, b) {
  *
  * **Wire format:**
  *
- *     <prefix>_<base64url(16 random bytes)>_<base64url(32 random bytes)>
- *     ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^
- *     type     id (128-bit — plaintext DB key)   secret (256-bit — HMAC'd)
+ *     <prefix>_<crockford-base32(16 random bytes)>_<crockford-base32(32 random bytes)>
+ *     ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ *     type     id (128-bit, 26 chars)                secret (256-bit, 52 chars)
  *
- *   sk_live_QVI0RExDX01Fbg_pTk9UX0FfUkVBTF9LRVlfNDJfQVJUSVNBTkFMX1BJWk
+ *   sk_live_<id-26-chars>_<secret-52-chars>
  *
  * Stripe / GitHub / Anthropic all use this three-segment shape. The
  * split matters:
@@ -1048,9 +1048,9 @@ function hashSecret(secretBytes, pepper) {
 
 /**
  * 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.
+ * inputs are base64url strings. A length mismatch early-returns `false`
+ * — all stored hashes are fixed-length (43-char SHA-256 digests), so
+ * the length check leaks no information about the stored value.
  *
  * @param {string} candidate
  * @param {string} stored
@@ -1091,15 +1091,25 @@ function parseApiKey(key) {
   // 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;}
+  if (lastUnderscore <= 0) {
+    return null;
+  }
   const prevUnderscore = key.lastIndexOf('_', lastUnderscore - 1);
-  if (prevUnderscore <= 0) {return null;}
+  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;}
+  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 };
 }
 

package/dist/middleware/core.d.ts

@@ -6,7 +6,7 @@
  */
 export function normalizeOptions(options: ApiKeyMiddlewareOptions): {
     store: import("../index.js").ApiKeyStore;
-    peppers: (string | Buffer | Uint8Array<ArrayBufferLike>)[] | undefined;
+    peppers: any[] | undefined;
     requiredScopes: string[] | undefined;
     expectedPrefix: string | undefined;
     updateLastUsed: boolean;
@@ -45,7 +45,7 @@ export type AdapterContext = {
 };
 export type ApiKeyMiddlewareOptions = {
     store: import("../index.js").ApiKeyStore;
-    peppers?: (string | Buffer | Uint8Array<ArrayBufferLike>)[] | undefined;
+    peppers?: any[] | undefined;
     requiredScopes?: string[] | undefined;
     expectedPrefix?: string | undefined;
     updateLastUsed?: boolean | undefined;

package/dist/middleware/express.cjs

@@ -787,11 +787,11 @@ function timingSafeEqual(a, b) {
  *
  * **Wire format:**
  *
- *     <prefix>_<base64url(16 random bytes)>_<base64url(32 random bytes)>
- *     ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^
- *     type     id (128-bit — plaintext DB key)   secret (256-bit — HMAC'd)
+ *     <prefix>_<crockford-base32(16 random bytes)>_<crockford-base32(32 random bytes)>
+ *     ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ *     type     id (128-bit, 26 chars)                secret (256-bit, 52 chars)
  *
- *   sk_live_QVI0RExDX01Fbg_pTk9UX0FfUkVBTF9LRVlfNDJfQVJUSVNBTkFMX1BJWk
+ *   sk_live_<id-26-chars>_<secret-52-chars>
  *
  * Stripe / GitHub / Anthropic all use this three-segment shape. The
  * split matters:
@@ -871,9 +871,9 @@ function hashSecret(secretBytes, pepper) {
 
 /**
  * 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.
+ * inputs are base64url strings. A length mismatch early-returns `false`
+ * — all stored hashes are fixed-length (43-char SHA-256 digests), so
+ * the length check leaks no information about the stored value.
  *
  * @param {string} candidate
  * @param {string} stored
@@ -914,15 +914,25 @@ function parseApiKey(key) {
   // 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;}
+  if (lastUnderscore <= 0) {
+    return null;
+  }
   const prevUnderscore = key.lastIndexOf('_', lastUnderscore - 1);
-  if (prevUnderscore <= 0) {return null;}
+  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;}
+  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 };
 }
 

package/dist/middleware/express.mjs

@@ -785,11 +785,11 @@ function timingSafeEqual(a, b) {
  *
  * **Wire format:**
  *
- *     <prefix>_<base64url(16 random bytes)>_<base64url(32 random bytes)>
- *     ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^
- *     type     id (128-bit — plaintext DB key)   secret (256-bit — HMAC'd)
+ *     <prefix>_<crockford-base32(16 random bytes)>_<crockford-base32(32 random bytes)>
+ *     ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ *     type     id (128-bit, 26 chars)                secret (256-bit, 52 chars)
  *
- *   sk_live_QVI0RExDX01Fbg_pTk9UX0FfUkVBTF9LRVlfNDJfQVJUSVNBTkFMX1BJWk
+ *   sk_live_<id-26-chars>_<secret-52-chars>
  *
  * Stripe / GitHub / Anthropic all use this three-segment shape. The
  * split matters:
@@ -869,9 +869,9 @@ function hashSecret(secretBytes, pepper) {
 
 /**
  * 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.
+ * inputs are base64url strings. A length mismatch early-returns `false`
+ * — all stored hashes are fixed-length (43-char SHA-256 digests), so
+ * the length check leaks no information about the stored value.
  *
  * @param {string} candidate
  * @param {string} stored
@@ -912,15 +912,25 @@ function parseApiKey(key) {
   // 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;}
+  if (lastUnderscore <= 0) {
+    return null;
+  }
   const prevUnderscore = key.lastIndexOf('_', lastUnderscore - 1);
-  if (prevUnderscore <= 0) {return null;}
+  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;}
+  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 };
 }
 

package/dist/middleware/fastify.cjs

@@ -1,6 +1,5 @@
 'use strict';
 
-var fp = require('fastify-plugin');
 var node_crypto = require('node:crypto');
 
 /**
@@ -131,6 +130,67 @@ function isBuffer(value) {
   return Buffer.isBuffer(value);
 }
 
+let counter = 0;
+
+/**
+ * Mark a function as a Fastify plugin with encapsulation bypass.
+ *
+ * Drop-in replacement for the `fastify-plugin` npm package — covers
+ * the same symbols and option handling without the external dependency.
+ *
+ * @param {Function} fn               Plugin function `(fastify, opts) => …`
+ * @param {string | PluginOptions} [options]
+ *   A semver range string (shorthand for `{ fastify: range }`) or a
+ *   full options object.
+ * @returns {Function} The same function, decorated with plugin metadata.
+ *
+ * @typedef {object} PluginOptions
+ * @property {string} [name]          Display name. Auto-generated from
+ *                                    `fn.name` when omitted.
+ * @property {string} [fastify]       Semver range the plugin is compatible
+ *                                    with (e.g. `'>=4'`). Fastify checks
+ *                                    this at register time.
+ * @property {string[]} [decorators]  Decorators the plugin expects to
+ *                                    exist before it runs.
+ * @property {string[]} [dependencies] Plugins that must be registered
+ *                                    before this one.
+ * @property {boolean} [encapsulate]  When `true`, the plugin stays
+ *                                    encapsulated (skip-override = false).
+ *                                    Default `false` (skip override).
+ */
+function fastifyPlugin(fn, options) {
+  if (fn && fn.default !== undefined) {
+    fn = fn.default;
+  }
+
+  if (!isFunction(fn)) {
+    throw new TypeError(`fastifyPlugin expects a function, instead got '${typeof fn}'`);
+  }
+
+  let opts;
+  if (isString(options)) {
+    opts = { fastify: options };
+  } else if (isObject(options)) {
+    opts = { ...options };
+  } else {
+    opts = {};
+  }
+
+  if (!opts.name) {
+    opts.name = (fn.name || 'anonymous') + '-auto-' + counter++;
+  }
+
+  fn[Symbol.for('skip-override')] = opts.encapsulate !== true;
+  fn[Symbol.for('fastify.display-name')] = opts.name;
+  fn[Symbol.for('plugin-meta')] = opts;
+
+  if (!fn.default) {
+    fn.default = fn;
+  }
+
+  return fn;
+}
+
 /**
  * Imperative single-argument guard helpers — the everyday
  * `assertPositiveInt(x, 'name')` shape used at API boundaries.
@@ -788,11 +848,11 @@ function timingSafeEqual(a, b) {
  *
  * **Wire format:**
  *
- *     <prefix>_<base64url(16 random bytes)>_<base64url(32 random bytes)>
- *     ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^
- *     type     id (128-bit — plaintext DB key)   secret (256-bit — HMAC'd)
+ *     <prefix>_<crockford-base32(16 random bytes)>_<crockford-base32(32 random bytes)>
+ *     ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ *     type     id (128-bit, 26 chars)                secret (256-bit, 52 chars)
  *
- *   sk_live_QVI0RExDX01Fbg_pTk9UX0FfUkVBTF9LRVlfNDJfQVJUSVNBTkFMX1BJWk
+ *   sk_live_<id-26-chars>_<secret-52-chars>
  *
  * Stripe / GitHub / Anthropic all use this three-segment shape. The
  * split matters:
@@ -872,9 +932,9 @@ function hashSecret(secretBytes, pepper) {
 
 /**
  * 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.
+ * inputs are base64url strings. A length mismatch early-returns `false`
+ * — all stored hashes are fixed-length (43-char SHA-256 digests), so
+ * the length check leaks no information about the stored value.
  *
  * @param {string} candidate
  * @param {string} stored
@@ -915,15 +975,25 @@ function parseApiKey(key) {
   // 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;}
+  if (lastUnderscore <= 0) {
+    return null;
+  }
   const prevUnderscore = key.lastIndexOf('_', lastUnderscore - 1);
-  if (prevUnderscore <= 0) {return null;}
+  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;}
+  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 };
 }
 
@@ -1330,45 +1400,36 @@ function _statusFor(reason) {
  *
  *   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.
+ * The plugin bypasses Fastify's encapsulation so the `preHandler` hook
+ * and the `req.apiKey` decorator apply to routes in the parent scope.
+ * Register inside a scoped `app.register(async scope => …)` block to
+ * control which route group needs an API key.
  */
 
 
-async function apiKeyPluginFn(app, options) {
-  const config = normalizeOptions(options);
+const apiKeyPlugin = fastifyPlugin(
+  async function apiKeyPluginFn(app, options) {
+    const config = normalizeOptions(options);
 
-  app.decorateRequest(config.attach, null);
+    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',
-});
+    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;
+    });
+  },
+  { name: '@exortek/apikey' },
+);
 
 exports.apiKeyPlugin = apiKeyPlugin;

package/dist/middleware/fastify.d.ts

@@ -1 +1 @@
-export function apiKeyPlugin(app: any, options: any): Promise<void>;
+export const apiKeyPlugin: Function;