@exortek/apikey 1.1.2 → 1.1.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @exortek/apikey
 
+## 1.1.3
+
+### Patch Changes
+
+- 89aea87: Ship self-contained TypeScript declarations. Every package's emitted `.d.ts` referenced `@exortek/shared`
+  (e.g. `import { BaseError } from '@exortek/shared/errors'`), but `@exortek/shared` is a private, never-published
+  workspace package that is inlined into each bundle at build time. A TypeScript consumer therefore hit
+  `Cannot find module '@exortek/shared/…'` (with `skipLibCheck` off) or silently degraded error-class types like
+  `ApiKeyError` — losing its constructor signature and `.code` / `.message` — with `skipLibCheck` on.
+
+  The build now runs a declaration-bundling pass (`rollup-plugin-dts`) after `tsc`, flattening each entry's `.d.ts` and
+  inlining the `@exortek/shared` types so the shipped declarations are fully self-contained. Runtime deps and `node:*`
+  stay external. No runtime or API change — types only.
+
 ## 1.1.2
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,3 +1,131 @@
+/**
+ * Parse a raw key without verifying it. Returns the segments, or
+ * `null` when the shape is wrong. Never throws.
+ *
+ * Callers can use `parseApiKey(key).prefix` to route by key family
+ * in a middleware before hitting the store — but the parse result
+ * MUST NOT be trusted as authenticated. Only `verifyApiKey` proves
+ * the holder possesses the real secret.
+ *
+ * @param {string} key
+ * @returns {{ prefix: string, id: string, secret: string } | null}
+ */
+declare function parseApiKey(key: string): {
+    prefix: string;
+    id: string;
+    secret: string;
+} | null;
+/**
+ * Log-safe display for a key. Returns `<prefix>_<first-N-of-id>…<last-M-of-secret>`
+ * so the value is recognisable in an audit log without disclosing the
+ * secret. The default masks all but the first 6 chars of the id and
+ * the last 4 chars of the secret.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+declare function mask(key: string): string;
+
+/**
+ * Shared base error class — the single error structure behind every
+ * `@exortek/*` package's `errors.js`.
+ *
+ * Every package keeps its own class identity with a one-liner subclass;
+ * codes stay per-package frozen maps, status mapping is declared as a
+ * static field:
+ *
+ *   import { BaseError } from '@exortek/shared/errors';
+ *
+ *   export const ErrorCode = Object.freeze({
+ *     INVALID_ARGUMENT: 'INVALID_ARGUMENT',
+ *     INVALID_TOKEN: 'INVALID_TOKEN',
+ *   });
+ *
+ *   export class JwtError extends BaseError {
+ *     static statuses = { INVALID_ARGUMENT: 400, INVALID_TOKEN: 401 };
+ *     static defaultStatus = 500;
+ *   }
+ *
+ * Instances carry a stable machine-readable `code` (branch on this,
+ * never on the message), an optional HTTP `status`, an optional
+ * `details` object, and the standard `cause` chain.
+ */
+declare class BaseError extends Error {
+    /**
+     * Optional `code → HTTP status` map declared on the subclass. When
+     * absent the instance carries no `status` at all — for HTTP-agnostic
+     * packages like `@exortek/crypto`.
+     *
+     * @type {Record<string, number> | undefined}
+     */
+    static statuses: Record<string, number> | undefined;
+    /**
+     * Fallback status for codes missing from `statuses`.
+     *
+     * @type {number}
+     */
+    static defaultStatus: number;
+    /**
+     * @param {string} code    Stable machine-readable code; branch on this.
+     * @param {string} message Human-readable diagnostic. Free-form; may
+     *                         change across versions.
+     * @param {{ cause?: unknown, status?: number, details?: Record<string, unknown> }} [options]
+     */
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+        status?: number;
+        details?: Record<string, unknown>;
+    });
+    /** @type {string} */
+    code: string;
+    /** @type {number | undefined} */
+    status: number | undefined;
+    /** @type {Record<string, unknown> | undefined} */
+    details: Record<string, unknown> | undefined;
+}
+
+declare const ErrorCode: Readonly<{
+    INVALID_ARGUMENT: "INVALID_ARGUMENT";
+    INVALID_PREFIX: "INVALID_PREFIX";
+    INVALID_PEPPER: "INVALID_PEPPER";
+    STORE_ERROR: "STORE_ERROR";
+}>;
+/**
+ * Every recoverable failure raised by this package. Carries a stable
+ * `code` (from {@link ErrorCode}) and a `status` — the HTTP response
+ * status a middleware layer would use when translating the error.
+ */
+declare class ApiKeyError extends BaseError {
+    static statuses: {
+        INVALID_ARGUMENT: number;
+        INVALID_PREFIX: number;
+        INVALID_PEPPER: number;
+        STORE_ERROR: number;
+    };
+}
+
+/**
+ * Does `granted` cover a single `required` scope?
+ * @param {string[]} granted
+ * @param {string} required
+ * @returns {boolean}
+ */
+declare function covers(granted: string[], required: string): boolean;
+/**
+ * All required scopes must be covered by granted.
+ * @param {string[]} granted
+ * @param {string[]} required
+ * @returns {boolean}
+ */
+declare function hasAll(granted: string[], required: string[]): boolean;
+/**
+ * At least one required scope must be covered.
+ * @param {string[]} granted
+ * @param {string[]} required
+ * @returns {boolean}
+ */
+declare function hasAny(granted: string[], required: string[]): boolean;
+
 /**
  * @typedef {object} ApiKeyRecord
  * @property {string} id                      Plaintext lookup key (128-bit b64u).
@@ -80,7 +208,7 @@
  * @param {CreateApiKeyOptions} options
  * @returns {Promise<CreateApiKeyResult>}
  */
-export function createApiKey(options: CreateApiKeyOptions): Promise<CreateApiKeyResult>;
+declare function createApiKey(options: CreateApiKeyOptions): Promise<CreateApiKeyResult>;
 /**
  * Verify a raw API key. Returns `{ valid: true, ... }` on success, or
  * `{ valid: false, reason }` on any expected failure. Never throws on
@@ -96,7 +224,7 @@ export function createApiKey(options: CreateApiKeyOptions): Promise<CreateApiKey
  * @param {VerifyApiKeyOptions} options
  * @returns {Promise<VerifyApiKeyResult>}
  */
-export function verifyApiKey(rawKey: string, options: VerifyApiKeyOptions): Promise<VerifyApiKeyResult>;
+declare function verifyApiKey(rawKey: string, options: VerifyApiKeyOptions): Promise<VerifyApiKeyResult>;
 /**
  * Revoke an API key by id or by the raw wire key. Returns `true` if
  * a record was actually revoked, `false` if the id was unknown or
@@ -106,7 +234,7 @@ export function verifyApiKey(rawKey: string, options: VerifyApiKeyOptions): Prom
  * @param {{ store: ApiKeyStore, reason?: string }} options
  * @returns {Promise<boolean>}
  */
-export function revokeApiKey(keyOrId: string, options: {
+declare function revokeApiKey(keyOrId: string, options: {
     store: ApiKeyStore;
     reason?: string;
 }): Promise<boolean>;
@@ -119,7 +247,7 @@ export function revokeApiKey(keyOrId: string, options: {
  * @param {{ store: ApiKeyStore, reason?: string }} options
  * @returns {Promise<number>}
  */
-export function revokeAllForUser(userId: string, options: {
+declare function revokeAllForUser(userId: string, options: {
     store: ApiKeyStore;
     reason?: string;
 }): Promise<number>;
@@ -133,7 +261,7 @@ export function revokeAllForUser(userId: string, options: {
  * @param {{ store: ApiKeyStore }} options
  * @returns {Promise<ApiKeyRecord[]>}
  */
-export function listApiKeys(userId: string, options: {
+declare function listApiKeys(userId: string, options: {
     store: ApiKeyStore;
 }): Promise<ApiKeyRecord[]>;
 /**
@@ -146,12 +274,12 @@ export function listApiKeys(userId: string, options: {
  * @param {{ store: ApiKeyStore, peppers: (Buffer | Uint8Array | string)[] }} options
  * @returns {Promise<boolean>}
  */
-export function rehashApiKey(rawKey: string, options: {
+declare function rehashApiKey(rawKey: string, options: {
     store: ApiKeyStore;
     peppers: (Buffer | Uint8Array | string)[];
 }): Promise<boolean>;
-export { maskKey as maskApiKey };
-export type ApiKeyRecord = {
+
+type ApiKeyRecord = {
     /**
      * Plaintext lookup key (128-bit b64u).
      */
@@ -197,7 +325,7 @@ export type ApiKeyRecord = {
      */
     pepperVersion?: number | undefined;
 };
-export type ApiKeyStore = {
+type ApiKeyStore = {
     put: (record: ApiKeyRecord) => Promise<void>;
     getById: (id: string) => Promise<ApiKeyRecord | null>;
     update: (id: string, patch: Partial<ApiKeyRecord>) => Promise<ApiKeyRecord | null>;
@@ -205,7 +333,7 @@ export type ApiKeyStore = {
     revokeAllForUser: (userId: string, reason?: string) => Promise<number>;
     listByUser: (userId: string) => Promise<ApiKeyRecord[]>;
 };
-export type CreateApiKeyOptions = {
+type CreateApiKeyOptions = {
     /**
      * Stripe-style; `sk_live`, `pk_test`, `svc_prod_v2`.
      */
@@ -229,7 +357,7 @@ export type CreateApiKeyOptions = {
      */
     now?: number | undefined;
 };
-export type CreateApiKeyResult = {
+type CreateApiKeyResult = {
     /**
      * Wire token — show ONCE to the caller and never again.
      */
@@ -243,7 +371,7 @@ export type CreateApiKeyResult = {
      */
     record: ApiKeyRecord;
 };
-export type VerifyApiKeyOptions = {
+type VerifyApiKeyOptions = {
     store: ApiKeyStore;
     peppers?: any[] | undefined;
     requiredScopes?: string[] | undefined;
@@ -257,8 +385,8 @@ export type VerifyApiKeyOptions = {
     updateLastUsed?: boolean | undefined;
     now?: number | undefined;
 };
-export type VerifyApiKeyFailureReason = "malformed" | "not_found" | "expired" | "revoked" | "bad_secret" | "prefix_mismatch" | "missing_scope" | "store_unavailable";
-export type VerifyApiKeyResult = {
+type VerifyApiKeyFailureReason = "malformed" | "not_found" | "expired" | "revoked" | "bad_secret" | "prefix_mismatch" | "missing_scope" | "store_unavailable";
+type VerifyApiKeyResult = {
     valid: true;
     id: string;
     userId: string;
@@ -272,7 +400,6 @@ export type VerifyApiKeyResult = {
     valid: false;
     reason: VerifyApiKeyFailureReason;
 };
-import { mask as maskKey } from './token.js';
-export { ApiKeyError, ErrorCode } from "./errors.js";
-export { covers, hasAll, hasAny } from "./scopes.js";
-export { parseApiKey, mask } from "./token.js";
+
+export { ApiKeyError, ErrorCode, covers, createApiKey, hasAll, hasAny, listApiKeys, mask, mask as maskApiKey, parseApiKey, rehashApiKey, revokeAllForUser, revokeApiKey, verifyApiKey };
+export type { ApiKeyRecord, ApiKeyStore, CreateApiKeyOptions, CreateApiKeyResult, VerifyApiKeyFailureReason, VerifyApiKeyOptions, VerifyApiKeyResult };

package/dist/middleware/express.d.ts

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

package/dist/middleware/fastify.d.ts

@@ -1 +1,3 @@
-export const apiKeyPlugin: Function;
+declare const apiKeyPlugin: Function;
+
+export { apiKeyPlugin };

package/dist/stores/custom.d.ts

@@ -1,8 +1 @@
-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>;
-};
+export const customStore: (impl: object) => Record<string, (...args: any[]) => Promise<any>>;

package/dist/stores/index.d.ts

@@ -1,3 +1,79 @@
-export { memoryStore } from "./memory.js";
-export { redisStore } from "./redis.js";
-export { customStore } from "./custom.js";
+type ApiKeyRecord = {
+    /**
+     * Plaintext lookup key (128-bit b64u).
+     */
+    id: string;
+    /**
+     * Storage hash of the secret (43-char b64u).
+     */
+    hash: string;
+    /**
+     * The prefix the key was minted with.
+     */
+    prefix: string;
+    userId: string;
+    scopes: string[];
+    /**
+     * Human label ("Production Backend").
+     */
+    name?: string | undefined;
+    /**
+     * `'live'` / `'test'` / caller-defined.
+     */
+    environment?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    /**
+     * ms epoch.
+     */
+    createdAt: number;
+    /**
+     * ms epoch; absent = no expiry.
+     */
+    expiresAt?: number | undefined;
+    /**
+     * ms epoch when the record was revoked.
+     */
+    revokedAt?: number | undefined;
+    revokedReason?: string | undefined;
+    /**
+     * ms epoch of the last successful verify.
+     */
+    lastUsedAt?: number | undefined;
+    /**
+     * Index into the peppers array that was used at mint. 0 = newest.
+     */
+    pepperVersion?: number | undefined;
+};
+type ApiKeyStore = {
+    put: (record: ApiKeyRecord) => Promise<void>;
+    getById: (id: string) => Promise<ApiKeyRecord | null>;
+    update: (id: string, patch: Partial<ApiKeyRecord>) => Promise<ApiKeyRecord | null>;
+    revoke: (id: string, reason?: string) => Promise<boolean>;
+    revokeAllForUser: (userId: string, reason?: string) => Promise<number>;
+    listByUser: (userId: string) => Promise<ApiKeyRecord[]>;
+};
+
+/**
+ * @returns {import('../index.js').ApiKeyStore & { _size: () => number }}
+ */
+declare function memoryStore(): ApiKeyStore & {
+    _size: () => number;
+};
+
+/**
+ * @typedef {object} RedisStoreOptions
+ * @property {string} [keyPrefix='apikey:']
+ */
+/**
+ * @param {any} client
+ * @param {RedisStoreOptions} [options]
+ * @returns {import('../index.js').ApiKeyStore}
+ */
+declare function redisStore(client: any, options?: RedisStoreOptions): ApiKeyStore;
+type RedisStoreOptions = {
+    keyPrefix?: string | undefined;
+};
+
+declare const customStore: (impl: object) => Record<string, (...args: any[]) => Promise<any>>;
+
+export { customStore, memoryStore, redisStore };

package/dist/stores.cjs

@@ -897,39 +897,101 @@ 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.
+ * Family factory for the `customStore(impl)` wrapper every store-shipping
+ * package exposes.
  *
- * Required: `put`, `getById`, `update`, `revoke`, `revokeAllForUser`, `listByUser`.
+ * Each package used to hand-roll the same three steps: assert `impl` is an
+ * object, assert its required methods are functions, then `Promise.resolve()`
+ * -wrap every call so a sync implementation is transparently promoted to the
+ * async store interface. Only the method-name arrays and the typed error
+ * differ. This collapses all of that into one binding per package.
  *
- * @param {Partial<import('../index.js').ApiKeyStore>} impl
- * @returns {import('../index.js').ApiKeyStore}
+ * Consumers: `apikey`, `challenge`, `magic-link`, `opaque`, `session`.
  */
 
-const REQUIRED = ['put', 'getById', 'update', 'revoke', 'revokeAllForUser', 'listByUser'];
 
-function customStore(impl) {
+/**
+ * Assert `impl` is an object exposing every method in `required` as a function.
+ * Throws the caller's typed error (via `wrap`) on the first failure. Used on
+ * its own by stores that keep a caller's implementation verbatim (jwt / paseto
+ * token registries), and internally by {@link createCustomStoreValidator}.
+ *
+ * @param {unknown} impl
+ * @param {readonly string[]} required
+ * @param {(message: string) => Error} wrap
+ *   The package's error factory; its returned error is thrown. A `wrap` that
+ *   throws directly also works (the outer `throw` is then unreachable).
+ * @returns {void}
+ */
+function assertStoreShape(impl, required, wrap) {
   if (!isObject(impl)) {
-    throw invalidArgument(`customStore(impl) requires an object with { ${REQUIRED.join(', ')} } methods`);
+    throw wrap(`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`);
+  for (const name of required) {
+    if (!isFunction(/** @type {any} */ (impl)[name])) {
+      throw wrap(`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)),
+}
+
+/**
+ * @param {object} spec
+ * @param {readonly string[]} spec.required
+ *   Methods that must exist on `impl`; missing ones fail at construction time.
+ * @param {readonly string[]} [spec.optional]
+ *   Methods wrapped through only when present (feature-gated store extras).
+ * @param {(message: string) => Error} spec.wrap
+ *   The package's error factory (its `invalidArgument`) — called with a
+ *   diagnostic message; its returned typed error is thrown so
+ *   `err instanceof <Pkg>Error` holds. A `wrap` that throws directly also
+ *   works (the outer `throw` is then unreachable).
+ * @param {Record<string, (result: any) => any>} [spec.coerce]
+ *   Optional per-method post-processor applied to the resolved result — e.g.
+ *   opaque coerces `set` to `undefined` so a native `Map.set` return value
+ *   can't leak out as `Promise<Map>`.
+ * @returns {(impl: object) => Record<string, (...args: any[]) => Promise<any>>}
+ */
+function createCustomStoreValidator({ required, optional = [], wrap, coerce = {} }) {
+  return function customStore(impl) {
+    assertStoreShape(impl, required, wrap);
+
+    /** @type {Record<string, (...args: any[]) => Promise<any>>} */
+    const store = {};
+    const bind = name => {
+      const post = coerce[name];
+      store[name] = post
+        ? (...args) => Promise.resolve(impl[name](...args)).then(post)
+        : (...args) => Promise.resolve(impl[name](...args));
+    };
+
+    for (const name of required) {
+      bind(name);
+    }
+    for (const name of optional) {
+      if (isFunction(impl[name])) {
+        bind(name);
+      }
+    }
+    return store;
   };
 }
 
+/**
+ * Wrap a user-supplied store into the `ApiKeyStore` interface. Validates the
+ * required methods at construction time (not on first use) and promotes sync
+ * implementations to the async interface.
+ *
+ * Required: `put`, `getById`, `update`, `revoke`, `revokeAllForUser`, `listByUser`.
+ *
+ * @param {Partial<import('../index.js').ApiKeyStore>} impl
+ * @returns {import('../index.js').ApiKeyStore}
+ */
+
+const customStore = createCustomStoreValidator({
+  required: ['put', 'getById', 'update', 'revoke', 'revokeAllForUser', 'listByUser'],
+  wrap: invalidArgument,
+});
+
 exports.customStore = customStore;
 exports.memoryStore = memoryStore;
 exports.redisStore = redisStore;

package/dist/stores.mjs

@@ -895,37 +895,99 @@ 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.
+ * Family factory for the `customStore(impl)` wrapper every store-shipping
+ * package exposes.
  *
- * Required: `put`, `getById`, `update`, `revoke`, `revokeAllForUser`, `listByUser`.
+ * Each package used to hand-roll the same three steps: assert `impl` is an
+ * object, assert its required methods are functions, then `Promise.resolve()`
+ * -wrap every call so a sync implementation is transparently promoted to the
+ * async store interface. Only the method-name arrays and the typed error
+ * differ. This collapses all of that into one binding per package.
  *
- * @param {Partial<import('../index.js').ApiKeyStore>} impl
- * @returns {import('../index.js').ApiKeyStore}
+ * Consumers: `apikey`, `challenge`, `magic-link`, `opaque`, `session`.
  */
 
-const REQUIRED = ['put', 'getById', 'update', 'revoke', 'revokeAllForUser', 'listByUser'];
 
-function customStore(impl) {
+/**
+ * Assert `impl` is an object exposing every method in `required` as a function.
+ * Throws the caller's typed error (via `wrap`) on the first failure. Used on
+ * its own by stores that keep a caller's implementation verbatim (jwt / paseto
+ * token registries), and internally by {@link createCustomStoreValidator}.
+ *
+ * @param {unknown} impl
+ * @param {readonly string[]} required
+ * @param {(message: string) => Error} wrap
+ *   The package's error factory; its returned error is thrown. A `wrap` that
+ *   throws directly also works (the outer `throw` is then unreachable).
+ * @returns {void}
+ */
+function assertStoreShape(impl, required, wrap) {
   if (!isObject(impl)) {
-    throw invalidArgument(`customStore(impl) requires an object with { ${REQUIRED.join(', ')} } methods`);
+    throw wrap(`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`);
+  for (const name of required) {
+    if (!isFunction(/** @type {any} */ (impl)[name])) {
+      throw wrap(`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)),
+}
+
+/**
+ * @param {object} spec
+ * @param {readonly string[]} spec.required
+ *   Methods that must exist on `impl`; missing ones fail at construction time.
+ * @param {readonly string[]} [spec.optional]
+ *   Methods wrapped through only when present (feature-gated store extras).
+ * @param {(message: string) => Error} spec.wrap
+ *   The package's error factory (its `invalidArgument`) — called with a
+ *   diagnostic message; its returned typed error is thrown so
+ *   `err instanceof <Pkg>Error` holds. A `wrap` that throws directly also
+ *   works (the outer `throw` is then unreachable).
+ * @param {Record<string, (result: any) => any>} [spec.coerce]
+ *   Optional per-method post-processor applied to the resolved result — e.g.
+ *   opaque coerces `set` to `undefined` so a native `Map.set` return value
+ *   can't leak out as `Promise<Map>`.
+ * @returns {(impl: object) => Record<string, (...args: any[]) => Promise<any>>}
+ */
+function createCustomStoreValidator({ required, optional = [], wrap, coerce = {} }) {
+  return function customStore(impl) {
+    assertStoreShape(impl, required, wrap);
+
+    /** @type {Record<string, (...args: any[]) => Promise<any>>} */
+    const store = {};
+    const bind = name => {
+      const post = coerce[name];
+      store[name] = post
+        ? (...args) => Promise.resolve(impl[name](...args)).then(post)
+        : (...args) => Promise.resolve(impl[name](...args));
+    };
+
+    for (const name of required) {
+      bind(name);
+    }
+    for (const name of optional) {
+      if (isFunction(impl[name])) {
+        bind(name);
+      }
+    }
+    return store;
   };
 }
 
+/**
+ * Wrap a user-supplied store into the `ApiKeyStore` interface. Validates the
+ * required methods at construction time (not on first use) and promotes sync
+ * implementations to the async interface.
+ *
+ * Required: `put`, `getById`, `update`, `revoke`, `revokeAllForUser`, `listByUser`.
+ *
+ * @param {Partial<import('../index.js').ApiKeyStore>} impl
+ * @returns {import('../index.js').ApiKeyStore}
+ */
+
+const customStore = createCustomStoreValidator({
+  required: ['put', 'getById', 'update', 'revoke', 'revokeAllForUser', 'listByUser'],
+  wrap: invalidArgument,
+});
+
 export { customStore, memoryStore, redisStore };

package/dist/token.d.ts

@@ -84,5 +84,6 @@ export function candidateHashesFor(rawSecret: string, peppers: Buffer[] | null):
  * @returns {string}
  */
 export function mask(key: string): string;
+export const _nodeTimingSafeEqual: any;
+export const _isBytes: typeof isBytes;
 import { isBytes } from '@exortek/shared/predicates';
-export { nodeTimingSafeEqual as _nodeTimingSafeEqual, isBytes as _isBytes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exortek/apikey",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "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,
@@ -36,7 +36,7 @@
     "/LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist tsconfig.tsbuildinfo && rollup -c rollup.config.js && tsc -p tsconfig.json",
+    "build": "rm -rf dist tsconfig.tsbuildinfo && rollup -c rollup.config.js && tsc -p tsconfig.json && rollup -c ../../rollup.dts.config.mjs",
     "build:watch": "rollup -c rollup.config.js --watch",
     "build:types": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",