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

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 {}`. */

package/dist/session.js

@@ -161,6 +161,7 @@ function makeSessionContext(id, data, internal, regenerate) {
  */
 export class MemorySessionStore {
     map = new Map();
+    /** Load a record; expired records are deleted and reported as `null`. */
     get(sid) {
         const rec = this.map.get(sid);
         if (!rec)
@@ -171,12 +172,15 @@ export class MemorySessionStore {
         }
         return rec;
     }
+    /** Store (or overwrite) a record for a session id. */
     set(sid, record) {
         this.map.set(sid, record);
     }
+    /** Remove the record for a session id, if present. */
     destroy(sid) {
         this.map.delete(sid);
     }
+    /** Extend an existing record's expiry (ms since epoch) without rewriting data. */
     touch(sid, expiresAt) {
         const rec = this.map.get(sid);
         if (rec)
@@ -210,6 +214,14 @@ export class MemorySessionStore {
  * 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 function session(opts) {
     const cookieName = opts.cookieName ?? DEFAULT_COOKIE_NAME;
@@ -432,6 +444,12 @@ function stableSnapshot(value) {
  * 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 function rotateSession(opts = {}) {
@@ -462,9 +480,13 @@ export function rotateSession(opts = {}) {
 }
 // ---------- Low-level signing helpers (re-exported for advanced use) ----------
 /**
- * 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 async function signValue(value, secret) {
     if (value.includes(".")) {
@@ -475,8 +497,12 @@ export async function signValue(value, secret) {
     return `${value}.${sig}`;
 }
 /**
- * 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 async function verifySignedValue(signed, secret) {
     const dot = signed.lastIndexOf(".");

package/dist/streaming.d.ts

@@ -36,8 +36,11 @@
  * and reconnection control without sending an event payload.
  */
 export interface SSEMessage {
+    /** Event payload. Strings are sent verbatim; other values are `JSON.stringify`-ed. */
     data?: unknown;
+    /** Event name (`event:` field). Newlines are replaced with spaces to prevent frame injection. */
     event?: string;
+    /** Last-event ID (`id:` field). Newlines are replaced with spaces to prevent frame injection. */
     id?: string;
     /** Reconnection delay in milliseconds. */
     retry?: number;
@@ -76,11 +79,19 @@ type IterableSource<T> = AsyncIterable<T> | Iterable<T> | (() => AsyncIterable<T
  * Build a backpressure-safe `ReadableStream` from an async iterable of SSE
  * messages. The iterator is only advanced when the consumer pulls the next
  * chunk, so a slow client cannot cause unbounded buffering.
+ *
+ * @param source Async/sync iterable (or factory) yielding {@link SSEMessage}s or plain strings.
+ * @param opts Abort signal and optional keep-alive interval; see {@link SSEStreamOptions}.
+ * @returns A `ReadableStream<Uint8Array>` of encoded `text/event-stream` frames.
  */
 export declare function sseStream(source: IterableSource<SSEMessage | string>, opts?: SSEStreamOptions): ReadableStream<Uint8Array>;
 /**
  * Wrap `sseStream` in a `Response` with the proper SSE headers
  * (`text/event-stream`, no caching, keep-alive). Caller-supplied headers win.
+ *
+ * @param source Async/sync iterable (or factory) yielding {@link SSEMessage}s or plain strings.
+ * @param opts Status, headers, abort signal, and keep-alive; see {@link SSEResponseOptions}.
+ * @returns A streaming `Response` (default status `200`) with SSE headers applied.
  */
 export declare function sseResponse(source: IterableSource<SSEMessage | string>, opts?: SSEResponseOptions): Response;
 /**
@@ -88,11 +99,19 @@ export declare function sseResponse(source: IterableSource<SSEMessage | string>,
  * JSON) records from an async iterable. Each yielded value is encoded with
  * `JSON.stringify` and terminated with `\n`. Values that stringify to
  * `undefined` throw because they cannot be represented as valid NDJSON.
+ *
+ * @param source Async/sync iterable (or factory) yielding JSON-serializable values.
+ * @param opts Optional abort signal; see {@link StreamOptions}.
+ * @returns A `ReadableStream<Uint8Array>` of newline-terminated JSON records.
  */
 export declare function ndjsonStream<T>(source: IterableSource<T>, opts?: StreamOptions): ReadableStream<Uint8Array>;
 /**
  * Wrap `ndjsonStream` in a `Response` with `application/x-ndjson` and
  * cache-busting headers. Caller-supplied headers win.
+ *
+ * @param source Async/sync iterable (or factory) yielding JSON-serializable values.
+ * @param opts Status, headers, and abort signal; see {@link NDJSONResponseOptions}.
+ * @returns A streaming `Response` (default status `200`) with NDJSON headers applied.
  */
 export declare function ndjsonResponse<T>(source: IterableSource<T>, opts?: NDJSONResponseOptions): Response;
 export {};

package/dist/streaming.js

@@ -87,6 +87,10 @@ function encodeNDJSON(value) {
  * Build a backpressure-safe `ReadableStream` from an async iterable of SSE
  * messages. The iterator is only advanced when the consumer pulls the next
  * chunk, so a slow client cannot cause unbounded buffering.
+ *
+ * @param source Async/sync iterable (or factory) yielding {@link SSEMessage}s or plain strings.
+ * @param opts Abort signal and optional keep-alive interval; see {@link SSEStreamOptions}.
+ * @returns A `ReadableStream<Uint8Array>` of encoded `text/event-stream` frames.
  */
 export function sseStream(source, opts = {}) {
     const iterator = getAsyncIterator(source);
@@ -165,6 +169,10 @@ export function sseStream(source, opts = {}) {
 /**
  * Wrap `sseStream` in a `Response` with the proper SSE headers
  * (`text/event-stream`, no caching, keep-alive). Caller-supplied headers win.
+ *
+ * @param source Async/sync iterable (or factory) yielding {@link SSEMessage}s or plain strings.
+ * @param opts Status, headers, abort signal, and keep-alive; see {@link SSEResponseOptions}.
+ * @returns A streaming `Response` (default status `200`) with SSE headers applied.
  */
 export function sseResponse(source, opts = {}) {
     const stream = sseStream(source, opts);
@@ -185,6 +193,10 @@ export function sseResponse(source, opts = {}) {
  * JSON) records from an async iterable. Each yielded value is encoded with
  * `JSON.stringify` and terminated with `\n`. Values that stringify to
  * `undefined` throw because they cannot be represented as valid NDJSON.
+ *
+ * @param source Async/sync iterable (or factory) yielding JSON-serializable values.
+ * @param opts Optional abort signal; see {@link StreamOptions}.
+ * @returns A `ReadableStream<Uint8Array>` of newline-terminated JSON records.
  */
 export function ndjsonStream(source, opts = {}) {
     const iterator = getAsyncIterator(source);
@@ -246,6 +258,10 @@ export function ndjsonStream(source, opts = {}) {
 /**
  * Wrap `ndjsonStream` in a `Response` with `application/x-ndjson` and
  * cache-busting headers. Caller-supplied headers win.
+ *
+ * @param source Async/sync iterable (or factory) yielding JSON-serializable values.
+ * @param opts Status, headers, and abort signal; see {@link NDJSONResponseOptions}.
+ * @returns A streaming `Response` (default status `200`) with NDJSON headers applied.
  */
 export function ndjsonResponse(source, opts = {}) {
     const stream = ndjsonStream(source, opts);

package/dist/subdomains.d.ts

@@ -92,6 +92,10 @@ export interface SubdomainsResult {
  * // => { baseDomain: "bar.s3.amazonaws.com", subdomain: "foo", labels: ["foo"] }
  * ```
  *
+ * @param hostname - Hostname to split (lowercased; a trailing FQDN dot is stripped).
+ * @param opts - Optional pinned `baseDomain`, `extraSuffixes`, and the `production` staleness gate.
+ * @returns The registrable {@link SubdomainsResult} (`baseDomain`, `subdomain`, `labels`).
+ * @throws {Error} On an empty hostname, a host outside a declared `baseDomain`, or a stale PSL snapshot in production.
  * @since 0.24.0
  */
 export declare function subdomains(hostname: string, opts?: SubdomainsOptions): SubdomainsResult;

package/dist/subdomains.js

@@ -93,6 +93,10 @@ export const MAX_SNAPSHOT_AGE_DAYS = 90;
  * // => { baseDomain: "bar.s3.amazonaws.com", subdomain: "foo", labels: ["foo"] }
  * ```
  *
+ * @param hostname - Hostname to split (lowercased; a trailing FQDN dot is stripped).
+ * @param opts - Optional pinned `baseDomain`, `extraSuffixes`, and the `production` staleness gate.
+ * @returns The registrable {@link SubdomainsResult} (`baseDomain`, `subdomain`, `labels`).
+ * @throws {Error} On an empty hostname, a host outside a declared `baseDomain`, or a stale PSL snapshot in production.
  * @since 0.24.0
  */
 export function subdomains(hostname, opts = {}) {