@daloyjs/core 1.0.0-beta.6 → 1.0.0-beta.7

package/dist/errors.js

@@ -37,6 +37,7 @@ export const SAFE_CUSTOM_ERROR_RESPONSE_HEADERS = new Set([
  * @since 0.32.0
  */
 export class MessageLeakError extends Error {
+    /** The refused headers, each with its name and the reason it was disallowed. */
     offendingHeaders;
     constructor(offendingHeaders) {
         const summary = offendingHeaders
@@ -53,6 +54,10 @@ export class MessageLeakError extends Error {
 /**
  * @internal — header-safety check applied by {@link httpError} when a custom
  * `res` is supplied. Exported for audits and tests.
+ *
+ * @param headers Headers of the caller-supplied custom error `Response`.
+ * @returns The disallowed headers (name plus refusal reason); an empty array
+ *   means every header passed the safe-error-response allowlist.
  */
 export function checkCustomErrorResponseHeaders(headers) {
     const offending = [];
@@ -111,6 +116,12 @@ function shouldCopyCustomErrorHeader(name, value) {
  * Build an {@link HttpError} with optional safe-header extraction from a
  * custom `Response`. See {@link HttpErrorOptions}.
  *
+ * @param opts Status, problem document, plain headers, and the optional
+ *   custom `res` whose safe headers are merged (never overwriting
+ *   caller-supplied headers; `Content-Length` is always dropped).
+ * @returns The constructed {@link HttpError}, ready to be thrown.
+ * @throws MessageLeakError in production under `secureDefaults` when the
+ *   custom `res` carries headers outside the safe allowlist.
  * @since 0.32.0
  */
 export function httpError(opts) {
@@ -173,8 +184,11 @@ export function httpError(opts) {
  * @since 0.1.0
  */
 export class HttpError extends Error {
+    /** HTTP status code of the rendered response. */
     status;
+    /** RFC 9457 problem document; `type` defaults to `https://httpstatuses.io/<status>`. */
     problem;
+    /** Extra response headers (e.g. `Retry-After`, `Allow`) merged onto the response. */
     headers;
     constructor(status, problem, headers) {
         super(problem.title);

package/dist/etag.d.ts

@@ -42,6 +42,8 @@ export interface ETagOptions {
  * app.use(etag());
  * ```
  *
+ * @param opts - `weak: true` emits `W/"..."` weak validators (default strong); `generator` replaces the default SHA-1 body digest.
+ * @returns A {@link Hooks} bundle (an `onSend` hook) to compose via `app.use()`.
  * @since 0.21.0
  */
 export declare function etag(opts?: ETagOptions): Hooks;

package/dist/etag.js

@@ -71,6 +71,8 @@ function inmMatches(headerValue, candidate) {
  * app.use(etag());
  * ```
  *
+ * @param opts - `weak: true` emits `W/"..."` weak validators (default strong); `generator` replaces the default SHA-1 body digest.
+ * @returns A {@link Hooks} bundle (an `onSend` hook) to compose via `app.use()`.
  * @since 0.21.0
  */
 export function etag(opts = {}) {

package/dist/fetch-guard.d.ts

@@ -102,8 +102,11 @@ export type SsrfBlockReason = "protocol-not-allowed" | "host-not-allowed" | "dns
  * @since 0.34.0
  */
 export declare class SsrfBlockedError extends Error {
+    /** The request URL (or redirect target) that was refused. */
     readonly url: string;
+    /** Machine-readable {@link SsrfBlockReason} explaining the refusal. */
     readonly reason: SsrfBlockReason;
+    /** The resolved IP that tripped the guard, when the block was address-based. */
     readonly address?: string;
     constructor(url: string, reason: SsrfBlockReason, address?: string);
 }
@@ -240,6 +243,10 @@ export interface FetchGuardOptions {
  * });
  * ```
  *
+ * @param options - Guard configuration; see {@link FetchGuardOptions}. Omit
+ *   for the strict default posture (public IPs over `http:`/`https:` only).
+ * @returns A `fetch`-compatible function that validates every hop (including
+ *   redirects) and throws {@link SsrfBlockedError} on refusal.
  * @since 0.34.0
  */
 export declare function fetchGuard(options?: FetchGuardOptions): typeof fetch;

package/dist/fetch-guard.js

@@ -96,8 +96,11 @@ import { compileCidrMatcher, matchesMatcher, parseIp } from "./ip-restriction.js
  * @since 0.34.0
  */
 export class SsrfBlockedError extends Error {
+    /** The request URL (or redirect target) that was refused. */
     url;
+    /** Machine-readable {@link SsrfBlockReason} explaining the refusal. */
     reason;
+    /** The resolved IP that tripped the guard, when the block was address-based. */
     address;
     constructor(url, reason, address) {
         const where = address ? ` -> ${address}` : "";
@@ -155,6 +158,10 @@ const UNIQUE_LOCAL = ["fc00::/7"];
  * });
  * ```
  *
+ * @param options - Guard configuration; see {@link FetchGuardOptions}. Omit
+ *   for the strict default posture (public IPs over `http:`/`https:` only).
+ * @returns A `fetch`-compatible function that validates every hop (including
+ *   redirects) and throws {@link SsrfBlockedError} on refusal.
  * @since 0.34.0
  */
 export function fetchGuard(options = {}) {

package/dist/fetch-resilience.d.ts

@@ -290,6 +290,10 @@ export interface ResilientFetchOptions {
  * const safeFetch = resilientFetch({ fetch: fetchGuard(), timeoutMs: 2_000 });
  * ```
  *
+ * @param options - Timeout (default 10000 ms), retry policy (default 2 retries, exponential backoff with jitter, `Retry-After` respected), circuit-breaker config (`false` disables), and the base `fetch`.
+ * @returns A drop-in `fetch` replacement applying the configured resilience layers.
+ * @throws {Error} When no global `fetch` exists and `options.fetch` is not provided.
+ * @throws {RangeError} When `timeoutMs` is negative/non-finite or `retries` is not a non-negative integer.
  * @since 0.37.0
  */
 export declare function resilientFetch(options?: ResilientFetchOptions): typeof fetch;

package/dist/fetch-resilience.js

@@ -355,6 +355,10 @@ function isAbortError(err) {
  * const safeFetch = resilientFetch({ fetch: fetchGuard(), timeoutMs: 2_000 });
  * ```
  *
+ * @param options - Timeout (default 10000 ms), retry policy (default 2 retries, exponential backoff with jitter, `Retry-After` respected), circuit-breaker config (`false` disables), and the base `fetch`.
+ * @returns A drop-in `fetch` replacement applying the configured resilience layers.
+ * @throws {Error} When no global `fetch` exists and `options.fetch` is not provided.
+ * @throws {RangeError} When `timeoutMs` is negative/non-finite or `retries` is not a non-negative integer.
  * @since 0.37.0
  */
 export function resilientFetch(options = {}) {

package/dist/http-signatures.d.ts

@@ -129,6 +129,10 @@ export interface MessageSignature {
  * Compute HTTP Message Signature header values (RFC 9421) over the described
  * message.
  *
+ * @param opts - Message description, covered components, algorithm, and key;
+ *   see {@link SignMessageOptions}.
+ * @returns The `Signature-Input` / `Signature` header values plus the exact
+ *   signature base that was signed.
  * @throws {TypeError} for unsupported algorithms, weak HMAC keys, or
  *   unserializable parameter values.
  * @throws {Error} when a covered component cannot be resolved (e.g. a covered
@@ -148,6 +152,11 @@ export type SignRequestOptions = Omit<SignMessageOptions, "method" | "url" | "he
  * `Signature` and `Signature-Input` headers attached. The original request is
  * not mutated.
  *
+ * @param request - The outbound request to sign; its method, URL, and headers
+ *   form the signature base.
+ * @param opts - Signing options minus the per-message fields; see
+ *   {@link SignRequestOptions}.
+ * @returns A new `Request` carrying the signature headers.
  * @since 0.37.0
  */
 export declare function signRequest(request: Request, opts: SignRequestOptions): Promise<Request>;
@@ -164,6 +173,7 @@ export interface KeyResolutionInfo {
 }
 /** Successful verification result. */
 export interface VerifySuccess {
+    /** Discriminant: always `true` on success. */
     valid: true;
     /** The verified signature label. */
     label: string;
@@ -184,6 +194,7 @@ export interface VerifySuccess {
 }
 /** Failed verification result. Never throws on a bad signature. */
 export interface VerifyFailure {
+    /** Discriminant: always `false` on failure. */
     valid: false;
     /** Stable machine-readable reason code. */
     reason: string;
@@ -242,6 +253,13 @@ export interface VerifyMessageOptions {
  * structured result and never throws on a bad/forged signature — only on a
  * programming error (e.g. WebCrypto unavailable).
  *
+ * @param opts - Received message plus verification policy (algorithm
+ *   allowlist, key resolver, freshness / replay checks); see
+ *   {@link VerifyMessageOptions}.
+ * @returns A {@link VerifySuccess} with the verified parameters, or a
+ *   {@link VerifyFailure} with a stable `reason` code.
+ * @throws {TypeError} when the `algorithms` allowlist is missing or empty;
+ *   there is no implicit "accept any" mode.
  * @since 0.37.0
  */
 export declare function verifyMessage(opts: VerifyMessageOptions): Promise<VerifyResult>;
@@ -250,6 +268,9 @@ export declare function verifyMessage(opts: VerifyMessageOptions): Promise<Verif
  * over {@link verifyMessage} that pulls the method, URL, and headers from the
  * request.
  *
+ * @param request - The inbound request carrying `Signature` / `Signature-Input`.
+ * @param opts - Verification policy minus the per-message fields.
+ * @returns The {@link VerifyResult}; never rejects on a bad signature.
  * @since 0.37.0
  */
 export declare function verifyRequest(request: Request, opts: Omit<VerifyMessageOptions, "method" | "url" | "headers" | "status">): Promise<VerifyResult>;
@@ -277,6 +298,9 @@ export interface HttpSignatureAuthOptions extends Omit<VerifyMessageOptions, "me
  * a missing (unless `optional`) or invalid signature it throws
  * {@link UnauthorizedError} (`401` + `Cache-Control: no-store`).
  *
+ * @param opts - Verification policy plus middleware knobs; see
+ *   {@link HttpSignatureAuthOptions}.
+ * @returns A {@link Hooks} object to pass to `app.use()` or a route's `hooks`.
  * @since 0.37.0
  */
 export declare function httpSignatureAuth(opts: HttpSignatureAuthOptions): Hooks;
@@ -288,6 +312,10 @@ export type ContentDigestAlgorithm = "sha-256" | "sha-512";
  * bind the request body into the signature, then re-check it against the
  * received body with {@link verifyContentDigest}.
  *
+ * @param body - Raw body bytes, or a string encoded as UTF-8.
+ * @param opts - Optional `algorithm` choice. Defaults to `"sha-256"`.
+ * @returns The structured-field header value, e.g. `sha-256=:<base64>:`.
+ * @throws {TypeError} for an unsupported digest algorithm.
  * @since 0.37.0
  */
 export declare function contentDigest(body: Uint8Array | string, opts?: {
@@ -298,6 +326,10 @@ export declare function contentDigest(body: Uint8Array | string, opts?: {
  * Returns `false` for any malformed header or mismatch (never throws on bad
  * input). Only `sha-256` / `sha-512` members are considered.
  *
+ * @param header - The received `Content-Digest` header value.
+ * @param body - Raw body bytes, or a string encoded as UTF-8.
+ * @returns `true` only when at least one supported digest member matched
+ *   (compared in constant time); `false` for mismatch or malformed input.
  * @since 0.37.0
  */
 export declare function verifyContentDigest(header: string, body: Uint8Array | string): Promise<boolean>;

package/dist/http-signatures.js

@@ -471,6 +471,10 @@ function parseComponentSpec(spec) {
  * Compute HTTP Message Signature header values (RFC 9421) over the described
  * message.
  *
+ * @param opts - Message description, covered components, algorithm, and key;
+ *   see {@link SignMessageOptions}.
+ * @returns The `Signature-Input` / `Signature` header values plus the exact
+ *   signature base that was signed.
  * @throws {TypeError} for unsupported algorithms, weak HMAC keys, or
  *   unserializable parameter values.
  * @throws {Error} when a covered component cannot be resolved (e.g. a covered
@@ -513,6 +517,11 @@ export async function signMessage(opts) {
  * `Signature` and `Signature-Input` headers attached. The original request is
  * not mutated.
  *
+ * @param request - The outbound request to sign; its method, URL, and headers
+ *   form the signature base.
+ * @param opts - Signing options minus the per-message fields; see
+ *   {@link SignRequestOptions}.
+ * @returns A new `Request` carrying the signature headers.
  * @since 0.37.0
  */
 export async function signRequest(request, opts) {
@@ -535,6 +544,13 @@ function fail(reason) {
  * structured result and never throws on a bad/forged signature — only on a
  * programming error (e.g. WebCrypto unavailable).
  *
+ * @param opts - Received message plus verification policy (algorithm
+ *   allowlist, key resolver, freshness / replay checks); see
+ *   {@link VerifyMessageOptions}.
+ * @returns A {@link VerifySuccess} with the verified parameters, or a
+ *   {@link VerifyFailure} with a stable `reason` code.
+ * @throws {TypeError} when the `algorithms` allowlist is missing or empty;
+ *   there is no implicit "accept any" mode.
  * @since 0.37.0
  */
 export async function verifyMessage(opts) {
@@ -688,6 +704,9 @@ export async function verifyMessage(opts) {
  * over {@link verifyMessage} that pulls the method, URL, and headers from the
  * request.
  *
+ * @param request - The inbound request carrying `Signature` / `Signature-Input`.
+ * @param opts - Verification policy minus the per-message fields.
+ * @returns The {@link VerifyResult}; never rejects on a bad signature.
  * @since 0.37.0
  */
 export function verifyRequest(request, opts) {
@@ -704,6 +723,9 @@ export function verifyRequest(request, opts) {
  * a missing (unless `optional`) or invalid signature it throws
  * {@link UnauthorizedError} (`401` + `Cache-Control: no-store`).
  *
+ * @param opts - Verification policy plus middleware knobs; see
+ *   {@link HttpSignatureAuthOptions}.
+ * @returns A {@link Hooks} object to pass to `app.use()` or a route's `hooks`.
  * @since 0.37.0
  */
 export function httpSignatureAuth(opts) {
@@ -736,6 +758,10 @@ function toBytes(body) {
  * bind the request body into the signature, then re-check it against the
  * received body with {@link verifyContentDigest}.
  *
+ * @param body - Raw body bytes, or a string encoded as UTF-8.
+ * @param opts - Optional `algorithm` choice. Defaults to `"sha-256"`.
+ * @returns The structured-field header value, e.g. `sha-256=:<base64>:`.
+ * @throws {TypeError} for an unsupported digest algorithm.
  * @since 0.37.0
  */
 export async function contentDigest(body, opts = {}) {
@@ -752,6 +778,10 @@ export async function contentDigest(body, opts = {}) {
  * Returns `false` for any malformed header or mismatch (never throws on bad
  * input). Only `sha-256` / `sha-512` members are considered.
  *
+ * @param header - The received `Content-Digest` header value.
+ * @param body - Raw body bytes, or a string encoded as UTF-8.
+ * @returns `true` only when at least one supported digest member matched
+ *   (compared in constant time); `false` for mismatch or malformed input.
  * @since 0.37.0
  */
 export async function verifyContentDigest(header, body) {

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export { validate, isStandardSchema } from "./schema.js";
 export { diffOpenAPI, hasBreakingChanges } from "./openapi-diff.js";
 export type { ChangeSeverity, OpenAPIChange, OpenAPIDiffResult } from "./openapi-diff.js";
 export { MCP_DEFAULT_MAX_BODY_BYTES, MCP_PROTOCOL_VERSION, MCP_PROTOCOL_VERSIONS, McpToolError, createMcpHandler, mcpRoutes, } from "./mcp.js";
-export type { McpContent, McpEmbeddedResourceContent, McpHandler, McpHandlerOptions, McpImageContent, McpJsonObject, McpJsonRpcId, McpJsonSchema, McpJsonValue, McpPrompt, McpPromptArgument, McpPromptDefinition, McpPromptMessage, McpPromptResult, McpRequestContext, McpResource, McpResourceContents, McpResourceDefinition, McpServerInfo, McpTextContent, McpTool, McpToolHandler, McpToolResult, } from "./mcp.js";
+export type { McpContent, McpEmbeddedResourceContent, McpHandler, McpHandlerOptions, McpIcon, McpImageContent, McpJsonObject, McpJsonRpcId, McpJsonSchema, McpJsonValue, McpPrompt, McpPromptArgument, McpPromptDefinition, McpPromptMessage, McpPromptResult, McpRequestContext, McpResource, McpResourceContents, McpResourceDefinition, McpResourceTemplate, McpResourceTemplateDefinition, McpServerInfo, McpTextContent, McpTool, McpToolAnnotations, McpToolHandler, McpToolResult, } from "./mcp.js";
 export { readBodyLimited, safeJsonParse, isForbiddenObjectKey, sanitizeHeaderName, sanitizeHeaderValue, timingSafeEqual, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, RESERVED_INBOUND_HEADER_PREFIXES, SMUGGLING_SINGLETON_HEADERS, verifyWebhookSignature, signWebhookPayload, WEBHOOK_DEFAULT_TOLERANCE_SECONDS, assertStrongSecret, MIN_PROD_SECRET_BYTES, WEAK_SECRET_STRINGS, sanitizeFilename, assertSafeRelativePath, hasMongoOperatorKeys, assertNoMongoOperators, } from "./security.js";
 export type { WebhookHmacAlgorithm } from "./security.js";
 export { requestId, secureHeaders, SECURE_HEADERS_MARKER, cors, CORS_HOOK_MARKER, CORS_ORIGIN_ALLOW_MARKER, CORS_WILDCARD_ORIGIN_MARKER, rateLimit, loginThrottle, timing, bearerAuth, basicAuth, csrf, CSRF_HOOK_MARKER, fetchMetadata, requireScopes, REQUIRE_SCOPES_AGGREGATE_KEY, REQUIRE_SCOPES_HOOK_MARKER, _resetSharedRateLimitStoresForTests, } from "./middleware.js";

package/dist/ip-restriction.d.ts

@@ -53,13 +53,18 @@ export interface IpRestrictionOptions {
 }
 /** @internal Parsed IP address (shared with `fetchGuard()`). */
 export interface ParsedIp {
+    /** Big-endian address bytes: 4 bytes for IPv4, 16 for IPv6. */
     bytes: Uint8Array;
+    /** Address family: `4` for IPv4, `6` for IPv6. */
     family: 4 | 6;
 }
 /** @internal Compiled CIDR matcher (shared with `fetchGuard()`). */
 export interface IpMatcher {
+    /** Address family the matcher applies to: `4` or `6`. */
     family: 4 | 6;
+    /** CIDR prefix length in bits (0-32 for IPv4, 0-128 for IPv6). */
     prefix: number;
+    /** Network address bytes with all host bits masked to zero. */
     bytes: Uint8Array;
 }
 /**
@@ -80,12 +85,44 @@ export interface IpMatcher {
  * On reject the middleware throws a {@link ForbiddenError}, which Daloy
  * renders as RFC 9457 `application/problem+json`.
  *
+ * @param opts Allow/deny lists plus IP-resolution options; see
+ *   {@link IpRestrictionOptions}. Deny matches always win over allow.
+ * @returns A {@link Hooks} object whose `beforeHandle` enforces the lists,
+ *   failing closed (403) when the client IP cannot be resolved or parsed.
+ * @throws Error at setup time when neither `allow` nor `deny` is provided,
+ *   or when a pattern is not a valid IP/CIDR.
  * @since 0.19.0
  */
 export declare function ipRestriction(opts: IpRestrictionOptions): Hooks;
-/** @internal */
+/**
+ * Test whether a parsed IP falls inside a compiled CIDR matcher, comparing
+ * only the matcher's prefix bits. IPv4-mapped IPv6 addresses
+ * (`::ffff:a.b.c.d`) are normalized so they match IPv4 matchers.
+ *
+ * @param ip Parsed client address from {@link parseIp}.
+ * @param m Compiled matcher from {@link compileCidrMatcher}.
+ * @returns `true` when the address is within the matcher's range.
+ * @internal
+ */
 export declare function matchesMatcher(ip: ParsedIp, m: IpMatcher): boolean;
-/** @internal */
+/**
+ * Compile an IP or CIDR pattern (e.g. `"10.0.0.0/8"`, `"::1"`) into an
+ * {@link IpMatcher}. A bare address gets a full-length prefix (/32 or /128);
+ * host bits beyond the prefix are masked to zero.
+ *
+ * @param input IPv4/IPv6 address, optionally with a `/prefix` suffix.
+ * @returns The compiled matcher used by {@link matchesMatcher}.
+ * @throws Error when the address or CIDR prefix is invalid.
+ * @internal
+ */
 export declare function compileCidrMatcher(input: string): IpMatcher;
-/** @internal */
+/**
+ * Parse an IPv4 or IPv6 address string into raw bytes. Supports IPv6 `::`
+ * compression and IPv4-mapped tails (`::ffff:1.2.3.4`).
+ *
+ * @param input Address string; surrounding whitespace is trimmed.
+ * @returns The parsed address, or `undefined` when the input is not a valid
+ *   IP (callers treat unparseable addresses as a rejection, failing closed).
+ * @internal
+ */
 export declare function parseIp(input: string): ParsedIp | undefined;

package/dist/ip-restriction.js

@@ -26,6 +26,12 @@ import { ForbiddenError } from "./errors.js";
  * On reject the middleware throws a {@link ForbiddenError}, which Daloy
  * renders as RFC 9457 `application/problem+json`.
  *
+ * @param opts Allow/deny lists plus IP-resolution options; see
+ *   {@link IpRestrictionOptions}. Deny matches always win over allow.
+ * @returns A {@link Hooks} object whose `beforeHandle` enforces the lists,
+ *   failing closed (403) when the client IP cannot be resolved or parsed.
+ * @throws Error at setup time when neither `allow` nor `deny` is provided,
+ *   or when a pattern is not a valid IP/CIDR.
  * @since 0.19.0
  */
 export function ipRestriction(opts) {
@@ -64,7 +70,16 @@ function forwardedIpResolver(ctx) {
         return forwarded.split(",")[0]?.trim();
     return headers.get("x-real-ip") ?? undefined;
 }
-/** @internal */
+/**
+ * Test whether a parsed IP falls inside a compiled CIDR matcher, comparing
+ * only the matcher's prefix bits. IPv4-mapped IPv6 addresses
+ * (`::ffff:a.b.c.d`) are normalized so they match IPv4 matchers.
+ *
+ * @param ip Parsed client address from {@link parseIp}.
+ * @param m Compiled matcher from {@link compileCidrMatcher}.
+ * @returns `true` when the address is within the matcher's range.
+ * @internal
+ */
 export function matchesMatcher(ip, m) {
     const candidate = normalizeFamily(ip, m.family);
     if (!candidate)
@@ -83,7 +98,16 @@ export function matchesMatcher(ip, m) {
     const mask = 0xff << (8 - remaining);
     return ((candidate[fullBytes] ^ expected[fullBytes]) & mask) === 0;
 }
-/** @internal */
+/**
+ * Compile an IP or CIDR pattern (e.g. `"10.0.0.0/8"`, `"::1"`) into an
+ * {@link IpMatcher}. A bare address gets a full-length prefix (/32 or /128);
+ * host bits beyond the prefix are masked to zero.
+ *
+ * @param input IPv4/IPv6 address, optionally with a `/prefix` suffix.
+ * @returns The compiled matcher used by {@link matchesMatcher}.
+ * @throws Error when the address or CIDR prefix is invalid.
+ * @internal
+ */
 export function compileCidrMatcher(input) {
     let addr = input;
     let prefixStr;
@@ -135,7 +159,15 @@ function applyPrefixMask(bytes, prefix) {
     }
     return out;
 }
-/** @internal */
+/**
+ * Parse an IPv4 or IPv6 address string into raw bytes. Supports IPv6 `::`
+ * compression and IPv4-mapped tails (`::ffff:1.2.3.4`).
+ *
+ * @param input Address string; surrounding whitespace is trimmed.
+ * @returns The parsed address, or `undefined` when the input is not a valid
+ *   IP (callers treat unparseable addresses as a rejection, failing closed).
+ * @internal
+ */
 export function parseIp(input) {
     const trimmed = input.trim();
     if (trimmed.includes(":"))

package/dist/jwk.d.ts

@@ -4,6 +4,7 @@ import type { BaseContext, Hooks } from "./types.js";
 export type JwkAlgorithm = Exclude<JwtAlgorithm, "HS256" | "HS384" | "HS512">;
 /** Minimal JWKS document shape (RFC 7517 §5). */
 export interface JwkSet {
+    /** Public JWKs; each entry should carry a `kid` so tokens can select their key. */
     keys: JsonWebKey[];
 }
 /**
@@ -13,7 +14,11 @@ export interface JwkSet {
 export type JwkSource = JwkSet | string | (() => JwkSet | Promise<JwkSet>);
 /** Per-request payload-revalidation hook. */
 export type JwkVerifyHook = (payload: Record<string, unknown>, ctx: BaseContext<any, any>) => boolean | void | Promise<boolean | void>;
-/** Options for {@link jwk}. */
+/**
+ * Options for {@link jwk}: the JWKS source and asymmetric algorithm allowlist
+ * are required; issuer / audience / clock-skew checks, JWKS fetch caching,
+ * and a per-request revalidation hook are opt-in.
+ */
 export interface JwkOptions {
     /** JWKS source (object, URL, or resolver). */
     jwks: JwkSource;
@@ -91,6 +96,12 @@ export interface JwkOptions {
  * });
  * ```
  *
+ * @param opts - JWKS source, algorithm allowlist, and claim checks; see
+ *   {@link JwkOptions}.
+ * @returns A {@link Hooks} object to pass to `app.use()` or a route's `hooks`;
+ *   failed auth yields a `401` problem+json with `WWW-Authenticate`.
+ * @throws {Error} at construction for missing options, an empty or
+ *   symmetric-containing allowlist, invalid TTLs, or a malformed realm.
  * @since 0.22.0
  */
 export declare function jwk(opts: JwkOptions): Hooks;

package/dist/jwk.js

@@ -161,6 +161,12 @@ function makeJwksLoader(source, fetchImpl, ttlSeconds, maxStaleSeconds) {
  * });
  * ```
  *
+ * @param opts - JWKS source, algorithm allowlist, and claim checks; see
+ *   {@link JwkOptions}.
+ * @returns A {@link Hooks} object to pass to `app.use()` or a route's `hooks`;
+ *   failed auth yields a `401` problem+json with `WWW-Authenticate`.
+ * @throws {Error} at construction for missing options, an empty or
+ *   symmetric-containing allowlist, invalid TTLs, or a malformed realm.
  * @since 0.22.0
  */
 export function jwk(opts) {

package/dist/jwt.d.ts

@@ -23,19 +23,24 @@ export type JwtAlgorithm = "HS256" | "HS384" | "HS512" | "RS256" | "RS384" | "RS
 export declare const DEFAULT_JWT_MAX_LIFETIME_SECONDS: number;
 /** Structured error thrown by every JWT helper. */
 export declare class JwtError extends Error {
+    /** Stable machine-readable error code (e.g. `"alg_none_refused"`, `"weak_hs_secret"`). */
     readonly code: string;
     constructor(code: string, message: string);
 }
 /** Result of a successful verify. */
 export interface JwtVerified {
+    /** Decoded JOSE header (`alg`, `kid`, `typ`, ...). */
     readonly header: Record<string, unknown>;
+    /** Decoded claims payload after signature and time-claim checks passed. */
     readonly payload: Record<string, unknown>;
 }
 /** Key material accepted by the signer/verifier. */
 export type JwtKeyMaterial = CryptoKey | Uint8Array | JsonWebKey;
 /** Options for {@link createJwtSigner}. */
 export interface JwtSignerOptions {
+    /** Signing algorithm. `"none"` is always refused. */
     alg: JwtAlgorithm;
+    /** Signing key. HS* secrets shorter than 32 bytes and RSA keys under 2048 bits are refused. */
     key: JwtKeyMaterial;
     /**
      * Maximum allowed `exp - iat` window in seconds. Required: refuse-at-
@@ -98,6 +103,10 @@ export interface JwtVerifierOptions {
  * `acknowledgeNoExp: true` was set at construction outside production) and
  * refuses payloads whose `exp - (iat | now)` exceeds `maxLifetimeSeconds`.
  *
+ * @param opts - Algorithm, key, and lifetime policy; see {@link JwtSignerOptions}.
+ * @returns An object whose `sign(payload)` resolves to the compact JWS string.
+ * @throws {JwtError} for `alg: "none"`, unknown algorithms, weak keys, a
+ *   missing/invalid `maxLifetimeSeconds`, or `acknowledgeNoExp` in production.
  * @since 0.21.0
  */
 export declare function createJwtSigner(opts: JwtSignerOptions): {
@@ -110,6 +119,11 @@ export declare function createJwtSigner(opts: JwtSignerOptions): {
  * refuses-at-construction when a symmetric algorithm (`HS*`) is mixed with
  * a JWK / JWKS-shaped key source (the documented confused-deputy attack).
  *
+ * @param opts - Allowlist, key source, and claim checks; see {@link JwtVerifierOptions}.
+ * @returns An object whose `verify(token)` resolves to the decoded
+ *   {@link JwtVerified} or rejects with {@link JwtError}.
+ * @throws {JwtError} at construction for an empty/invalid allowlist, `"none"`
+ *   in the allowlist, weak HS* secrets, or HS* mixed with a JWK source.
  * @since 0.21.0
  */
 export declare function createJwtVerifier(opts: JwtVerifierOptions): {

package/dist/jwt.js

@@ -60,6 +60,7 @@ const MIN_RSA_KEY_BITS = 2048;
 export const DEFAULT_JWT_MAX_LIFETIME_SECONDS = 30 * 24 * 60 * 60;
 /** Structured error thrown by every JWT helper. */
 export class JwtError extends Error {
+    /** Stable machine-readable error code (e.g. `"alg_none_refused"`, `"weak_hs_secret"`). */
     code;
     constructor(code, message) {
         super(`[${code}] ${message}`);
@@ -228,6 +229,10 @@ function buildSignAlgorithm(alg) {
  * `acknowledgeNoExp: true` was set at construction outside production) and
  * refuses payloads whose `exp - (iat | now)` exceeds `maxLifetimeSeconds`.
  *
+ * @param opts - Algorithm, key, and lifetime policy; see {@link JwtSignerOptions}.
+ * @returns An object whose `sign(payload)` resolves to the compact JWS string.
+ * @throws {JwtError} for `alg: "none"`, unknown algorithms, weak keys, a
+ *   missing/invalid `maxLifetimeSeconds`, or `acknowledgeNoExp` in production.
  * @since 0.21.0
  */
 export function createJwtSigner(opts) {
@@ -326,6 +331,11 @@ function normalizeStringSet(value) {
  * refuses-at-construction when a symmetric algorithm (`HS*`) is mixed with
  * a JWK / JWKS-shaped key source (the documented confused-deputy attack).
  *
+ * @param opts - Allowlist, key source, and claim checks; see {@link JwtVerifierOptions}.
+ * @returns An object whose `verify(token)` resolves to the decoded
+ *   {@link JwtVerified} or rejects with {@link JwtError}.
+ * @throws {JwtError} at construction for an empty/invalid allowlist, `"none"`
+ *   in the allowlist, weak HS* secrets, or HS* mixed with a JWK source.
  * @since 0.21.0
  */
 export function createJwtVerifier(opts) {

package/dist/load-shedding.d.ts

@@ -65,6 +65,9 @@ export interface LoadSheddingSnapshot {
  *   retryAfterSeconds: 5,
  * }));
  * ```
+ *
+ * @param opts - Pressure thresholds (event-loop delay default 1000 ms, ELU default 0.98, optional heap/RSS byte caps), sampling interval, `Retry-After` seconds, and an optional custom `healthCheck`.
+ * @returns A {@link Hooks} bundle that sheds requests with `503` + `Retry-After` while pressure thresholds are exceeded.
  */
 export declare function loadShedding(opts?: LoadSheddingOptions): Hooks;
 /**

package/dist/load-shedding.js

@@ -37,6 +37,9 @@ async function tryLoadPerfHooks() {
  *   retryAfterSeconds: 5,
  * }));
  * ```
+ *
+ * @param opts - Pressure thresholds (event-loop delay default 1000 ms, ELU default 0.98, optional heap/RSS byte caps), sampling interval, `Retry-After` seconds, and an optional custom `healthCheck`.
+ * @returns A {@link Hooks} bundle that sheds requests with `503` + `Retry-After` while pressure thresholds are exceeded.
  */
 export function loadShedding(opts = {}) {
     const maxDelay = opts.maxEventLoopDelayMs ?? 1000;

package/dist/logger.d.ts

@@ -10,13 +10,21 @@ export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
  * thin adapter; the default implementation is {@link createLogger}.
  */
 export interface Logger {
+    /** Minimum level emitted; records below this level are dropped. */
     level: LogLevel;
+    /** Log at `trace` level. Pass a fields object plus optional message, or a message string. */
     trace(obj: object | string, msg?: string): void;
+    /** Log at `debug` level. Pass a fields object plus optional message, or a message string. */
     debug(obj: object | string, msg?: string): void;
+    /** Log at `info` level. Pass a fields object plus optional message, or a message string. */
     info(obj: object | string, msg?: string): void;
+    /** Log at `warn` level. Pass a fields object plus optional message, or a message string. */
     warn(obj: object | string, msg?: string): void;
+    /** Log at `error` level. Pass a fields object plus optional message, or a message string. */
     error(obj: object | string, msg?: string): void;
+    /** Log at `fatal` level. Pass a fields object plus optional message, or a message string. */
     fatal(obj: object | string, msg?: string): void;
+    /** Return a derived logger whose records always include `bindings` merged into each record. */
     child(bindings: Record<string, unknown>): Logger;
 }
 /**
@@ -63,7 +71,9 @@ export interface LoggerRedactionOptions {
 export declare const DEFAULT_REDACT_KEYS: readonly string[];
 /** Options for {@link createLogger}. */
 export interface ConsoleLoggerOptions {
+    /** Minimum level to emit. Defaults to `"info"`. */
     level?: LogLevel;
+    /** Fields merged into every record emitted by this logger and its children. */
     bindings?: Record<string, unknown>;
     /** Where to write. Defaults to process.stdout.write or console.log. */
     write?: (line: string) => void;
@@ -89,6 +99,9 @@ interface ResolvedRedaction {
  * `cfg.redactJwt` is on) with `cfg.censor`. Exported for direct use by
  * custom logger implementations that want the same defaults.
  *
+ * @param record - Log record to redact. Mutated in place (cycle-safe, depth-capped).
+ * @param cfg - Resolved redaction settings (key set, censor, JWT/credential toggles, max depth).
+ * @returns The same `record` object, for chaining.
  * @since 0.15.0
  */
 export declare function redactRecord(record: Record<string, unknown>, cfg: ResolvedRedaction): Record<string, unknown>;

package/dist/logger.js

@@ -123,6 +123,9 @@ function redactString(value, cfg) {
  * `cfg.redactJwt` is on) with `cfg.censor`. Exported for direct use by
  * custom logger implementations that want the same defaults.
  *
+ * @param record - Log record to redact. Mutated in place (cycle-safe, depth-capped).
+ * @param cfg - Resolved redaction settings (key set, censor, JWT/credential toggles, max depth).
+ * @returns The same `record` object, for chaining.
  * @since 0.15.0
  */
 export function redactRecord(record, cfg) {