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

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

package/dist/time-claims.d.ts

@@ -26,10 +26,17 @@
  * @since 0.27.0
  */
 export declare class TemporalClaimError extends Error {
+    /** Machine-readable failure code identifying which claim check failed. */
     readonly code: TemporalClaimErrorCode;
     constructor(code: TemporalClaimErrorCode, message: string);
 }
-/** @since 0.27.0 */
+/**
+ * Failure codes for {@link TemporalClaimError}. `invalid_*` codes mean the
+ * claim (or option) was present but not a finite number; the remaining codes
+ * mean a well-formed claim failed its RFC 7519 time comparison.
+ *
+ * @since 0.27.0
+ */
 export type TemporalClaimErrorCode = "invalid_exp" | "token_expired" | "invalid_nbf" | "token_not_yet_valid" | "invalid_iat" | "iat_in_future" | "invalid_clock_skew";
 /**
  * Subset of a JWT-style payload that participates in temporal validation.
@@ -39,11 +46,19 @@ export type TemporalClaimErrorCode = "invalid_exp" | "token_expired" | "invalid_
  * @since 0.27.0
  */
 export interface TemporalClaims {
+    /** Expiration time (RFC 7519 `exp`), unix seconds. Validated when present. */
     readonly exp?: unknown;
+    /** Not-before time (RFC 7519 `nbf`), unix seconds. Validated when present. */
     readonly nbf?: unknown;
+    /** Issued-at time (RFC 7519 `iat`), unix seconds. Rejected if in the future. */
     readonly iat?: unknown;
 }
-/** @since 0.27.0 */
+/**
+ * Options for {@link assertTemporalClaims}: the reference clock and the
+ * symmetric clock-skew tolerance.
+ *
+ * @since 0.27.0
+ */
 export interface AssertTemporalClaimsOptions {
     /** Current unix-seconds timestamp. Injectable for tests. */
     readonly now: number;
@@ -65,6 +80,11 @@ export interface AssertTemporalClaimsOptions {
  *  - `iat` rejected when `iat - skew > now` (issued in the future — the
  *    issuer's clock is wrong, or someone pre-issued a token).
  *
+ * @param claims Decoded payload; only the claims that are present are checked.
+ * @param opts Reference clock (`now`, unix seconds) and optional
+ *   `clockSkewSeconds` tolerance (defaults to `0`).
+ * @throws TemporalClaimError on the first failing check, including malformed
+ *   (non-finite) claim values or an invalid `now` / negative skew.
  * @since 0.27.0
  */
 export declare function assertTemporalClaims(claims: TemporalClaims, opts: AssertTemporalClaimsOptions): void;

package/dist/time-claims.js

@@ -26,6 +26,7 @@
  * @since 0.27.0
  */
 export class TemporalClaimError extends Error {
+    /** Machine-readable failure code identifying which claim check failed. */
     code;
     constructor(code, message) {
         super(message);
@@ -48,6 +49,11 @@ function isFiniteNumber(v) {
  *  - `iat` rejected when `iat - skew > now` (issued in the future — the
  *    issuer's clock is wrong, or someone pre-issued a token).
  *
+ * @param claims Decoded payload; only the claims that are present are checked.
+ * @param opts Reference clock (`now`, unix seconds) and optional
+ *   `clockSkewSeconds` tolerance (defaults to `0`).
+ * @throws TemporalClaimError on the first failing check, including malformed
+ *   (non-finite) claim values or an invalid `now` / negative skew.
  * @since 0.27.0
  */
 export function assertTemporalClaims(claims, opts) {

package/dist/tracing.d.ts

@@ -47,13 +47,18 @@ export type TracingAttributes = Record<string, TracingAttributeValue>;
  * `Span` (extra OTel methods are ignored).
  */
 export interface TracingSpan {
+    /** Set a single attribute on the span. */
     setAttribute(key: string, value: TracingAttributeValue): void;
+    /** Optional bulk attribute setter; DaloyJS falls back to `setAttribute` per key. */
     setAttributes?(attrs: TracingAttributes): void;
+    /** Set the span status (e.g. {@link TRACING_SPAN_STATUS_ERROR} on failure). */
     setStatus(status: {
         code: number;
         message?: string;
     }): void;
+    /** Optional exception recorder; called with the thrown error on failures. */
     recordException?(err: unknown): void;
+    /** End the span. DaloyJS calls this exactly once per request. */
     end(endTime?: number): void;
 }
 /** Options passed to {@link TracingTracer.startSpan}. */
@@ -65,6 +70,7 @@ export interface TracingStartSpanOptions {
 }
 /** Minimum tracer surface DaloyJS needs. Compatible with `@opentelemetry/api`'s `Tracer`. */
 export interface TracingTracer {
+    /** Create a span; `context` carries the extracted upstream parent context, if any. */
     startSpan(name: string, options?: TracingStartSpanOptions, context?: unknown): TracingSpan;
 }
 /** Options for {@link otelTracing}. */
@@ -101,5 +107,11 @@ export interface OtelTracingOptions {
  * Middleware that wraps every request in an OpenTelemetry-compatible span.
  * Pass any tracer that matches the {@link TracingTracer} surface; DaloyJS
  * does not import `@opentelemetry/api` itself.
+ *
+ * @param opts Tracer plus optional span naming, attribute, and context
+ *   extraction hooks; see {@link OtelTracingOptions}.
+ * @returns A {@link Hooks} object that starts a SERVER span per request,
+ *   exposes it on `ctx.state[stateKey]`, records exceptions, marks 5xx
+ *   responses as errors, and ends the span exactly once on send.
  */
 export declare function otelTracing(opts: OtelTracingOptions): Hooks;

package/dist/tracing.js

@@ -72,6 +72,12 @@ function endOnce(entry, attrs) {
  * Middleware that wraps every request in an OpenTelemetry-compatible span.
  * Pass any tracer that matches the {@link TracingTracer} surface; DaloyJS
  * does not import `@opentelemetry/api` itself.
+ *
+ * @param opts Tracer plus optional span naming, attribute, and context
+ *   extraction hooks; see {@link OtelTracingOptions}.
+ * @returns A {@link Hooks} object that starts a SERVER span per request,
+ *   exposes it on `ctx.state[stateKey]`, records exceptions, marks 5xx
+ *   responses as errors, and ends the span exactly once on send.
  */
 export function otelTracing(opts) {
     const stateKey = opts.stateKey ?? "otelSpan";

package/dist/types.d.ts

@@ -63,9 +63,13 @@ export type PathParams<P extends string> = {
  * @since 0.1.0
  */
 export interface RequestSchemas {
+    /** Validator for path parameters. Without it, `ctx.params` is raw {@link PathParams} strings. */
     params?: StandardSchemaV1;
+    /** Validator for the parsed query string. Without it, `ctx.query` is a raw string record. */
     query?: StandardSchemaV1;
+    /** Validator for request headers. Without it, `ctx.headers` is a raw string record. */
     headers?: StandardSchemaV1;
+    /** Validator for the parsed request body. Without it, `ctx.body` is `unknown`. Prefer `.strict()` object schemas so unexpected keys are rejected. */
     body?: StandardSchemaV1;
 }
 /** Infer the validated output of a Standard Schema validator, or `undefined` when no schema is present. */
@@ -110,12 +114,16 @@ export type InferRequest<R extends RequestSchemas | undefined, P extends string>
  * @since 0.1.0
  */
 export interface ResponseSpec {
+    /** Human-readable description emitted into the OpenAPI response object. Required. */
     description: string;
+    /** Response-body validator; handler return values are checked against it when `AppOptions.validateResponses` is on. */
     body?: StandardSchemaV1;
+    /** Documented response headers keyed by header name; surfaced in the OpenAPI document. */
     headers?: Record<string, {
         description?: string;
         schema?: StandardSchemaV1;
     }>;
+    /** Named example payloads emitted into OpenAPI and served when `AppOptions.mockMode` is enabled. */
     examples?: Record<string, unknown>;
 }
 /**
@@ -216,9 +224,18 @@ export interface AppState {
  * @since 0.24.0
  */
 export type AuthScheme = "bearer" | "basic" | "jwt" | "jwk" | "webhook" | "session" | "apiKey";
-/** @since 0.24.0 */
+/**
+ * Verified-identity envelope written to `ctx.state.auth` by the first-party
+ * auth helpers. The `scheme` discriminant keeps per-scheme logic (revocation
+ * lists, audit logs) from being applied to credentials issued by a different
+ * scheme (see {@link AuthScheme}).
+ *
+ * @since 0.24.0
+ */
 export interface AuthContext<TCredentials = unknown> {
+    /** Discriminant naming the auth helper that verified the request (e.g. `"jwt"`, `"session"`). */
     readonly scheme: AuthScheme;
+    /** The verified credential payload (decoded JWT claims, session record, ...); shape depends on the scheme. */
     readonly credentials: TCredentials;
 }
 /**
@@ -235,11 +252,15 @@ export interface AuthContext<TCredentials = unknown> {
  * @since 0.1.0
  */
 export interface BaseContext<P extends string, R extends RequestSchemas | undefined> {
+    /** The original web-standard `Request`. Its body stream may already be consumed when a `body` schema triggered parsing. */
     request: Request;
     /** Validated request data (or raw fallbacks if no schema). */
     params: InferRequest<R, P>["params"];
+    /** Validated query params; raw `Record<string, string | string[] | undefined>` without a schema. */
     query: InferRequest<R, P>["query"];
+    /** Validated request headers; raw `Record<string, string | undefined>` without a schema. */
     headers: InferRequest<R, P>["headers"];
+    /** Validated request body; `unknown` without a schema. Parsed prototype-pollution-safe (forbidden keys rejected). */
     body: InferRequest<R, P>["body"];
     /** Mutable per-request state. Plugin-augmented context lives here. */
     state: AppState & Record<string, unknown>;
@@ -269,9 +290,13 @@ export interface BaseContext<P extends string, R extends RequestSchemas | undefi
  * @since 0.1.0
  */
 export interface Hooks {
+    /** Runs first, before validation or context building. Receives the raw web-standard `Request`. */
     onRequest?: (req: Request) => void | Promise<void>;
+    /** Runs with the validated {@link BaseContext} before the handler. Returning a `Response` short-circuits the handler entirely (useful for auth guards). */
     beforeHandle?: (ctx: BaseContext<any, any>) => void | Response | Promise<void | Response>;
+    /** Runs after the handler with its raw return value. Return a non-`undefined` value to replace the result before serialization and response-schema validation. */
     afterHandle?: (ctx: BaseContext<any, any>, result: unknown) => void | unknown | Promise<void | unknown>;
+    /** Runs on the error path before serialization. `ctx` is `undefined` if the error occurred before context was built. Return a `Response` to replace the default RFC 9457 problem+json error response. */
     onError?: (err: unknown, ctx: BaseContext<any, any> | undefined) => void | Response | Promise<void | Response>;
     /**
      * Symmetric to `beforeHandle`, but for outgoing responses. Runs after the Response
@@ -281,6 +306,7 @@ export interface Hooks {
      * the existing response. Multiple `onSend` hooks compose pipeline-style.
      */
     onSend?: (res: Response, ctx: BaseContext<any, any> | undefined) => void | Response | Promise<void | Response>;
+    /** Fire-and-forget observer of the final outgoing `Response` (logging, metrics). Runs last; cannot alter the response. */
     onResponse?: (res: Response) => void | Promise<void>;
 }
 /**
@@ -312,14 +338,35 @@ export interface Hooks {
  * @since 0.1.0
  */
 export interface RouteDefinition<P extends PathString = PathString, M extends HttpMethod = HttpMethod, Req extends RequestSchemas | undefined = undefined, Res extends ResponsesMap = ResponsesMap> {
+    /** HTTP method to match (uppercase, e.g. `"GET"`). See {@link HttpMethod}. */
     method: M;
+    /** URL path pattern starting with `/`; `:name` segments become typed path params (e.g. `"/books/:id"`). */
     path: P;
+    /** Stable unique operation id for OpenAPI and the generated client (drives SDK method names). Omitted from the spec when unset. */
     operationId?: string;
+    /** One-line summary shown in OpenAPI docs UIs. */
     summary?: string;
+    /** Longer free-form description for the OpenAPI operation (CommonMark allowed). */
     description?: string;
+    /** OpenAPI tags used to group the operation in docs UIs; merged with {@link RouteMeta.tags}. */
     tags?: string[];
+    /** Emits `deprecated: true` on the OpenAPI operation. Set implicitly when {@link RouteDefinition.sunset} is present. */
     deprecated?: boolean;
+    /** Optional per-route API version label. Informational metadata only; not emitted into the OpenAPI document. */
     version?: string;
+    /**
+     * Acknowledge that this route's `2xx` responses intentionally carry no
+     * response body schema — an opaque, framework-controlled, or non-JSON body
+     * (a raw `Response`, an HTML page, a spec document, a proxied payload).
+     *
+     * Setting this suppresses the `security.response.bodySchemaMissing` boot
+     * warning and the `audit.response.bodySchema` `daloy doctor` finding for
+     * this route only. It documents intent; it does not add protection —
+     * response field-level stripping (OWASP API3) still does not run for a
+     * `2xx` response without a body schema, so never set this on a route whose
+     * handler builds JSON from domain objects.
+     */
+    acknowledgeNoResponseBodySchema?: boolean;
     /**
      * Mark the endpoint as scheduled for removal at a specific date (RFC 8594
      * "The Sunset HTTP Header Field"). Accepts an ISO-8601 string, any string
@@ -353,8 +400,11 @@ export interface RouteDefinition<P extends PathString = PathString, M extends Ht
      * @since 0.37.0
      */
     sunset?: string | Date;
+    /** Standard Schemas ({@link RequestSchemas}) validating `params`/`query`/`headers`/`body`. Parts without a schema arrive untyped; validation failures return 400/422 before the handler runs. */
     request?: Req;
+    /** Map of status code to {@link ResponseSpec}. Drives response-body validation, the handler's allowed return types, OpenAPI responses, and the typed client. */
     responses: Res;
+    /** Declarative auth requirement ({@link AuthSpec}); surfaces as the OpenAPI `security` requirement for this operation. */
     auth?: AuthSpec;
     /**
      * Per-route Content-Type allowlist. When the route declares a `body`
@@ -421,6 +471,7 @@ export interface RouteDefinition<P extends PathString = PathString, M extends Ht
      * @since 0.14.0
      */
     meta?: RouteMeta;
+    /** Per-route lifecycle {@link Hooks}. Run after global and group hooks in the pipeline. */
     hooks?: Hooks;
     /**
      * The route handler. Receives the typed, validated {@link BaseContext} and
@@ -455,14 +506,23 @@ export interface RouteDefinition<P extends PathString = PathString, M extends Ht
  * `handler` (no execution path on the producer side).
  */
 export interface CallbackOperation {
+    /** HTTP method the producer uses when invoking the callback URL. */
     method: HttpMethod;
+    /** Stable unique operation id for the callback operation in the OpenAPI document. */
     operationId?: string;
+    /** One-line summary shown in OpenAPI docs UIs. */
     summary?: string;
+    /** Longer free-form description for the callback operation. */
     description?: string;
+    /** OpenAPI tags grouping the callback operation in docs UIs. */
     tags?: string[];
+    /** Emits `deprecated: true` on the callback operation. */
     deprecated?: boolean;
+    /** Schemas describing the outgoing callback request (documentation only; never executed by the framework). */
     request?: RequestSchemas;
+    /** Responses the producer expects back from the consumer, keyed by status code. */
     responses: ResponsesMap;
+    /** Auth requirement the callback request is documented to carry ({@link AuthSpec}). */
     auth?: AuthSpec;
 }
 /**
@@ -495,14 +555,18 @@ export interface CallbackMap {
  * @since 0.14.0
  */
 export interface RouteExample {
+    /** One-line label for the example, surfaced as the OpenAPI example `summary`. */
     summary?: string;
+    /** Longer explanation of what the example demonstrates. */
     description?: string;
+    /** Sample inbound request. `body` is validated against the route's request body schema by `runContractTests()`. */
     request?: {
         params?: Record<string, string>;
         query?: Record<string, unknown>;
         headers?: Record<string, string>;
         body?: unknown;
     };
+    /** Sample response. `status` must be declared in the route's `responses`; `body` is validated against that status's schema. */
     response?: {
         status: number;
         body?: unknown;
@@ -526,9 +590,14 @@ export interface RouteExample {
  * @since 0.14.0
  */
 export interface RouteMeta {
+    /** Fallback operation summary; the route-level `summary` wins when both are set. */
     summary?: string;
+    /** Fallback operation description; the route-level `description` wins when both are set. */
     description?: string;
+    /** Extra OpenAPI tags, merged (deduplicated) with the route-level `tags`. */
     tags?: string[];
+    /** Named request/response examples ({@link RouteExample}); validated against the route's schemas by `runContractTests()`. */
     examples?: Record<string, RouteExample>;
+    /** Free-form vendor extensions emitted as `x-<key>` on the OpenAPI operation; keys are auto-prefixed with `x-` when missing. */
     extensions?: Record<string, unknown>;
 }

package/dist/waf.js

@@ -80,7 +80,12 @@ const XSS_SIGNATURES = Object.freeze([
     /<script[\s\S]{0,40}?>/i,
     /<\/script\s*>/i,
     /javascript:\s*\S/i,
-    /\bon(?:error|load|click|mouseover|focus|submit|toggle|animationstart)\s*=/i,
+    // Inline event-handler attributes. Explicit alternation (not `on\w+`) to
+    // avoid false-positives on benign params like `online=`/`once=`, but broadened
+    // well beyond the classic four to cover the paren-less handlers commonly used
+    // to evade keyword blocklists (pointer/focus/touch/wheel/toggle events — see
+    // the ES6-for-pentesters technique in the cure53-web-frontend-offense skill).
+    /\bon(?:error|load|click|dblclick|aux(?:click)?|contextmenu|mouse(?:over|enter|move|down|up|out|leave)|pointer(?:over|enter|down|up|move|rawupdate|leave)|touch(?:start|move|end)|focus(?:in|out)?|blur|input|change|submit|reset|toggle|beforetoggle|scroll|wheel|drag|drop|copy|cut|paste|play|playing|canplay|show|hashchange|popstate|pageshow|pagehide|message|animation(?:start|end|iteration)|transitionend|key(?:down|up|press)|load(?:start|end)|progress)\s*=/i,
     /<iframe[\s>]/i,
     /<img[\s\S]{0,80}?\bonerror\s*=/i,
     /<svg[\s\S]{0,40}?\bonload\s*=/i,
@@ -268,11 +273,26 @@ export function waf(opts = {}) {
             if (inspectQuery && url.search.length > 1) {
                 // Scan both the raw query string and a best-effort decoded form so an
                 // encoded payload (`%27%20OR%201=1`) is caught after normalization.
+                // This is a SINGLE decode on purpose: the framework's request path also
+                // decodes the query exactly once, so the WAF sees the same bytes the
+                // handler will. Recursive decoding is deliberately avoided — it would
+                // false-positive on values that legitimately contain percent-encoded
+                // text, and a double-encoded payload stays inert (`%3Cscript%3E`) all
+                // the way to the handler. See red-team-attacks-6 "DOCUMENTED LIMITATION".
                 const raw = url.search.slice(1);
                 scanValue(raw, "query", rules, scored);
                 const decoded = safeDecode(raw);
                 if (decoded !== raw)
                     scanValue(decoded, "query", rules, scored);
+                // Additionally inspect each key/value the way the app's OWN query parser
+                // (`URLSearchParams`) decodes them: notably `+` becomes a space, which a
+                // plain `decodeURIComponent` does NOT do. Without this, `1+OR+1=1` slipped
+                // past the WAF while the handler still received `1 OR 1=1` (a parser
+                // differential — the WAF must inspect the bytes the app actually parses).
+                for (const [k, v] of url.searchParams) {
+                    scanValue(k, "query", rules, scored);
+                    scanValue(v, "query", rules, scored);
+                }
             }
             if (headerAllowlist.length > 0) {
                 for (const name of headerAllowlist) {

package/dist/webhook-delivery.d.ts

@@ -122,6 +122,7 @@ export interface WebhookDeadLetter {
  * @since 0.37.0
  */
 export interface WebhookDeadLetterSink {
+    /** Persist a permanently-failed delivery. May be async; the sender awaits it. */
     add(letter: WebhookDeadLetter): void | Promise<void>;
 }
 /**
@@ -258,6 +259,11 @@ export interface WebhookSenderOptions {
  * const result = await send({ url, eventType: "user.created", payload: { id } });
  * ```
  *
+ * @param options - Signing secret plus delivery policy; see
+ *   {@link WebhookSenderOptions} for the per-field defaults.
+ * @returns A `send(event)` function that resolves to a
+ *   {@link WebhookDeliveryResult}.
+ * @throws Error at construction when `secret` is missing or empty.
  * @since 0.37.0
  */
 export declare function createWebhookSender(options: WebhookSenderOptions): (event: WebhookEvent) => Promise<WebhookDeliveryResult>;

package/dist/webhook-delivery.js

@@ -140,6 +140,11 @@ function randomId() {
  * const result = await send({ url, eventType: "user.created", payload: { id } });
  * ```
  *
+ * @param options - Signing secret plus delivery policy; see
+ *   {@link WebhookSenderOptions} for the per-field defaults.
+ * @returns A `send(event)` function that resolves to a
+ *   {@link WebhookDeliveryResult}.
+ * @throws Error at construction when `secret` is missing or empty.
  * @since 0.37.0
  */
 export function createWebhookSender(options) {