@daloyjs/core 1.0.0-beta.6 → 1.0.0-rc.0

package/dist/discriminator.js

@@ -19,6 +19,11 @@
  * Build an OpenAPI 3.1 Discriminator Object. Throws on an empty
  * `propertyName` so misconfigurations fail at boot rather than producing a
  * silently invalid spec.
+ *
+ * @param propertyName Name of the property that selects the variant schema.
+ * @param mapping Optional explicit discriminator-value-to-$ref map.
+ * @returns A {@link DiscriminatorObject} ready to embed in an OpenAPI schema.
+ * @throws TypeError if `propertyName` is not a non-empty string.
  */
 export function discriminator(propertyName, mapping) {
     if (typeof propertyName !== "string" || propertyName.length === 0) {
@@ -35,6 +40,14 @@ export function discriminator(propertyName, mapping) {
  * const Cat = z.object({ kind: z.literal("cat"), meow: z.boolean() });
  * const Dog = z.object({ kind: z.literal("dog"), bark: z.boolean() });
  * const Animal = discriminatedUnion("kind", { cat: Cat, dog: Dog });
+ *
+ * @param propertyName Discriminator property read off the incoming value.
+ * @param variants Map from discriminator value to variant schema. Only own
+ *   properties are consulted, so prototype names like `constructor` cannot
+ *   be abused to bypass variant lookup.
+ * @param opts Optional {@link DiscriminatedUnionOptions} (explicit `mapping`, `vendor`).
+ * @returns A {@link DiscriminatedUnion} usable as validator and OpenAPI emitter.
+ * @throws TypeError if `propertyName` is empty or `variants` has no entries.
  */
 export function discriminatedUnion(propertyName, variants, opts) {
     if (typeof propertyName !== "string" || propertyName.length === 0) {
@@ -71,7 +84,16 @@ export function discriminatedUnion(propertyName, variants, opts) {
                     ],
                 };
             }
-            const variant = variants[discriminatorValue];
+            // Only accept an OWN property of the variant map. A bare
+            // `variants[discriminatorValue]` lookup would resolve inherited
+            // `Object.prototype` members (`constructor`, `toString`, `valueOf`,
+            // `hasOwnProperty`, `__proto__`, …) to a truthy non-variant, slipping
+            // past the `!variant` guard below; the subsequent `variant["~standard"]`
+            // access then throws an uncaught `TypeError` that the app surfaces as an
+            // unauthenticated 500 (and error-log flood) instead of a clean 400.
+            const variant = Object.hasOwn(variants, discriminatorValue)
+                ? variants[discriminatorValue]
+                : undefined;
             if (!variant) {
                 return {
                     issues: [

package/dist/docs.d.ts

@@ -24,72 +24,129 @@ export type ScalarTheme = "alternate" | "default" | "moon" | "purple" | "solariz
  */
 export interface ScalarReferenceConfiguration {
     [key: string]: ScalarJsonValue | undefined;
+    /** Built-in color theme name. See {@link ScalarTheme}. */
     theme?: ScalarTheme;
+    /** Extra CSS injected into the reference UI. */
     customCss?: string;
+    /** Start the UI in dark mode. */
     darkMode?: boolean;
+    /** Pin the color scheme and hide the user's ability to change it. */
     forceDarkModeState?: "dark" | "light";
+    /** Load Scalar's default fonts (Inter/JetBrains Mono) from its CDN. */
     withDefaultFonts?: boolean;
+    /** URL of the favicon shown in the browser tab. */
     favicon?: string;
+    /** Overall page layout: `"modern"` (default) or `"classic"`. */
     layout?: "modern" | "classic";
+    /** Hide the "Open API Client" button. */
     hideClientButton?: boolean;
+    /** Hide the dark-mode toggle. */
     hideDarkModeToggle?: boolean;
+    /** Hide the Models (schemas) section. */
     hideModels?: boolean;
+    /** Hide the search bar. */
     hideSearch?: boolean;
+    /** Hide the "Test Request" button on operations. */
     hideTestRequestButton?: boolean;
+    /** Show each operation's `operationId` next to its title. */
     showOperationId?: boolean;
+    /** Show the navigation sidebar. */
     showSidebar?: boolean;
+    /** When to expose Scalar's developer tools panel. */
     showDeveloperTools?: "always" | "localhost" | "never";
+    /** Expand the first tag's operations on load. */
     defaultOpenFirstTag?: boolean;
+    /** Expand every tag's operations on load. */
     defaultOpenAllTags?: boolean;
+    /** Expand all model (schema) sections on load. */
     expandAllModelSections?: boolean;
+    /** Expand all response sections on load. */
     expandAllResponses?: boolean;
+    /** Which spec download button(s) to offer, or `"none"` to hide them. */
     documentDownloadType?: "json" | "yaml" | "both" | "direct" | "none";
+    /** Label operations by their `summary` or by their `path`. */
     operationTitleSource?: "summary" | "path";
+    /** List required schema properties before optional ones. */
     orderRequiredPropertiesFirst?: boolean;
+    /** Sort schema properties alphabetically or keep spec order. */
     orderSchemaPropertiesBy?: "alpha" | "preserve";
+    /** Keyboard key that focuses search, e.g. `"k"` for Ctrl/Cmd+K. */
     searchHotKey?: string;
+    /** Base URL prepended to relative server URLs in the spec. */
     baseServerURL?: string;
+    /** Proxy URL used by "Test Request" calls to avoid CORS issues. */
     proxyUrl?: string;
+    /** Redirect URI used by the OAuth2 authorization-code flow. */
     oauth2RedirectUri?: string;
+    /** Persist entered credentials in browser storage across reloads. */
     persistAuth?: boolean;
+    /** Enable Scalar's anonymous usage telemetry. */
     telemetry?: boolean;
+    /** Sort tags alphabetically. */
     tagsSorter?: "alpha";
+    /** Sort operations alphabetically or by HTTP method. */
     operationsSorter?: "alpha" | "method";
+    /** Prefill security-scheme credentials (JSON-only Scalar `authentication` object). */
     authentication?: {
         [key: string]: ScalarJsonValue | undefined;
     };
+    /** Snippet target preselected in the client picker, e.g. `{ targetKey, clientKey }`. */
     defaultHttpClient?: {
         [key: string]: ScalarJsonValue | undefined;
     };
+    /** Extra HTML meta tags (title, description, Open Graph, ...) for the page. */
     metaData?: {
         [key: string]: ScalarJsonValue | undefined;
     };
+    /** Scalar MCP integration settings (JSON-only). */
     mcp?: {
         [key: string]: ScalarJsonValue | undefined;
     };
+    /** Use path-based routing for deep links, e.g. `{ basePath }`. */
     pathRouting?: {
         [key: string]: ScalarJsonValue | undefined;
     };
+    /** Override the spec's `servers` list shown in the UI. */
     servers?: ScalarJsonValue[];
+    /** Not serializable; the spec is always loaded from {@link DocsOptions.specUrl}. */
     content?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     fetch?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     generateHeadingSlug?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     generateModelSlug?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     generateOperationSlug?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     generateTagSlug?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     generateWebhookSlug?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onBeforeRequest?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onDocumentSelect?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onLoaded?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onRequestSent?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onServerChange?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onShowMore?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onSidebarClick?: never;
+    /** Function-valued callback; cannot cross the server-to-HTML boundary. */
     onSpecUpdate?: never;
+    /** Function-valued Scalar plugins; cannot cross the server-to-HTML boundary. */
     plugins?: never;
+    /** Function-valued option; cannot cross the server-to-HTML boundary. */
     redirect?: never;
+    /** Multi-document sources are not serializable here; serve one spec per page. */
     sources?: never;
+    /** Internal URL wiring owned by DaloyJS. Use {@link DocsOptions.specUrl} instead. */
     spec?: never;
+    /** Internal URL wiring owned by DaloyJS. Use {@link DocsOptions.specUrl} instead. */
     url?: never;
 }
 /**
@@ -425,6 +482,10 @@ export interface HtmlResponseOptions extends DocsContentSecurityPolicyOptions {
  * The output is a single HTML document with configurable external assets;
  * pair it with {@link htmlResponse} (or your own `Response`) and serve from
  * any route.
+ *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and Scalar configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value or `auth.loginUrl` is invalid.
  */
 export declare function scalarHtml(opts: ScalarHtmlOptions): string;
 /**
@@ -434,6 +495,10 @@ export declare function scalarHtml(opts: ScalarHtmlOptions): string;
  * Developer-entered credentials are persisted by default
  * (`persistAuthorization: true`) so routes with OpenAPI security requirements
  * can be exercised after using Swagger UI's Authorize dialog.
+ *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and Swagger UI configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value or `auth.loginUrl` is invalid.
  */
 export declare function swaggerUiHtml(opts: SwaggerUiHtmlOptions): string;
 /**
@@ -448,6 +513,9 @@ export declare function swaggerUiHtml(opts: SwaggerUiHtmlOptions): string;
  * you). The spec URL and configuration are embedded with `<`-escaped JSON so
  * an attacker-controlled value cannot break out of the inline `<script>`.
  *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and Redoc configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value or `auth.loginUrl` is invalid.
  * @since 0.39.0
  */
 export declare function redocHtml(opts: RedocHtmlOptions): string;
@@ -465,6 +533,9 @@ export declare function redocHtml(opts: RedocHtmlOptions): string;
  * and configuration are embedded with `<`-escaped JSON so an attacker-controlled
  * value cannot break out of the inline `<script>`.
  *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and AsyncAPI configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value is invalid.
  * @since 0.42.0
  */
 export declare function asyncapiHtml(opts: AsyncApiHtmlOptions): string;
@@ -474,11 +545,18 @@ export declare function asyncapiHtml(opts: AsyncApiHtmlOptions): string;
  *
  * Allows `'self'` plus the listed `assetOrigins` (default: jsDelivr) and
  * either `'unsafe-inline'` or the provided `scriptNonce` for scripts.
+ *
+ * @param opts Asset/connect origins, script nonce, inline-style, and blob-worker toggles.
+ * @returns The policy string, ready for a `content-security-policy` header.
  */
 export declare function docsContentSecurityPolicy(opts?: DocsContentSecurityPolicyOptions): string;
 /**
  * Wrap a docs HTML string in a `Response` with safe defaults:
  * `text/html` content type, `nosniff`, `no-referrer`, and a CSP from
  * {@link docsContentSecurityPolicy} (or a caller-supplied override).
+ *
+ * @param html The HTML document body to serve.
+ * @param opts CSP options, or a verbatim `contentSecurityPolicy` override.
+ * @returns A `Response` with the HTML body and hardened security headers.
  */
 export declare function htmlResponse(html: string, opts?: HtmlResponseOptions): Response;

package/dist/docs.js

@@ -45,6 +45,10 @@ function integrityAttr(integrity, crossOrigin) {
  * The output is a single HTML document with configurable external assets;
  * pair it with {@link htmlResponse} (or your own `Response`) and serve from
  * any route.
+ *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and Scalar configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value or `auth.loginUrl` is invalid.
  */
 export function scalarHtml(opts) {
     const title = escapeHtml(opts.title ?? "API Reference");
@@ -71,6 +75,10 @@ ${docsAuthLauncherHtml(opts.auth, opts.scriptNonce)}
  * Developer-entered credentials are persisted by default
  * (`persistAuthorization: true`) so routes with OpenAPI security requirements
  * can be exercised after using Swagger UI's Authorize dialog.
+ *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and Swagger UI configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value or `auth.loginUrl` is invalid.
  */
 export function swaggerUiHtml(opts) {
     const title = escapeHtml(opts.title ?? "API Docs");
@@ -110,6 +118,9 @@ ${docsAuthLauncherHtml(opts.auth, opts.scriptNonce)}
  * you). The spec URL and configuration are embedded with `<`-escaped JSON so
  * an attacker-controlled value cannot break out of the inline `<script>`.
  *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and Redoc configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value or `auth.loginUrl` is invalid.
  * @since 0.39.0
  */
 export function redocHtml(opts) {
@@ -145,6 +156,9 @@ ${docsAuthLauncherHtml(opts.auth, opts.scriptNonce)}
  * and configuration are embedded with `<`-escaped JSON so an attacker-controlled
  * value cannot break out of the inline `<script>`.
  *
+ * @param opts Spec URL, page title, asset overrides, CSP nonce, and AsyncAPI configuration.
+ * @returns The complete HTML document as a string.
+ * @throws {TypeError} when an SRI integrity value is invalid.
  * @since 0.42.0
  */
 export function asyncapiHtml(opts) {
@@ -176,6 +190,9 @@ export function asyncapiHtml(opts) {
  *
  * Allows `'self'` plus the listed `assetOrigins` (default: jsDelivr) and
  * either `'unsafe-inline'` or the provided `scriptNonce` for scripts.
+ *
+ * @param opts Asset/connect origins, script nonce, inline-style, and blob-worker toggles.
+ * @returns The policy string, ready for a `content-security-policy` header.
  */
 export function docsContentSecurityPolicy(opts = {}) {
     const assetOrigins = opts.assetOrigins ?? [JSDELIVR_ORIGIN];
@@ -206,6 +223,10 @@ export function docsContentSecurityPolicy(opts = {}) {
  * Wrap a docs HTML string in a `Response` with safe defaults:
  * `text/html` content type, `nosniff`, `no-referrer`, and a CSP from
  * {@link docsContentSecurityPolicy} (or a caller-supplied override).
+ *
+ * @param html The HTML document body to serve.
+ * @param opts CSP options, or a verbatim `contentSecurityPolicy` override.
+ * @returns A `Response` with the HTML body and hardened security headers.
  */
 export function htmlResponse(html, opts = {}) {
     return new Response(html, {

package/dist/errors.d.ts

@@ -81,6 +81,7 @@ export declare const SAFE_CUSTOM_ERROR_RESPONSE_HEADERS: ReadonlySet<string>;
  * @since 0.32.0
  */
 export declare class MessageLeakError extends Error {
+    /** The refused headers, each with its name and the reason it was disallowed. */
     readonly offendingHeaders: ReadonlyArray<{
         name: string;
         reason: string;
@@ -93,6 +94,10 @@ export declare 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 declare function checkCustomErrorResponseHeaders(headers: Headers): Array<{
     name: string;
@@ -108,7 +113,9 @@ export declare function checkCustomErrorResponseHeaders(headers: Headers): Array
  * @since 0.32.0
  */
 export interface HttpErrorOptions {
+    /** HTTP status code for the rendered problem+json response. */
     status: number;
+    /** RFC 9457 problem document fields; `title` is required. */
     problem: Partial<ProblemDetails> & {
         title: string;
     };
@@ -136,6 +143,12 @@ export interface HttpErrorOptions {
  * 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 declare function httpError(opts: HttpErrorOptions): HttpError;
@@ -178,8 +191,11 @@ export declare function httpError(opts: HttpErrorOptions): HttpError;
  * @since 0.1.0
  */
 export declare class HttpError extends Error {
+    /** HTTP status code of the rendered response. */
     readonly status: number;
+    /** RFC 9457 problem document; `type` defaults to `https://httpstatuses.io/<status>`. */
     readonly problem: ProblemDetails;
+    /** Extra response headers (e.g. `Retry-After`, `Allow`) merged onto the response. */
     readonly headers?: Record<string, string>;
     constructor(status: number, problem: Partial<ProblemDetails> & {
         title: string;

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) {