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

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:a88e3a69-b278-5771-a67e-40fb774e004e",
+  "serialNumber": "urn:uuid:b5480fcc-c870-525f-bf19-08a30ac9e3d6",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-01T22:47:12.881Z",
+    "timestamp": "2026-07-02T15:07:00.378Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.0.0-beta.6"
+        "version": "1.0.0-beta.7"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-beta.6",
+      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-beta.7",
       "name": "@daloyjs/core",
-      "version": "1.0.0-beta.6",
+      "version": "1.0.0-beta.7",
       "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
-      "purl": "pkg:npm/@daloyjs/core@1.0.0-beta.6",
+      "purl": "pkg:npm/@daloyjs/core@1.0.0-beta.7",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-1.0.0-beta.6",
+        "tagId": "swidtag--daloyjs-core-1.0.0-beta.7",
         "name": "@daloyjs/core",
-        "version": "1.0.0-beta.6",
+        "version": "1.0.0-beta.7",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@1.0.0-beta.6",
+      "ref": "pkg:npm/@daloyjs/core@1.0.0-beta.7",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@daloyjs/core-1.0.0-beta.6",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-beta.6-a88e3a69-b278-5771-a67e-40fb774e004e",
+  "name": "@daloyjs/core-1.0.0-beta.7",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-beta.7-b5480fcc-c870-525f-bf19-08a30ac9e3d6",
   "creationInfo": {
-    "created": "2026-07-01T22:47:12.881Z",
+    "created": "2026-07-02T15:07:00.378Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "1.0.0-beta.6",
+      "versionInfo": "1.0.0-beta.7",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-beta.6"
+          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-beta.7"
         }
       ]
     }

package/dist/scheduler.d.ts

@@ -57,9 +57,13 @@ export declare class CronParseError extends Error {
  * @since 0.37.0
  */
 export interface SchedulerLogger {
+    /** Log at debug level (task definitions as they are registered). */
     debug(obj: object | string, msg?: string): void;
+    /** Log at info level (scheduler started / stopped lifecycle events). */
     info(obj: object | string, msg?: string): void;
+    /** Log at warn level (overrun-skipped runs, stop grace-period timeouts). */
     warn(obj: object | string, msg?: string): void;
+    /** Log at error level (a task handler threw or rejected). */
     error(obj: object | string, msg?: string): void;
 }
 /**

package/dist/schema.d.ts

@@ -7,35 +7,60 @@
  * `~standard`. No vendor lock-in.
  */
 export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema contract object every compatible validator exposes. */
     readonly "~standard": StandardSchemaV1.Props<Input, Output>;
 }
 export declare namespace StandardSchemaV1 {
+    /**
+     * The `~standard` contract exposed by a Standard Schema validator: spec
+     * version, vendor tag, and the vendor-neutral `validate` entry point.
+     */
     interface Props<Input = unknown, Output = Input> {
+        /** Spec version implemented by the validator. Always `1`. */
         readonly version: 1;
+        /** Name of the validator library (e.g. `"zod"`, `"valibot"`). */
         readonly vendor: string;
+        /** Validates a value; may be sync or async. Returns `{ value }` on success or `{ issues }` on failure. */
         readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Type-only carrier for {@link InferInput}/{@link InferOutput}; never populated at runtime. */
         readonly types?: Types<Input, Output>;
     }
+    /** Outcome of {@link Props.validate}: a {@link SuccessResult} or a {@link FailureResult}. */
     type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** Successful validation: the parsed/coerced output value and no issues. */
     interface SuccessResult<Output> {
+        /** The validated (and possibly transformed) output value. */
         readonly value: Output;
+        /** Always `undefined` on success; lets `result.issues` discriminate the union. */
         readonly issues?: undefined;
     }
+    /** Failed validation: one or more {@link Issue}s and no output value. */
     interface FailureResult {
+        /** The validation problems found; always non-empty on failure. */
         readonly issues: ReadonlyArray<Issue>;
     }
+    /** One validation problem reported by a validator. */
     interface Issue {
+        /** Human-readable description of the problem. */
         readonly message: string;
+        /** Location of the problem as a key path from the root; omitted for root-level issues. */
         readonly path?: ReadonlyArray<PropertyKey | PathSegment>;
     }
+    /** Object-wrapped path entry used by validators that attach extra metadata to path keys. */
     interface PathSegment {
+        /** The property key this segment addresses. */
         readonly key: PropertyKey;
     }
+    /** Type-level input/output carrier referenced by {@link Props.types}; runtime value is never read. */
     interface Types<Input, Output> {
+        /** The type accepted by the validator before parsing/coercion. */
         readonly input: Input;
+        /** The type produced by the validator after parsing/coercion. */
         readonly output: Output;
     }
+    /** Infers the input (pre-validation) type of a Standard Schema validator. */
     type InferInput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["input"];
+    /** Infers the output (post-validation) type of a Standard Schema validator. */
     type InferOutput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["output"];
 }
 /**

package/dist/security-schemes.d.ts

@@ -14,66 +14,92 @@ export type ApiKeyLocation = "header" | "query" | "cookie";
 export interface HttpBearerSchemeOptions {
     /** Hint about the bearer token format (e.g. "JWT"). */
     bearerFormat?: string;
+    /** Human-readable description shown in the generated docs (CommonMark). */
     description?: string;
     /** Require payload/body authentication for routes using this scheme. */
     requirePayloadAuth?: boolean;
 }
 /** Options for {@link httpBasicScheme}. */
 export interface HttpBasicSchemeOptions {
+    /** Human-readable description shown in the generated docs (CommonMark). */
     description?: string;
     /** Require payload/body authentication for routes using this scheme. */
     requirePayloadAuth?: boolean;
 }
 /** Options for {@link apiKeyScheme}. */
 export interface ApiKeySchemeOptions {
+    /** Where the key is presented: `"header"`, `"query"`, or `"cookie"`. */
     in: ApiKeyLocation;
+    /** Name of the header, query parameter, or cookie that carries the key. */
     name: string;
+    /** Human-readable description shown in the generated docs (CommonMark). */
     description?: string;
     /** Require payload/body authentication for routes using this scheme. */
     requirePayloadAuth?: boolean;
 }
 /** OAuth2 Implicit flow object (deprecated in OAuth 2.1 but still part of OpenAPI). */
 export interface OAuth2ImplicitFlow {
+    /** Authorization endpoint URL (OpenAPI `authorizationUrl`; must be TLS). */
     authorizationUrl: string;
+    /** Optional URL for obtaining refresh tokens. */
     refreshUrl?: string;
+    /** Map of scope name to short description. May be empty. */
     scopes: Record<string, string>;
 }
 /** OAuth2 Resource Owner Password Credentials flow object. */
 export interface OAuth2PasswordFlow {
+    /** Token endpoint URL (OpenAPI `tokenUrl`; must be TLS). */
     tokenUrl: string;
+    /** Optional URL for obtaining refresh tokens. */
     refreshUrl?: string;
+    /** Map of scope name to short description. May be empty. */
     scopes: Record<string, string>;
 }
 /** OAuth2 Client Credentials flow object. */
 export interface OAuth2ClientCredentialsFlow {
+    /** Token endpoint URL (OpenAPI `tokenUrl`; must be TLS). */
     tokenUrl: string;
+    /** Optional URL for obtaining refresh tokens. */
     refreshUrl?: string;
+    /** Map of scope name to short description. May be empty. */
     scopes: Record<string, string>;
 }
 /** OAuth2 Authorization Code flow object (the recommended interactive flow). */
 export interface OAuth2AuthorizationCodeFlow {
+    /** Authorization endpoint URL (OpenAPI `authorizationUrl`; must be TLS). */
     authorizationUrl: string;
+    /** Token endpoint URL (OpenAPI `tokenUrl`; must be TLS). */
     tokenUrl: string;
+    /** Optional URL for obtaining refresh tokens. */
     refreshUrl?: string;
+    /** Map of scope name to short description. May be empty. */
     scopes: Record<string, string>;
 }
 /** Container for all OAuth2 flows supported by a single scheme. At least one entry is required. */
 export interface OAuth2Flows {
+    /** Implicit flow (deprecated in OAuth 2.1; avoid for new APIs). */
     implicit?: OAuth2ImplicitFlow;
+    /** Resource Owner Password Credentials flow. */
     password?: OAuth2PasswordFlow;
+    /** Client Credentials flow (machine-to-machine). */
     clientCredentials?: OAuth2ClientCredentialsFlow;
+    /** Authorization Code flow (the recommended interactive flow). */
     authorizationCode?: OAuth2AuthorizationCodeFlow;
 }
 /** Options for {@link oauth2Scheme}. */
 export interface OAuth2SchemeOptions {
+    /** Supported OAuth2 flows. At least one entry is required. */
     flows: OAuth2Flows;
+    /** Human-readable description shown in the generated docs (CommonMark). */
     description?: string;
     /** Require payload/body authentication for routes using this scheme. */
     requirePayloadAuth?: boolean;
 }
 /** Options for {@link openIdConnectScheme}. */
 export interface OpenIdConnectSchemeOptions {
+    /** OpenID Connect Discovery URL (typically ends in `/.well-known/openid-configuration`). */
     openIdConnectUrl: string;
+    /** Human-readable description shown in the generated docs (CommonMark). */
     description?: string;
     /** Require payload/body authentication for routes using this scheme. */
     requirePayloadAuth?: boolean;
@@ -82,38 +108,56 @@ export interface OpenIdConnectSchemeOptions {
 export declare const REQUIRE_PAYLOAD_AUTH_EXTENSION: "x-daloy-require-payload-auth";
 /** Mixin shape for schemes that opt into payload authentication via {@link REQUIRE_PAYLOAD_AUTH_EXTENSION}. */
 export interface RequirePayloadAuthExtension {
+    /** Set to `true` when routes using this scheme must also pass payload (signed body) authentication. */
     readonly [REQUIRE_PAYLOAD_AUTH_EXTENSION]?: true;
 }
 /** OpenAPI HTTP Bearer security scheme returned by {@link httpBearerScheme}. */
 export interface HttpBearerScheme extends RequirePayloadAuthExtension {
+    /** OpenAPI security scheme `type` discriminant. Always `"http"`. */
     type: "http";
+    /** HTTP auth scheme name per RFC 9110. Always `"bearer"`. */
     scheme: "bearer";
+    /** Hint about the bearer token format (e.g. "JWT"). */
     bearerFormat?: string;
+    /** Human-readable description shown in the generated docs (CommonMark). */
     description?: string;
 }
 /** OpenAPI HTTP Basic security scheme returned by {@link httpBasicScheme}. */
 export interface HttpBasicScheme extends RequirePayloadAuthExtension {
+    /** OpenAPI security scheme `type` discriminant. Always `"http"`. */
     type: "http";
+    /** HTTP auth scheme name per RFC 9110. Always `"basic"`. */
     scheme: "basic";
+    /** Human-readable description shown in the generated docs (CommonMark). */
     description?: string;
 }
 /** OpenAPI API-key security scheme returned by {@link apiKeyScheme}. */
 export interface ApiKeyScheme extends RequirePayloadAuthExtension {
+    /** OpenAPI security scheme `type` discriminant. Always `"apiKey"`. */
     type: "apiKey";
+    /** Where the key is presented: `"header"`, `"query"`, or `"cookie"`. */
     in: ApiKeyLocation;
+    /** Name of the header, query parameter, or cookie that carries the key. */
     name: string;
+    /** Human-readable description shown in the generated docs (CommonMark). */
     description?: string;
 }
 /** OpenAPI OAuth2 security scheme returned by {@link oauth2Scheme}. */
 export interface OAuth2Scheme extends RequirePayloadAuthExtension {
+    /** OpenAPI security scheme `type` discriminant. Always `"oauth2"`. */
     type: "oauth2";
+    /** Supported OAuth2 flows (at least one entry). */
     flows: OAuth2Flows;
+    /** Human-readable description shown in the generated docs (CommonMark). */
     description?: string;
 }
 /** OpenAPI OpenID Connect security scheme returned by {@link openIdConnectScheme}. */
 export interface OpenIdConnectScheme extends RequirePayloadAuthExtension {
+    /** OpenAPI security scheme `type` discriminant. Always `"openIdConnect"`. */
     type: "openIdConnect";
+    /** OpenID Connect Discovery URL (typically ends in `/.well-known/openid-configuration`). */
     openIdConnectUrl: string;
+    /** Human-readable description shown in the generated docs (CommonMark). */
     description?: string;
 }
 /** Union of every concrete security scheme this module can build. */
@@ -122,12 +166,18 @@ export type SecurityScheme = HttpBearerScheme | HttpBasicScheme | ApiKeyScheme |
  * Returns `true` when `scheme` opts into payload (signed body) authentication
  * via either the legacy `requirePayloadAuth` flag or the canonical
  * {@link REQUIRE_PAYLOAD_AUTH_EXTENSION} OpenAPI extension.
+ *
+ * @param scheme - Candidate security scheme object (non-objects are tolerated).
+ * @returns `true` when payload auth is required; `false` otherwise.
  */
 export declare function securitySchemeRequiresPayloadAuth(scheme: unknown): boolean;
 /**
  * Normalize a builder output into a spec-compliant OpenAPI security scheme by
  * stripping the convenience `requirePayloadAuth` flag and emitting the
  * canonical {@link REQUIRE_PAYLOAD_AUTH_EXTENSION} extension instead.
+ *
+ * @param scheme - Candidate security scheme object (non-objects pass through untouched).
+ * @returns A copy without `requirePayloadAuth` (extension set when it was `true`), or the input itself when no normalization is needed.
  */
 export declare function toOpenAPISecurityScheme(scheme: unknown): unknown;
 /**

package/dist/security-schemes.js

@@ -20,6 +20,9 @@ function markRequirePayloadAuth(scheme, options) {
  * Returns `true` when `scheme` opts into payload (signed body) authentication
  * via either the legacy `requirePayloadAuth` flag or the canonical
  * {@link REQUIRE_PAYLOAD_AUTH_EXTENSION} OpenAPI extension.
+ *
+ * @param scheme - Candidate security scheme object (non-objects are tolerated).
+ * @returns `true` when payload auth is required; `false` otherwise.
  */
 export function securitySchemeRequiresPayloadAuth(scheme) {
     if (!scheme || typeof scheme !== "object")
@@ -32,6 +35,9 @@ export function securitySchemeRequiresPayloadAuth(scheme) {
  * Normalize a builder output into a spec-compliant OpenAPI security scheme by
  * stripping the convenience `requirePayloadAuth` flag and emitting the
  * canonical {@link REQUIRE_PAYLOAD_AUTH_EXTENSION} extension instead.
+ *
+ * @param scheme - Candidate security scheme object (non-objects pass through untouched).
+ * @returns A copy without `requirePayloadAuth` (extension set when it was `true`), or the input itself when no normalization is needed.
  */
 export function toOpenAPISecurityScheme(scheme) {
     if (!scheme || typeof scheme !== "object")

package/dist/security.d.ts

@@ -105,6 +105,21 @@ export declare function sanitizeHeaderValue(value: string): string;
  * @since 0.1.0
  */
 export declare function timingSafeEqual(a: string, b: string): boolean;
+/**
+ * Generate a cryptographically strong, URL-safe identifier (~22 chars).
+ *
+ * Uses Web Crypto's `crypto.randomUUID()` when available, falling back to
+ * 16 random bytes via `crypto.getRandomValues()`. The last-resort fallback
+ * (timestamp + `Math.random()`) only triggers in environments without
+ * WebCrypto, which is none of Node 20+/Bun/Deno/Cloudflare Workers/Vercel
+ * Edge.
+ *
+ * Suitable for request ids, session ids, and short-lived correlation tokens.
+ * Do not use for long-lived secrets unless you also sign or wrap them.
+ *
+ * @returns A random URL-safe id string.
+ * @since 0.1.0
+ */
 export declare function randomId(): string;
 /**
  * Header names that MUST appear at most once on a request per RFC 7230.
@@ -126,6 +141,7 @@ export declare const SMUGGLING_SINGLETON_HEADERS: readonly string[];
  * Throws {@link BadRequestError} so the framework returns a structured
  * `400 problem+json` instead of forwarding a smuggling-class request.
  *
+ * @param headers - Normalized request headers to inspect.
  * @since 0.15.0
  */
 export declare function assertNoDuplicateSingletonHeaders(headers: Headers): void;
@@ -163,6 +179,7 @@ export declare const RESERVED_INBOUND_HEADER_PREFIXES: readonly string[];
  * `400 problem+json` instead of routing a request that may be probing
  * for an internal-dispatch bypass.
  *
+ * @param headers - Normalized request headers to inspect (names arrive lowercased).
  * @since 0.36.0
  */
 export declare function assertNoReservedInternalHeaders(headers: Headers): void;
@@ -229,6 +246,8 @@ export declare const WEAK_SECRET_STRINGS: readonly string[];
  * The thrown `Error` includes the `scope` argument (e.g. `"session"`) so
  * the developer sees which subsystem rejected the secret.
  *
+ * @param secret - Candidate secret value to vet.
+ * @param scope - Subsystem name used to prefix the thrown error message.
  * @since 0.17.0
  */
 export declare function assertStrongSecret(secret: unknown, scope: string): void;
@@ -283,6 +302,11 @@ export declare const WEBHOOK_DEFAULT_TOLERANCE_SECONDS = 300;
  * });
  * ```
  *
+ * @param opts - Payload, expected signature, shared secret, and optional
+ *   `algorithm` (defaults to `"sha256"`), `timestamp`, `toleranceSeconds`,
+ *   and `now` clock for replay-window checks.
+ * @returns `true` only when the signature matches the HMAC of the (optionally
+ *   timestamp-prefixed) payload and the timestamp is within tolerance.
  * @since 0.15.0
  */
 export declare function verifyWebhookSignature(opts: {
@@ -325,6 +349,11 @@ export declare function verifyWebhookSignature(opts: {
  * companion of {@link verifyWebhookSignature}; useful for tests, for
  * outbound webhook senders, and for diffing implementations.
  *
+ * @param opts - Payload, shared secret, optional `algorithm` (defaults to
+ *   `"sha256"`), and optional `timestamp` to bind the signature to.
+ * @returns The hex-encoded HMAC digest.
+ * @throws TypeError on an unsupported algorithm or malformed timestamp;
+ *   Error when WebCrypto is unavailable.
  * @since 0.15.0
  */
 export declare function signWebhookPayload(opts: {
@@ -415,6 +444,8 @@ export declare function assertSafeRelativePath(input: string): string;
  * Returns `true` on the first hit. Use before passing untrusted data
  * into a query object that may be interpreted as an operator expression.
  *
+ * @param value - Parsed, untrusted JSON value to scan recursively.
+ * @returns `true` when any nested key starts with `$`; `false` otherwise.
  * @since 0.35.0
  */
 export declare function hasMongoOperatorKeys(value: unknown): boolean;
@@ -424,6 +455,8 @@ export declare function hasMongoOperatorKeys(value: unknown): boolean;
  * threading it into a NoSQL driver — closes the
  * `{"password": {"$ne": null}}` authentication-bypass class of bug.
  *
+ * @param value - Parsed, untrusted JSON value to scan recursively.
+ * @throws BadRequestError when any nested key starts with `$`.
  * @since 0.35.0
  */
 export declare function assertNoMongoOperators(value: unknown): void;

package/dist/security.js

@@ -197,6 +197,16 @@ export function timingSafeEqual(a, b) {
     }
     return mismatch === 0;
 }
+// Cache the Web Crypto entry points at module load so randomId() doesn't pay
+// for a `globalThis.crypto` + optional-chain property lookup per request.
+// Falls back to the runtime lookup path if Web Crypto is patched/replaced
+// after module load (test harnesses, custom runtimes) — the cache is only
+// trusted when `globalThis.crypto` is still the same reference, otherwise
+// the stubbed object would be silently bypassed.
+const _webCrypto = globalThis.crypto;
+const _randomUUID = _webCrypto && typeof _webCrypto.randomUUID === "function"
+    ? _webCrypto.randomUUID.bind(_webCrypto)
+    : undefined;
 /**
  * Generate a cryptographically strong, URL-safe identifier (~22 chars).
  *
@@ -212,16 +222,6 @@ export function timingSafeEqual(a, b) {
  * @returns A random URL-safe id string.
  * @since 0.1.0
  */
-// Cache the Web Crypto entry points at module load so randomId() doesn't pay
-// for a `globalThis.crypto` + optional-chain property lookup per request.
-// Falls back to the runtime lookup path if Web Crypto is patched/replaced
-// after module load (test harnesses, custom runtimes) — the cache is only
-// trusted when `globalThis.crypto` is still the same reference, otherwise
-// the stubbed object would be silently bypassed.
-const _webCrypto = globalThis.crypto;
-const _randomUUID = _webCrypto && typeof _webCrypto.randomUUID === "function"
-    ? _webCrypto.randomUUID.bind(_webCrypto)
-    : undefined;
 export function randomId() {
     const c = globalThis.crypto;
     if (c === _webCrypto && _randomUUID !== undefined)
@@ -260,6 +260,7 @@ export const SMUGGLING_SINGLETON_HEADERS = Object.freeze([
  * Throws {@link BadRequestError} so the framework returns a structured
  * `400 problem+json` instead of forwarding a smuggling-class request.
  *
+ * @param headers - Normalized request headers to inspect.
  * @since 0.15.0
  */
 export function assertNoDuplicateSingletonHeaders(headers) {
@@ -307,6 +308,7 @@ export const RESERVED_INBOUND_HEADER_PREFIXES = Object.freeze([
  * `400 problem+json` instead of routing a request that may be probing
  * for an internal-dispatch bypass.
  *
+ * @param headers - Normalized request headers to inspect (names arrive lowercased).
  * @since 0.36.0
  */
 export function assertNoReservedInternalHeaders(headers) {
@@ -426,6 +428,8 @@ const WEAK_SECRET_SET = new Set(WEAK_SECRET_STRINGS.map((s) => s.toLowerCase()))
  * The thrown `Error` includes the `scope` argument (e.g. `"session"`) so
  * the developer sees which subsystem rejected the secret.
  *
+ * @param secret - Candidate secret value to vet.
+ * @param scope - Subsystem name used to prefix the thrown error message.
  * @since 0.17.0
  */
 export function assertStrongSecret(secret, scope) {
@@ -603,6 +607,11 @@ function buildSignedPayloadBytes(payload, timestamp) {
  * });
  * ```
  *
+ * @param opts - Payload, expected signature, shared secret, and optional
+ *   `algorithm` (defaults to `"sha256"`), `timestamp`, `toleranceSeconds`,
+ *   and `now` clock for replay-window checks.
+ * @returns `true` only when the signature matches the HMAC of the (optionally
+ *   timestamp-prefixed) payload and the timestamp is within tolerance.
  * @since 0.15.0
  */
 export async function verifyWebhookSignature(opts) {
@@ -648,6 +657,11 @@ export async function verifyWebhookSignature(opts) {
  * companion of {@link verifyWebhookSignature}; useful for tests, for
  * outbound webhook senders, and for diffing implementations.
  *
+ * @param opts - Payload, shared secret, optional `algorithm` (defaults to
+ *   `"sha256"`), and optional `timestamp` to bind the signature to.
+ * @returns The hex-encoded HMAC digest.
+ * @throws TypeError on an unsupported algorithm or malformed timestamp;
+ *   Error when WebCrypto is unavailable.
  * @since 0.15.0
  */
 export async function signWebhookPayload(opts) {
@@ -840,6 +854,8 @@ function walkForMongoOperators(value) {
  * Returns `true` on the first hit. Use before passing untrusted data
  * into a query object that may be interpreted as an operator expression.
  *
+ * @param value - Parsed, untrusted JSON value to scan recursively.
+ * @returns `true` when any nested key starts with `$`; `false` otherwise.
  * @since 0.35.0
  */
 export function hasMongoOperatorKeys(value) {
@@ -851,6 +867,8 @@ export function hasMongoOperatorKeys(value) {
  * threading it into a NoSQL driver — closes the
  * `{"password": {"$ne": null}}` authentication-bypass class of bug.
  *
+ * @param value - Parsed, untrusted JSON value to scan recursively.
+ * @throws BadRequestError when any nested key starts with `$`.
  * @since 0.35.0
  */
 export function assertNoMongoOperators(value) {

package/dist/session.d.ts

@@ -49,8 +49,11 @@ export interface SessionRecord {
  * lazily delete expired records.
  */
 export interface SessionStore {
+    /** Load the record for a session id, or `null` when missing/expired. */
     get(sid: string): SessionRecord | null | Promise<SessionRecord | null>;
+    /** Persist (create or overwrite) the record for a session id. */
     set(sid: string, record: SessionRecord): void | Promise<void>;
+    /** Delete the record for a session id; a no-op when it does not exist. */
     destroy(sid: string): void | Promise<void>;
     /** Optional fast-path for rolling sessions; falls back to `set()` if omitted. */
     touch?(sid: string, expiresAt: number): void | Promise<void>;
@@ -128,9 +131,13 @@ export type SessionContext = {
  */
 export declare class MemorySessionStore implements SessionStore {
     private readonly map;
+    /** Load a record; expired records are deleted and reported as `null`. */
     get(sid: string): SessionRecord | null;
+    /** Store (or overwrite) a record for a session id. */
     set(sid: string, record: SessionRecord): void;
+    /** Remove the record for a session id, if present. */
     destroy(sid: string): void;
+    /** Extend an existing record's expiry (ms since epoch) without rewriting data. */
     touch(sid: string, expiresAt: number): void;
     /** Test helper. Remove every record. */
     clear(): void;
@@ -155,6 +162,14 @@ export declare class MemorySessionStore implements SessionStore {
  * const app = new App();
  * app.use(session({ secret: process.env.SESSION_SECRET! }));
  * ```
+ *
+ * @param opts Secrets, cookie attributes, store, TTL, and rolling behavior;
+ *   see {@link SessionOptions}. Cookies default to `__Host-` prefixed,
+ *   `HttpOnly`, `Secure`, `SameSite=Lax`.
+ * @returns A {@link Hooks} object that loads/verifies the session before the
+ *   handler and persists mutations plus the `Set-Cookie` header afterwards.
+ * @throws Error at setup time on missing/short secrets, invalid cookie
+ *   attribute combinations, or a non-positive `ttlSeconds`.
  */
 export declare function session(opts: SessionOptions): Hooks;
 /** Options for {@link rotateSession}. */
@@ -177,18 +192,32 @@ export interface RotateSessionOptions {
  * session key-rotation arrays: old cookies verify with any configured secret
  * and rotated cookies are re-signed with the first/current secret.
  *
+ * @param opts Which session keys (or computed value) to watch, and whether
+ *   payload data survives rotation (`keepData`, default `true`); see
+ *   {@link RotateSessionOptions}.
+ * @returns A {@link Hooks} object that snapshots the watched value before the
+ *   handler and regenerates the session id when it changed afterwards
+ *   (session-fixation defense).
  * @since 0.23.0
  */
 export declare function rotateSession(opts?: RotateSessionOptions): Hooks;
 /**
- * Sign an arbitrary string with HMAC-SHA256. Returns `${value}.${sig}` where
- * `sig` is URL-safe base64. Useful for building custom signed cookies or
- * tokens that do not need a session store.
+ * Sign an arbitrary string with HMAC-SHA256. Useful for building custom
+ * signed cookies or tokens that do not need a session store.
+ *
+ * @param value String to sign; must not contain `.` (the separator).
+ * @param secret HMAC key, at least 16 characters.
+ * @returns `${value}.${sig}` where `sig` is URL-safe base64.
+ * @throws Error when `value` contains `.` or the secret is too short.
  */
 export declare function signValue(value: string, secret: string): Promise<string>;
 /**
- * Verify a `signValue()`-produced string. Returns the original value when the
- * signature checks out, otherwise `null`. Constant-time on the signature.
+ * Verify a `signValue()`-produced string. Constant-time on the signature
+ * comparison.
+ *
+ * @param signed The `${value}.${sig}` string to verify.
+ * @param secret HMAC key(s); an array lets rotated old secrets still verify.
+ * @returns The original value when any secret's signature matches, else `null`.
  */
 export declare function verifySignedValue(signed: string, secret: string | string[]): Promise<string | null>;
 /** Type-augmentation helper: `interface AppState extends SessionState {}`. */