@daloyjs/core 0.36.0 → 0.38.0

package/dist/security.js

@@ -5,10 +5,10 @@
  * - safeJsonParse: JSON parser that strips __proto__ / constructor / prototype
  *   keys to prevent prototype-pollution attacks.
  * - sanitizeHeaderName / sanitizeHeaderValue: prevent CRLF header injection.
- * - timingSafeEqual: constant-time string comparison for token checks.
+ * - timingSafeEqual: length-independent string compare for fixed-length token checks.
  * - randomId: cryptographically strong request id.
  */
-import { PayloadTooLargeError, BadRequestError, } from "./errors.js";
+import { PayloadTooLargeError, BadRequestError, RequestHeaderFieldsTooLargeError, } from "./errors.js";
 // Resolved once at module load. Mirror of `DALOY_REQUEST_RAW_BODY` in
 // app.ts; defined here via the global Symbol registry to avoid an import
 // cycle (app.ts -> security.ts). Adapters attach a pre-validated
@@ -160,12 +160,32 @@ export function sanitizeHeaderValue(value) {
     return value;
 }
 /**
- * Constant-time string comparison resistant to timing attacks. Use whenever
- * comparing secrets such as CSRF tokens, HMAC signatures, or API keys; never
- * use `===` for those comparisons.
- *
- * @param a - First string.
- * @param b - Second string.
+ * Length-independent string comparison resistant to the *first-mismatch*
+ * timing leak. Use whenever comparing secrets such as CSRF tokens, HMAC
+ * signatures, or API keys; never use `===` for those comparisons.
+ *
+ * The comparison always folds every character of the longer input into a
+ * single accumulator (no early return), so it does not reveal the position
+ * of the first differing character the way `===` does. The byte lengths are
+ * mixed in too, so inputs of different lengths can never compare equal.
+ *
+ * Caveats — read before using for anything other than fixed-length tokens:
+ *
+ *  - **Length is not hidden.** The loop runs `max(a.length, b.length)`
+ *    iterations, so the running time grows with the longer input. Intended
+ *    for values whose length is fixed and public (hex/base64 tokens, HMAC
+ *    digests, API keys). Do not rely on it to conceal the length of a
+ *    secret from an attacker who controls the other side.
+ *  - **Not a hardware constant-time primitive.** It compares UTF-16 code
+ *    units via `charCodeAt`, and the engine's per-character access time is
+ *    not provably uniform. For raw bytes you already hold in memory, prefer
+ *    Node's `crypto.timingSafeEqual(Buffer, Buffer)`, which also rejects
+ *    length mismatches outright.
+ *  - **Compares code units, not bytes.** Fine for ASCII tokens; for
+ *    arbitrary binary, compare `Uint8Array`s instead.
+ *
+ * @param a - First string (typically the attacker-supplied candidate).
+ * @param b - Second string (typically the expected secret).
  * @returns `true` when the strings have the same length and contents.
  * @since 0.1.0
  */
@@ -301,6 +321,53 @@ export function assertNoReservedInternalHeaders(headers) {
         }
     });
 }
+/**
+ * Default cap on the number of distinct request header fields accepted
+ * before {@link assertHeaderCountWithinLimit} rejects the request. Chosen to
+ * sit far above any realistic legitimate request (browsers, tracing layers,
+ * and reverse proxies rarely add more than a few dozen headers) yet far
+ * below the thousands-of-headers floods used by header-count amplification
+ * attacks such as the "HTTP/2 Bomb".
+ *
+ * @since 0.38.0
+ */
+export const DEFAULT_MAX_HEADER_COUNT = 100;
+/**
+ * Reject requests that carry more than `limit` distinct header fields.
+ *
+ * This is the runtime-portable, application-tier defence against
+ * header-*count* amplification (the dimension abused by the "HTTP/2 Bomb",
+ * where per-entry server bookkeeping — not header size — is the amplifier).
+ * It complements, and does not replace, the native header-count caps that a
+ * runtime/proxy terminating HTTP/2 must apply (NGINX `max_headers`, Node
+ * `server.maxHeadersCount`, etc.). Because the WHATWG `Headers` collection
+ * coalesces same-named fields, the count is over distinct header names —
+ * the truest signal available once a request has been normalised to a
+ * web-standard `Request`.
+ *
+ * A `limit` of `0` (or any non-positive / non-finite value) disables the
+ * check. Throws {@link RequestHeaderFieldsTooLargeError} (`431`) so the
+ * framework returns a structured `problem+json` response instead of routing
+ * a flood.
+ *
+ * @param headers - The incoming request headers.
+ * @param limit - Maximum distinct header fields to allow. `0` disables.
+ * @since 0.38.0
+ */
+export function assertHeaderCountWithinLimit(headers, limit) {
+    if (!(limit > 0) || !Number.isFinite(limit))
+        return;
+    let count = 0;
+    // Count via forEach (not keys()) so a same-named coalesced field counts
+    // once and the check works on any Headers-shaped object. Throwing from the
+    // callback bails the instant the cap is crossed, so a flood pays for at
+    // most `limit + 1` iterations rather than walking the whole set.
+    headers.forEach(() => {
+        if (++count > limit) {
+            throw new RequestHeaderFieldsTooLargeError(limit);
+        }
+    });
+}
 /**
  * Minimum acceptable secret length in bytes for HMAC / signing material in
  * production (boot guard). Matches the OWASP "Secret Management"

package/dist/session.js

@@ -290,12 +290,12 @@ export function session(opts) {
             }
             internal.activeId = id;
             const regenerate = async (keepData) => {
+                // Only destroy a persisted session id. An id created earlier this
+                // request (or a prior mid-request rotation) was never written to the
+                // store, so there is nothing to destroy — we just discard it.
                 if (internal.activeId && internal.originalId === internal.activeId) {
                     await store.destroy(internal.activeId);
                 }
-                else if (internal.activeId && internal.activeId !== internal.originalId) {
-                    // We rotated mid-request previously; throw away the unsaved id.
-                }
                 const next = generator();
                 if (!next)
                     throw new Error("session(): generator returned an empty id.");

package/dist/types.d.ts

@@ -320,6 +320,39 @@ export interface RouteDefinition<P extends PathString = PathString, M extends Ht
     tags?: string[];
     deprecated?: boolean;
     version?: string;
+    /**
+     * 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
+     * parseable by `new Date(...)`, or a `Date`. When set, the framework:
+     *
+     * - implicitly treats the route as {@link RouteDefinition.deprecated}
+     *   (the OpenAPI operation is emitted with `deprecated: true`);
+     * - emits a `Deprecation: true` response header (RFC 8594 / the
+     *   `Deprecation` HTTP header field) on every response from the route; and
+     * - emits a `Sunset: <IMF-fixdate>` response header normalized to an HTTP
+     *   date so clients and gateways can schedule migration.
+     *
+     * The OpenAPI document also surfaces the normalized value as an
+     * `x-sunset` vendor extension on the operation.
+     *
+     * Invalid (unparseable) values are rejected at `app.route(...)`
+     * registration time, never per-request.
+     *
+     * @example
+     * ```ts
+     * app.route({
+     *   method: "GET",
+     *   path: "/v1/legacy",
+     *   deprecated: true,
+     *   sunset: "2026-12-31T00:00:00Z",
+     *   responses: { 200: { description: "OK" } },
+     *   handler: () => ({ status: 200, body: { ok: true } }),
+     * });
+     * ```
+     *
+     * @since 0.37.0
+     */
+    sunset?: string | Date;
     request?: Req;
     responses: Res;
     auth?: AuthSpec;

package/dist/waf.d.ts

@@ -0,0 +1,213 @@
+/**
+ * WAF-lite signature/anomaly inbound-inspection middleware (OWASP CRS-lite).
+ *
+ * DaloyJS deliberately leaves a full Web Application Firewall to the operator's
+ * edge (CDN / reverse proxy / ModSecurity CRS). {@link waf} is **not** that — it
+ * is a first-party, opt-in, *defense-in-depth* layer for teams that do not have
+ * an edge WAF, wiring the framework's high-confidence injection signatures
+ * (SQLi, XSS, NoSQL-operator injection, command injection) into a single scored
+ * inbound-inspection pass with per-rule enable/disable and a block-or-log mode.
+ *
+ * Each enabled rule contributes an **anomaly score** when it matches anywhere in
+ * the inspected surface (the decoded URL path, the raw + decoded query string,
+ * an optional header allowlist, and the validated request body). When a
+ * request's total score reaches {@link WafOptions.blockThreshold}, the request is
+ * either rejected with a generic `403` (block mode, the default) or merely
+ * reported to {@link WafOptions.onMatch} (log mode) so operators can tune rules
+ * against real traffic before enforcing.
+ *
+ * Design notes / secure-by-default posture:
+ * - The `403` body is intentionally generic — it never tells the attacker which
+ *   signature fired. Rule detail is delivered server-side via `onMatch` only.
+ * - Body inspection covers the **validated** body (`ctx.body`), so it composes
+ *   with the framework's schema-first contract. Routes without a body schema are
+ *   not body-inspected (their body is never parsed); inspect their inputs with a
+ *   schema to bring them under coverage.
+ * - Header inspection is **opt-in** (off by default) because header values
+ *   (notably `User-Agent` / `Cookie`) carry parentheses and punctuation that can
+ *   trip signatures; enable it with an explicit allowlist.
+ * - Scanning is bounded: per-value length and total node-count caps keep a
+ *   hostile or huge payload from turning inspection into CPU-DoS.
+ * - Signatures are curated for **high confidence / low false-positive rate**;
+ *   this is a complement to, not a replacement for, input schemas and parameter
+ *   binding. Start in `"log"` mode, watch `onMatch`, then switch to `"block"`.
+ *
+ * The middleware is dependency-free and runtime-portable. It inspects the built
+ * context in the {@link "./types.js".Hooks.beforeHandle} phase (so query, params,
+ * headers, and the validated body are all available) and reuses
+ * {@link "./security.js".hasMongoOperatorKeys} for structural NoSQL-operator
+ * detection. Register it with `app.use(waf())`.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import type { Hooks } from "./types.js";
+/**
+ * Identifier of a built-in WAF rule category. Each maps to a curated set of
+ * high-confidence signatures (plus, for `nosqli`, a structural body check).
+ *
+ * @since 0.37.0
+ */
+export type WafRuleId = "sqli" | "xss" | "nosqli" | "cmdi";
+/**
+ * Where in the request a signature matched. Surfaced on {@link WafMatch} so
+ * operators can see whether the hit came from the path, query string, an
+ * inspected header, or the request body.
+ *
+ * @since 0.37.0
+ */
+export type WafInspectionLocation = "path" | "query" | "header" | "body";
+/**
+ * Per-rule configuration. Pass a boolean to enable/disable a rule, or an object
+ * to enable it with a custom anomaly {@link WafRuleConfig.score}.
+ *
+ * @since 0.37.0
+ */
+export interface WafRuleConfig {
+    /** Whether the rule is active. Default: `true`. */
+    enabled?: boolean;
+    /** Anomaly score this rule contributes when it matches. Default: `5`. */
+    score?: number;
+}
+/**
+ * One rule's contribution to a flagged request. Reported (deduplicated per rule)
+ * in {@link WafEvent.matches}.
+ *
+ * @since 0.37.0
+ */
+export interface WafMatch {
+    /** Which rule category fired. */
+    ruleId: WafRuleId;
+    /** The anomaly score this rule contributed. */
+    score: number;
+    /** Where the first matching value was found. */
+    location: WafInspectionLocation;
+    /** A short, truncated sample of the offending value (for server-side logs). */
+    sample: string;
+}
+/**
+ * Detail of a flagged request, passed to {@link WafOptions.onMatch}. Emitted only
+ * when a request's total score reaches the block threshold (in both `"block"`
+ * and `"log"` mode), so it always represents an actionable detection.
+ *
+ * @since 0.37.0
+ */
+export interface WafEvent {
+    /** The mode the middleware is running in. */
+    mode: WafMode;
+    /** Whether the request was rejected (`"block"`) or allowed through (`"log"`). */
+    action: "blocked" | "logged";
+    /** The request method. */
+    method: string;
+    /** The request path (decoded pathname). */
+    path: string;
+    /** Best-effort client IP (socket remote address), when available. */
+    clientIp: string | undefined;
+    /** Total anomaly score accumulated across all fired rules. */
+    score: number;
+    /** The threshold the score met or exceeded. */
+    threshold: number;
+    /** The deduplicated per-rule matches that drove the score. */
+    matches: readonly WafMatch[];
+}
+/**
+ * Enforcement mode for {@link waf}.
+ *
+ * - `"block"` (default) — reject a flagged request with a generic `403`.
+ * - `"log"` — never reject; only invoke {@link WafOptions.onMatch}. Use this to
+ *   tune rules against production traffic before enforcing.
+ *
+ * @since 0.37.0
+ */
+export type WafMode = "block" | "log";
+/**
+ * Selects which parts of the request are inspected. Path, query, and body are
+ * inspected by default; header inspection is opt-in via {@link WafInspectConfig.headers}.
+ *
+ * @since 0.37.0
+ */
+export interface WafInspectConfig {
+    /** Inspect the decoded URL pathname. Default: `true`. */
+    path?: boolean;
+    /** Inspect the raw and decoded query string. Default: `true`. */
+    query?: boolean;
+    /** Inspect the validated request body (`ctx.body`). Default: `true`. */
+    body?: boolean;
+    /**
+     * Inspect a specific allowlist of request headers (lower-cased names). Header
+     * inspection is **off** unless you provide this list, because common headers
+     * (`User-Agent`, `Cookie`, `Referer`) carry punctuation that can trip
+     * signatures. Example: `["referer", "x-forwarded-host"]`.
+     */
+    headers?: readonly string[];
+}
+/**
+ * Configuration for {@link waf}. Every field is optional — `waf()` ships secure,
+ * low-false-positive defaults (all four rules on at score 5, block threshold 5,
+ * block mode, path/query/body inspected, headers not).
+ *
+ * @since 0.37.0
+ */
+export interface WafOptions {
+    /** Enforcement mode. Default: `"block"`. */
+    mode?: WafMode;
+    /**
+     * Per-rule overrides. Any rule omitted here keeps its default (enabled, score
+     * 5). Disable a noisy rule with `{ xss: false }`, or reweight one with
+     * `{ sqli: { score: 8 } }`.
+     */
+    rules?: Partial<Record<WafRuleId, boolean | WafRuleConfig>>;
+    /**
+     * Total anomaly score at which a request is flagged (blocked or logged).
+     * Default: `5` — any single high-confidence rule trips it. Raise it (e.g. `8`)
+     * to require two independent rule categories to fire. Must be a positive number.
+     */
+    blockThreshold?: number;
+    /** Which request parts to inspect. See {@link WafInspectConfig}. */
+    inspect?: WafInspectConfig;
+    /**
+     * Cap on the length of any single string value that is scanned. Longer values
+     * are truncated to this prefix before matching. Default: `8192`. Must be a
+     * positive integer.
+     */
+    maxValueLength?: number;
+    /**
+     * Cap on the number of nodes walked when inspecting the body, to bound CPU on
+     * deeply nested or huge payloads. Default: `10000`. Must be a positive integer.
+     */
+    maxBodyNodes?: number;
+    /**
+     * Observability callback invoked once per flagged request (in both modes),
+     * before any `403` is thrown. Receives the structured {@link WafEvent}. Must
+     * not throw.
+     */
+    onMatch?: (event: WafEvent) => void;
+}
+/**
+ * Build an opt-in, scored WAF-lite inbound-inspection middleware.
+ *
+ * Inspects the decoded path, query string, an optional header allowlist, and the
+ * validated body for SQLi / XSS / NoSQL-operator / command-injection signatures.
+ * When the summed anomaly score of the rules that fire reaches
+ * {@link WafOptions.blockThreshold}, the request is rejected with a generic `403`
+ * (block mode) or reported to {@link WafOptions.onMatch} (log mode).
+ *
+ * ```ts
+ * import { App, waf } from "@daloyjs/core";
+ *
+ * const app = new App();
+ *
+ * // Start in log mode to tune against real traffic, then switch to block.
+ * app.use(waf({
+ *   mode: "log",
+ *   onMatch: (e) => logger.warn({ waf: e }, "waf detection"),
+ * }));
+ * ```
+ *
+ * @param opts - Mode, per-rule overrides, threshold, inspection surface, and the `onMatch` hook.
+ * @returns A {@link "./types.js".Hooks} bundle exposing only a `beforeHandle` hook.
+ * @throws {TypeError} At construction when an option is invalid.
+ * @throws {ForbiddenError} Per request, in block mode, when a request is flagged.
+ * @since 0.37.0
+ */
+export declare function waf(opts?: WafOptions): Hooks;