@exortek/apikey 1.1.1 → 1.1.3

package/dist/middleware/express.cjs

@@ -137,20 +137,33 @@ function isBuffer(value) {
  * `@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.
+ * Every guard is exported as a `make…` **factory** taking the binding
+ * package's `wrap` and returning the guard itself. A package binds the
+ * guards it calls once, in its `internal/guards.js`, so every argument
+ * failure throws that package's error class — `err instanceof
+ * CryptoError` holds, and users see at a glance which package raised it.
+ *
+ *   // packages/<pkg>/src/internal/guards.js
+ *   import { makeAssertString, makeInvalidArgument } from '@exortek/shared/asserts';
+ *   import { CryptoError, ErrorCode } from '../errors.js';
+ *
+ *   const wrap = (message, extra) => new CryptoError(ErrorCode.INVALID_ARGUMENT, message, extra);
+ *
+ *   export const assertString = makeAssertString(wrap);
+ *   export const invalidArgument = makeInvalidArgument(wrap);
+ *
+ * Importing each factory by name is what makes the module
+ * tree-shakeable. An earlier version handed back one object carrying
+ * every guard, so all of them shipped in every package's bundle no
+ * matter how few were used — `assertBoolean` reached fifteen published
+ * packages without a single call site. Import what you call.
  *
  * **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
+ *   - `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>"`,
@@ -159,289 +172,17 @@ function isBuffer(value) {
  * 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.
+ * Construct (not throw) the bound error with a free-form message — for
+ * `throw invalidArgument('…')` sites that don't fit the `X must be Y`
+ * shape (canonicalisation errors, cross-field constraint failures). Pass
+ * `{ cause }` when the failure was triggered by an underlying throw whose
+ * chain matters (e.g. `JSON.stringify` on a bigint).
  *
- * @param {string} name
- * @param {string} description
- * @param {string} [hint]
- * @returns {string}
+ * @type {(wrap: WrapFn) => (msg: string, extra?: WrapExtra) => Error}
  */
-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));
-}
+const makeInvalidArgument = wrap => (msg, extra) => wrap(msg, extra);
 
 /**
  * Shared base error class — the single error structure behind every
@@ -552,10 +293,15 @@ class ApiKeyError extends BaseError {
  */
 
 
-const { invalidArgument} = defineGuards(
-  ApiKeyError,
-  ErrorCode.INVALID_ARGUMENT,
-);
+/**
+ * Bind every guard this package calls to ApiKeyError, so an argument-shape
+ * failure anywhere carries one class and one code to branch on.
+ *
+ * @type {import('@exortek/shared/asserts').WrapFn}
+ */
+const wrap = (message, extra) => new ApiKeyError(ErrorCode.INVALID_ARGUMENT, message, extra);
+
+const invalidArgument = makeInvalidArgument(wrap);
 
 /**
  * Scope match helpers.

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 };