@exortek/apikey 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @exortek/apikey
 
+## 1.1.0
+
+### Minor Changes
+
+- b1f5d6e: Add `customStore(impl)` — wrap your own `ApiKeyStore` implementation with validation (fails at construction
+  time if a required method is missing) and transparent sync/async wrapping, instead of hand-assembling the interface
+  yourself.
+
+### Patch Changes
+
+- 40fc707: Docs: add a "Rate limiting" section explaining why `@exortek/apikey` ships no built-in limiter and how to
+  front the mint/verify routes with `@exortek/security`'s rate-limit (with a runnable demo in both example servers);
+  document the previously-undocumented `revokeAllForUser` and `listApiKeys` functions; align README structure (badges,
+  `Why`, `Highlights`, `Links`) with the rest of the `@exortek/*` packages.
+
+## 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

package/README.md

@@ -3,10 +3,15 @@
 > Stripe-style prefixed API keys for Node.js 22+ — 3-segment tokens (`sk_live_<id>_<secret>`), HMAC-SHA256 storage hash with optional pepper rotation, scope allowlists, memory + Redis stores, Express + Fastify middleware. Zero non-`@exortek/*` runtime dependencies.
 
 [![npm](https://img.shields.io/npm/v/@exortek/apikey.svg?color=cb3837)](https://www.npmjs.com/package/@exortek/apikey)
+[![tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/ExorTek/auth/actions/workflows/ci.yml)
 [![node](https://img.shields.io/node/v/@exortek/apikey.svg?color=339933)](https://nodejs.org)
 [![install size](https://packagephobia.com/badge?p=@exortek/apikey)](https://packagephobia.com/result?p=@exortek/apikey)
+[![types](https://img.shields.io/badge/types-included-3178C6)](./dist/index.d.ts)
 [![license](https://img.shields.io/npm/l/@exortek/apikey.svg?color=blue)](./LICENSE)
-[![tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/ExorTek/auth/actions/workflows/ci.yml)
+
+📖 **Docs:** [**auth.memet.dev/apikey**](https://auth.memet.dev/apikey)
+
+## Why
 
 Every API vendor rebuilds the same six things: a prefixed token format so keys are recognisable in logs, hashed storage so a leaked DB doesn't leak secrets, scope allowlists so a machine token can't accidentally admin your infrastructure, revocation, a per-user list for the "manage API keys" UI, and a middleware that turns `Authorization: Bearer <key>` into a verified caller identity. `@exortek/apikey` ships all six.
 
@@ -124,6 +129,27 @@ Never throws on a bad key. Failure reasons:
 | `missing_scope`     | `requiredScopes` not covered by the record's `scopes`.    |
 | `store_unavailable` | `store.getById` threw.                                    |
 
+### `revokeAllForUser(userId, options)`
+
+```ts
+revokeAllForUser(userId: string, {
+  store:    ApiKeyStore,
+  reason?:  string,
+}): Promise<number>  // count of records actually revoked
+```
+
+Revoke every non-revoked key belonging to `userId` in one call — password reset, account termination, etc.
+
+### `listApiKeys(userId, options)`
+
+```ts
+listApiKeys(userId: string, {
+  store: ApiKeyStore,
+}): Promise<ApiKeyRecord[]>  // most-recently-used first
+```
+
+For a "manage API keys" UI. Hide `record.hash` before rendering — only the plaintext `id` is safe to display.
+
 ### Scopes: `covers` / `hasAll` / `hasAny`
 
 ```js
@@ -221,12 +247,37 @@ app.get('/v1/whoami', async req => req.apiKey);
 
 Invalid keys respond with 401 `{ error: 'invalid_api_key', reason }`; missing scope responds 403; store failure responds 503.
 
+## Rate limiting
+
+`@exortek/apikey` doesn't ship a built-in limiter, and deliberately so: `verifyApiKey` is an O(1) store lookup plus a fast HMAC compare, and the secret half is 256-bit random — there's no brute-force cost here for a limiter to blunt (see [Token format](#token-format)). What you actually want to bound is generic request volume, which isn't specific to this package.
+
+Put [`@exortek/security`](https://www.npmjs.com/package/@exortek/security)'s rate-limit in front of the routes that matter:
+
+- **Key-minting route** (`POST /keys` or wherever `createApiKey` is called) — this one has no key-based auth yet, so limit by IP.
+- **Guarded routes** — if you want to slow down credential stuffing beyond a firehose, limit by the `id` segment (plaintext, already in your logs) instead of IP, so one leaked key can't be used to exhaust another caller's budget.
+
+```js
+import { rateLimit } from '@exortek/security';
+import { rateLimitMiddleware } from '@exortek/security/express';
+
+const mintLimiter = rateLimitMiddleware({
+  limiter: rateLimit.sliding({ requests: 5, window: '1m', store: rateLimit.stores.memory() }),
+});
+
+app.post('/keys', mintLimiter, async (req, res) => {
+  /* createApiKey(...) */
+});
+```
+
+See `@exortek/apikey/examples/express-server.js` and `fastify-server.js` for a runnable version.
+
 ## Stores
 
 `@exortek/apikey/stores` ships two implementations. Any object matching the `ApiKeyStore` interface works — bring your own if you already have a keys table in your DB.
 
 - **`memoryStore()`** — in-process Map with a reverse index by `userId`. Not cluster-safe. Fine for dev / single-node prod / tests.
 - **`redisStore(client, { keyPrefix? })`** — layout: `<keyPrefix><id>` (JSON blob) + `<keyPrefix>u:<userId>` (SADD-set of ids). Cluster-safe. Works with `ioredis`, `node-redis@4+`, `@upstash/redis`.
+- **`customStore(impl)`** — wrap your own DB-backed implementation. Validates the required methods exist at construction time (not on the first `createApiKey` call) and wraps sync return values in a Promise, so `impl` can be sync or async.
 
 ### The interface
 
@@ -258,6 +309,20 @@ import { ApiKeyError, ErrorCode } from '@exortek/apikey';
 
 Expected verify failures do NOT throw — they surface as `{ valid: false, reason }`. See the failure-reasons table above.
 
+## Highlights
+
+- Stripe-style 3-segment tokens (`prefix_id_secret`) — recognisable in logs, O(1) lookup by id.
+- HMAC-SHA256 storage hash with optional pepper rotation — never store the raw secret.
+- Scope allowlists with namespace/super wildcards (`covers` / `hasAll` / `hasAny`).
+- Revocation, per-user listing, and last-used tracking for a "manage API keys" UI.
+- Express + Fastify middleware, memory + Redis stores, zero non-`@exortek/*` runtime dependencies.
+
+## Links
+
+- **Source:** [github.com/ExorTek/auth](https://github.com/ExorTek/auth)
+- **Issues & discussions:** [github.com/ExorTek/auth/issues](https://github.com/ExorTek/auth/issues)
+- **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
+
 ## License
 
-MIT
+MIT © ExorTek — see [LICENSE](./LICENSE).

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

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

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

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

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
@@ -1340,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);
-
-  app.decorateRequest(config.attach, null);
+const apiKeyPlugin = fastifyPlugin(
+  async function apiKeyPluginFn(app, options) {
+    const config = normalizeOptions(options);
 
-  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;
-  });
-}
+    app.decorateRequest(config.attach, null);
 
-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;

package/dist/middleware/fastify.mjs

@@ -1,4 +1,3 @@
-import fp from 'fastify-plugin';
 import { timingSafeEqual as timingSafeEqual$1, createHmac, createHash } from 'node:crypto';
 
 /**
@@ -129,6 +128,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.
@@ -786,11 +846,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:
@@ -870,9 +930,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
@@ -1338,45 +1398,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);
-
-  app.decorateRequest(config.attach, null);
+const apiKeyPlugin = fastifyPlugin(
+  async function apiKeyPluginFn(app, options) {
+    const config = normalizeOptions(options);
 
-  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;
-  });
-}
+    app.decorateRequest(config.attach, null);
 
-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' },
+);
 
 export { apiKeyPlugin };

package/dist/stores/custom.d.ts

@@ -0,0 +1,8 @@
+export function customStore(impl: any): {
+    put: (record: any) => Promise<any>;
+    getById: (id: any) => Promise<any>;
+    update: (id: any, patch: any) => Promise<any>;
+    revoke: (id: any, reason: any) => Promise<any>;
+    revokeAllForUser: (userId: any, reason: any) => Promise<any>;
+    listByUser: (userId: any) => Promise<any>;
+};

package/dist/stores/index.d.ts

@@ -1,2 +1,3 @@
 export { memoryStore } from "./memory.js";
 export { redisStore } from "./redis.js";
+export { customStore } from "./custom.js";

package/dist/stores.cjs

@@ -25,6 +25,27 @@
  * 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
@@ -351,7 +372,11 @@ function createMemoryRecordStore(config) {
  * }}
  */
 function createRedisRecordStore(client, config) {
-  const wrap = config.wrap ?? (msg => { throw new TypeError(msg); });
+  const wrap =
+    config.wrap ??
+    (msg => {
+      throw new TypeError(msg);
+    });
   assertRedisClient(client, ['get', 'set', 'del'], wrap);
 
   const {
@@ -1039,7 +1064,9 @@ function redisStore(client, options = {}) {
       }
       return record;
     },
-    wrap: msg => { throw invalidArgument(msg); },
+    wrap: msg => {
+      throw invalidArgument(msg);
+    },
   });
 
   return {
@@ -1084,5 +1111,40 @@ function redisStore(client, options = {}) {
   };
 }
 
+/**
+ * Wrap a user-supplied store into the `ApiKeyStore` interface.
+ * Validates that the required methods exist so a misconfiguration
+ * surfaces at construction time, not on the first `createApiKey` /
+ * `verifyApiKey` call. Sync implementations are wrapped transparently
+ * — return a plain value or a Promise, either works.
+ *
+ * Required: `put`, `getById`, `update`, `revoke`, `revokeAllForUser`, `listByUser`.
+ *
+ * @param {Partial<import('../index.js').ApiKeyStore>} impl
+ * @returns {import('../index.js').ApiKeyStore}
+ */
+
+const REQUIRED = ['put', 'getById', 'update', 'revoke', 'revokeAllForUser', 'listByUser'];
+
+function customStore(impl) {
+  if (!isObject(impl)) {
+    throw invalidArgument(`customStore(impl) requires an object with { ${REQUIRED.join(', ')} } methods`);
+  }
+  for (const name of REQUIRED) {
+    if (!isFunction(impl[name])) {
+      throw invalidArgument(`customStore: impl.${name} is required and must be a function`);
+    }
+  }
+  return {
+    put: record => Promise.resolve(impl.put(record)),
+    getById: id => Promise.resolve(impl.getById(id)),
+    update: (id, patch) => Promise.resolve(impl.update(id, patch)),
+    revoke: (id, reason) => Promise.resolve(impl.revoke(id, reason)),
+    revokeAllForUser: (userId, reason) => Promise.resolve(impl.revokeAllForUser(userId, reason)),
+    listByUser: userId => Promise.resolve(impl.listByUser(userId)),
+  };
+}
+
+exports.customStore = customStore;
 exports.memoryStore = memoryStore;
 exports.redisStore = redisStore;

package/dist/stores.mjs

@@ -23,6 +23,27 @@
  * 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
@@ -349,7 +370,11 @@ function createMemoryRecordStore(config) {
  * }}
  */
 function createRedisRecordStore(client, config) {
-  const wrap = config.wrap ?? (msg => { throw new TypeError(msg); });
+  const wrap =
+    config.wrap ??
+    (msg => {
+      throw new TypeError(msg);
+    });
   assertRedisClient(client, ['get', 'set', 'del'], wrap);
 
   const {
@@ -1037,7 +1062,9 @@ function redisStore(client, options = {}) {
       }
       return record;
     },
-    wrap: msg => { throw invalidArgument(msg); },
+    wrap: msg => {
+      throw invalidArgument(msg);
+    },
   });
 
   return {
@@ -1082,4 +1109,38 @@ function redisStore(client, options = {}) {
   };
 }
 
-export { memoryStore, redisStore };
+/**
+ * Wrap a user-supplied store into the `ApiKeyStore` interface.
+ * Validates that the required methods exist so a misconfiguration
+ * surfaces at construction time, not on the first `createApiKey` /
+ * `verifyApiKey` call. Sync implementations are wrapped transparently
+ * — return a plain value or a Promise, either works.
+ *
+ * Required: `put`, `getById`, `update`, `revoke`, `revokeAllForUser`, `listByUser`.
+ *
+ * @param {Partial<import('../index.js').ApiKeyStore>} impl
+ * @returns {import('../index.js').ApiKeyStore}
+ */
+
+const REQUIRED = ['put', 'getById', 'update', 'revoke', 'revokeAllForUser', 'listByUser'];
+
+function customStore(impl) {
+  if (!isObject(impl)) {
+    throw invalidArgument(`customStore(impl) requires an object with { ${REQUIRED.join(', ')} } methods`);
+  }
+  for (const name of REQUIRED) {
+    if (!isFunction(impl[name])) {
+      throw invalidArgument(`customStore: impl.${name} is required and must be a function`);
+    }
+  }
+  return {
+    put: record => Promise.resolve(impl.put(record)),
+    getById: id => Promise.resolve(impl.getById(id)),
+    update: (id, patch) => Promise.resolve(impl.update(id, patch)),
+    revoke: (id, reason) => Promise.resolve(impl.revoke(id, reason)),
+    revokeAllForUser: (userId, reason) => Promise.resolve(impl.revokeAllForUser(userId, reason)),
+    listByUser: userId => Promise.resolve(impl.listByUser(userId)),
+  };
+}
+
+export { customStore, memoryStore, redisStore };

package/dist/token.d.ts

@@ -30,9 +30,9 @@ export function mint(prefix: string, pepper: Buffer | null): {
 export function hashSecret(secretBytes: Buffer, pepper: Buffer | null): string;
 /**
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exortek/apikey",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Stripe-style prefixed API keys for Node.js — 3-segment tokens (prefix_id_secret), HMAC-SHA256 storage hash with pepper rotation, scope allowlists with wildcard match, opt-in lastUsedAt tracking, memory + Redis stores, Express + Fastify middleware. Server-only. Zero non-@exortek runtime dependencies.",
   "type": "module",
   "sideEffects": false,
@@ -32,6 +32,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
@@ -72,8 +73,7 @@
   },
   "peerDependencies": {
     "express": ">=4",
-    "fastify": ">=4",
-    "fastify-plugin": ">=4"
+    "fastify": ">=4"
   },
   "peerDependenciesMeta": {
     "express": {
@@ -81,17 +81,8 @@
     },
     "fastify": {
       "optional": true
-    },
-    "fastify-plugin": {
-      "optional": true
     }
   },
-  "devDependencies": {
-    "@exortek/shared": "0.0.0",
-    "express": "^5.2.1",
-    "fastify": "^5.10.0",
-    "fastify-plugin": "^6.0.0"
-  },
   "publishConfig": {
     "access": "public"
   }