@nifrajs/middleware 0.1.0-alpha.1

package/dist/pretty-json.js

@@ -0,0 +1,88 @@
+import { definePlugin } from "@nifrajs/core";
+const JSON_TYPE = /^(?:application\/json|[^/]+\/[^;]+\+json)(?:\s*;|$)/i;
+function isJson(contentType) {
+    return JSON_TYPE.test(contentType);
+}
+function parseLength(value) {
+    if (value === null)
+        return undefined;
+    if (!/^(?:0|[1-9]\d*)$/.test(value))
+        return undefined;
+    return Number(value);
+}
+async function readTextCapped(res, maxBytes) {
+    const body = res.clone().body;
+    if (body === null)
+        return null;
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let total = 0;
+    let text = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                return text + decoder.decode();
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel();
+                return null;
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Pretty-print JSON responses for debugging and developer-facing APIs. It only touches JSON content,
+ * skips encoded responses, caps inspection size, and leaves invalid JSON untouched.
+ */
+export function prettyJson(options = {}) {
+    const spaces = options.spaces ?? 2;
+    if (!Number.isInteger(spaces) || spaces < 0 || spaces > 10) {
+        throw new Error("prettyJson: spaces must be an integer from 0 to 10");
+    }
+    const maxBytes = options.maxBytes ?? 1_000_000;
+    if (!Number.isInteger(maxBytes) || maxBytes < 0) {
+        throw new Error("prettyJson: maxBytes must be a non-negative integer");
+    }
+    const newline = options.newline !== false;
+    const query = options.query ?? false;
+    if (query !== false && query.trim() === "")
+        throw new Error("prettyJson: query is empty");
+    const enabled = options.enabled ?? true;
+    const isEnabled = typeof enabled === "function" ? enabled : enabled ? () => true : () => false;
+    return definePlugin("prettyJson", (app) => app.onResponse(async (res, req) => {
+        if (!isEnabled(req))
+            return res;
+        if (query !== false && !new URL(req.url).searchParams.has(query))
+            return res;
+        if (res.body === null || res.headers.has("content-encoding"))
+            return res;
+        if (!isJson(res.headers.get("content-type") ?? ""))
+            return res;
+        const declared = parseLength(res.headers.get("content-length"));
+        if (declared !== undefined && declared > maxBytes)
+            return res;
+        const text = await readTextCapped(res, maxBytes);
+        if (text === null)
+            return res;
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return res;
+        }
+        const headers = new Headers(res.headers);
+        headers.delete("content-length");
+        return new Response(`${JSON.stringify(parsed, null, spaces)}${newline ? "\n" : ""}`, {
+            status: res.status,
+            statusText: res.statusText,
+            headers,
+        });
+    }));
+}
+//# sourceMappingURL=pretty-json.js.map

package/dist/pretty-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pretty-json.js","sourceRoot":"","sources":["../src/pretty-json.ts"],"names":[],"mappings":"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"}

package/dist/rate-limit.d.ts

@@ -0,0 +1,92 @@
+import type { Middleware } from "@nifrajs/core";
+export interface RateLimitResult {
+    /** Hits recorded in the current window, including this one. */
+    readonly count: number;
+    /** Epoch-ms when the current window resets. */
+    readonly resetAt: number;
+}
+/**
+ * Counter backend. Production deploys MUST use a shared store (Redis, etc.) so the
+ * limit holds across instances — that's a user dependency, not ours, hence the
+ * interface. {@link MemoryStore} is for dev / single-instance only.
+ */
+export interface RateLimitStore {
+    hit(key: string, windowMs: number): Promise<RateLimitResult>;
+}
+export interface MemoryStoreOptions {
+    /** Allow the in-memory store in production. Off by default — a per-instance limiter is unsafe across instances. */
+    readonly allowInProduction?: boolean;
+    /** Hard cap on tracked client keys; expired keys are evicted first, then oldest active keys. Default `100_000`.
+     * Bounds memory against an unbounded key space (bot scans, per-IP buckets). */
+    readonly maxKeys?: number;
+    /** Minimum interval (ms) between amortized sweeps of expired windows. Default `30_000`. */
+    readonly sweepIntervalMs?: number;
+}
+/**
+ * In-process fixed-window store. Refuses to run in production unless explicitly allowed.
+ *
+ * Bounded against unbounded growth: expired windows are swept lazily (amortized, at most once per
+ * `sweepIntervalMs`) and the key set is hard-capped at `maxKeys` (expired keys are evicted first,
+ * then oldest active keys).
+ * Without this, expired entries for keys never seen again — and the unbounded key space of a bot scan
+ * — would accumulate in the map forever and OOM a single-instance deploy.
+ */
+export declare class MemoryStore implements RateLimitStore {
+    private readonly windows;
+    private readonly maxKeys;
+    private readonly sweepIntervalMs;
+    private lastSweep;
+    private evictionScans;
+    /** Cumulative entries inspected by the eviction scan since construction — an eviction-pressure
+     * gauge. The bounded scan keeps this ~O(1) per over-cap insert (≤ {@link MAX_EVICTION_SCAN}); a
+     * regressed full O(n) sweep would make it ~maxKeys per insert (what the regression test asserts). */
+    get evictionScanCount(): number;
+    constructor(options?: MemoryStoreOptions);
+    hit(key: string, windowMs: number): Promise<RateLimitResult>;
+    private sweepExpired;
+    private enforceMaxKeys;
+}
+export interface RateLimitOptions {
+    /** Where counters live. `MemoryStore` for dev; a shared store in production. */
+    readonly store: RateLimitStore;
+    /** Max requests allowed per window. */
+    readonly max: number;
+    /** Window length, in milliseconds. */
+    readonly windowMs: number;
+    /**
+     * How many trusted reverse proxies sit in front of the app and append to `X-Forwarded-For`.
+     * Default `0`.
+     *
+     * The default key reads the client IP from `X-Forwarded-For` as the address your **edge** proxy
+     * observed — the entry `trustedProxies` from the right (1 proxy → the rightmost hop; 2 → the
+     * second-from-right; …). Your proxies append on the right, so a client can only inject fake hops on
+     * the *left*, which this skips → not spoofable when `trustedProxies` matches your topology.
+     *
+     * ⚠️ With the default `0`, `X-Forwarded-For` is treated as fully client-controlled and **ignored**.
+     * Reading the
+     * *first* XFF hop — the old behavior — let any client mint a fresh bucket per request and defeat the
+     * limiter. Set `trustedProxies` (only safe behind a proxy you control that appends XFF), configure a
+     * trusted single-IP {@link header}, or supply a custom {@link key} (e.g. an authenticated user id).
+     */
+    readonly trustedProxies?: number;
+    /** Exact trusted single-IP header, e.g. an infra-set `x-real-ip`. Not read unless configured. */
+    readonly header?: string;
+    /**
+     * Allow one shared bucket when no per-request key can be derived. Off by default because it lets one
+     * client consume the quota for everyone. Enable only for intentional global throttles.
+     */
+    readonly allowGlobalKey?: boolean;
+    /**
+     * Bucket key for a request. Overrides the default XFF-based key entirely — set this for accurate
+     * per-client limiting (e.g. an authenticated user id, or a header your proxy sets). A `Middleware`
+     * can't see the socket IP (that needs the server instance).
+     */
+    readonly key?: (req: Request) => string;
+}
+/**
+ * Rate limiting as a {@link Middleware}. Runs in `onRequest` (before routing, so it
+ * also covers 404s); over the limit → `429` + `Retry-After`. Every response carries
+ * `RateLimit-Limit/Remaining/Reset` (added in `onResponse`, keyed off the request).
+ */
+export declare function rateLimit(options: RateLimitOptions): Middleware;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE/C,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CAC7D;AAED,MAAM,WAAW,kBAAkB;IACjC,mHAAmH;IACnH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;IACpC;mFAC+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AAOD;;;;;;;;GAQG;AACH,qBAAa,WAAY,YAAW,cAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwD;IAChF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,aAAa,CAAI;IAEzB;;yGAEqG;IACrG,IAAI,iBAAiB,IAAI,MAAM,CAE9B;gBAEW,OAAO,GAAE,kBAAuB;IAiB5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAmB5D,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,cAAc;CAuBvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,iGAAiG;IACjG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;IACjC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAA;CACxC;AA4BD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,UAAU,CAyD/D"}

package/dist/rate-limit.js

@@ -0,0 +1,172 @@
+/** Max entries scanned (oldest-first) per eviction looking for an expired victim before falling back
+ * to evicting the oldest-inserted. Bounds eviction to O(1) per insertion instead of a full O(n) sweep
+ * under a distinct-key flood — the abuse the key cap defends against. */
+const MAX_EVICTION_SCAN = 64;
+/**
+ * In-process fixed-window store. Refuses to run in production unless explicitly allowed.
+ *
+ * Bounded against unbounded growth: expired windows are swept lazily (amortized, at most once per
+ * `sweepIntervalMs`) and the key set is hard-capped at `maxKeys` (expired keys are evicted first,
+ * then oldest active keys).
+ * Without this, expired entries for keys never seen again — and the unbounded key space of a bot scan
+ * — would accumulate in the map forever and OOM a single-instance deploy.
+ */
+export class MemoryStore {
+    windows = new Map();
+    maxKeys;
+    sweepIntervalMs;
+    lastSweep = 0;
+    evictionScans = 0;
+    /** Cumulative entries inspected by the eviction scan since construction — an eviction-pressure
+     * gauge. The bounded scan keeps this ~O(1) per over-cap insert (≤ {@link MAX_EVICTION_SCAN}); a
+     * regressed full O(n) sweep would make it ~maxKeys per insert (what the regression test asserts). */
+    get evictionScanCount() {
+        return this.evictionScans;
+    }
+    constructor(options = {}) {
+        if (options.allowInProduction !== true && process.env.NODE_ENV === "production") {
+            throw new Error("MemoryStore is per-instance and unsafe in production (each instance limits separately). " +
+                "Use a shared store (e.g. Redis), or pass { allowInProduction: true } for a single-instance deploy.");
+        }
+        this.maxKeys = options.maxKeys ?? 100_000;
+        if (!Number.isInteger(this.maxKeys) || this.maxKeys < 1) {
+            throw new Error("MemoryStore: maxKeys must be a positive integer");
+        }
+        this.sweepIntervalMs = options.sweepIntervalMs ?? 30_000;
+        if (!Number.isFinite(this.sweepIntervalMs) || this.sweepIntervalMs < 0) {
+            throw new Error("MemoryStore: sweepIntervalMs must be a non-negative number");
+        }
+    }
+    hit(key, windowMs) {
+        const now = Date.now();
+        // Amortized GC: at most once per sweepIntervalMs, drop every window whose reset has passed. This
+        // bounds memory to ~the active key set instead of leaking an entry per distinct key ever seen.
+        if (now - this.lastSweep >= this.sweepIntervalMs) {
+            this.sweepExpired(now);
+            this.lastSweep = now;
+        }
+        const current = this.windows.get(key);
+        if (current === undefined || now >= current.resetAt) {
+            const fresh = { count: 1, resetAt: now + windowMs };
+            this.windows.set(key, fresh);
+            this.enforceMaxKeys(now);
+            return Promise.resolve({ count: fresh.count, resetAt: fresh.resetAt });
+        }
+        current.count += 1;
+        return Promise.resolve({ count: current.count, resetAt: current.resetAt });
+    }
+    sweepExpired(now) {
+        for (const [k, v] of this.windows)
+            if (now >= v.resetAt)
+                this.windows.delete(k);
+    }
+    enforceMaxKeys(now) {
+        if (this.windows.size <= this.maxKeys)
+            return;
+        // Prefer evicting an expired window over an active user's, but bound the work. A full sweep on
+        // every insertion is O(n)/request under a distinct-key flood — the exact abuse the cap defends
+        // against. Scan only a small fixed budget (oldest-first, where expired entries cluster) for a
+        // victim; if none is found, evict the oldest-inserted (O(1)). Expired entries beyond the budget
+        // are still reclaimed by the amortized sweep in `hit`.
+        while (this.windows.size > this.maxKeys) {
+            let victim;
+            let scanned = 0;
+            for (const [k, v] of this.windows) {
+                this.evictionScans++;
+                if (now >= v.resetAt) {
+                    victim = k;
+                    break;
+                }
+                if (++scanned >= MAX_EVICTION_SCAN)
+                    break;
+            }
+            if (victim === undefined)
+                victim = this.windows.keys().next().value;
+            if (victim === undefined)
+                break;
+            this.windows.delete(victim);
+        }
+    }
+}
+function defaultKey(req, trustedProxies, header, allowGlobalKey) {
+    if (header !== undefined) {
+        const ip = req.headers.get(header);
+        if (ip !== null && ip.trim() !== "")
+            return ip.trim();
+    }
+    if (trustedProxies > 0) {
+        const xff = req.headers.get("x-forwarded-for");
+        if (xff !== null) {
+            const parts = xff.split(",");
+            // The leftmost of the trusted suffix (your proxies append on the right) = the address your edge
+            // proxy observed = the real client. A client can only prepend fakes further left, which this
+            // index skips. A chain shorter than `trustedProxies` (misconfig) → undefined → fall through.
+            const ip = parts[parts.length - trustedProxies]?.trim();
+            if (ip !== undefined && ip !== "")
+                return ip;
+        }
+    }
+    // No trusted proxy (or XFF absent/too-short): XFF isn't trustworthy, so don't derive a per-client key
+    // from it. A shared bucket is only safe when the app deliberately asked for a global throttle.
+    return allowGlobalKey ? "global" : null;
+}
+/**
+ * Rate limiting as a {@link Middleware}. Runs in `onRequest` (before routing, so it
+ * also covers 404s); over the limit → `429` + `Retry-After`. Every response carries
+ * `RateLimit-Limit/Remaining/Reset` (added in `onResponse`, keyed off the request).
+ */
+export function rateLimit(options) {
+    const { store, max, windowMs } = options;
+    if (!Number.isInteger(max) || max < 1)
+        throw new Error("rateLimit: max must be a positive integer");
+    if (!Number.isFinite(windowMs) || windowMs <= 0) {
+        throw new Error("rateLimit: windowMs must be a positive number");
+    }
+    const trustedProxies = options.trustedProxies ?? 0;
+    if (!Number.isInteger(trustedProxies) || trustedProxies < 0) {
+        throw new Error("rateLimit: trustedProxies must be a non-negative integer");
+    }
+    const header = options.header?.trim().toLowerCase();
+    if (header !== undefined && header.trim() === "")
+        throw new Error("rateLimit: header is empty");
+    const allowGlobalKey = options.allowGlobalKey === true;
+    if (options.key === undefined &&
+        header === undefined &&
+        trustedProxies === 0 &&
+        !allowGlobalKey) {
+        throw new Error("rateLimit: configure key, header, or trustedProxies; pass allowGlobalKey: true only for an intentional shared bucket");
+    }
+    const keyOf = options.key ?? ((req) => defaultKey(req, trustedProxies, header, allowGlobalKey));
+    const quota = new WeakMap();
+    return {
+        name: "rate-limit",
+        async onRequest(req) {
+            const key = keyOf(req);
+            if (typeof key !== "string" || key.trim() === "") {
+                return Response.json({ ok: false, error: "rate_limit_key_unavailable" }, { status: 500 });
+            }
+            const { count, resetAt } = await store.hit(key, windowMs);
+            const resetSeconds = Math.max(0, Math.ceil((resetAt - Date.now()) / 1000));
+            quota.set(req, { remaining: Math.max(0, max - count), resetSeconds });
+            if (count > max) {
+                return new Response(JSON.stringify({ ok: false, error: "rate_limited" }), {
+                    status: 429,
+                    headers: { "content-type": "application/json", "retry-after": String(resetSeconds) },
+                });
+            }
+            return undefined;
+        },
+        onResponse(res, req) {
+            const info = quota.get(req);
+            if (info === undefined)
+                return res;
+            quota.delete(req);
+            const headers = new Headers(res.headers);
+            headers.set("RateLimit-Limit", String(max));
+            headers.set("RateLimit-Remaining", String(info.remaining));
+            headers.set("RateLimit-Reset", String(info.resetSeconds));
+            return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+        },
+    };
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"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"}

package/dist/request-id.d.ts

@@ -0,0 +1,18 @@
+export interface RequestIdOptions {
+    /** Header read for an inbound id (trace propagation) + echoed on the response. Default `"x-request-id"`. */
+    readonly header?: string;
+    /** Generate an id when the inbound header is absent. Default `crypto.randomUUID()`. */
+    readonly generate?: () => string;
+}
+/**
+ * A {@link definePlugin} plugin that gives every request a stable id: it reuses an inbound
+ * `x-request-id` (or generates one), exposes it on the handler context as **`c.requestId`** (typed,
+ * threaded by `derive`), and echoes it on the response header. Idempotent — applying it twice is a
+ * no-op.
+ *
+ * ```ts
+ * app.use(requestId())          // c.requestId available downstream; X-Request-Id on responses
+ * ```
+ */
+export declare function requestId(options?: RequestIdOptions): import("@nifrajs/core").NifraPlugin<import("@nifrajs/core").AnyServer, import("@nifrajs/core").Server<any, any>>;
+//# sourceMappingURL=request-id.d.ts.map

package/dist/request-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.d.ts","sourceRoot":"","sources":["../src/request-id.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,4GAA4G;IAC5G,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAA;CACjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,oHAUvD"}

package/dist/request-id.js

@@ -0,0 +1,21 @@
+import { definePlugin } from "@nifrajs/core";
+/**
+ * A {@link definePlugin} plugin that gives every request a stable id: it reuses an inbound
+ * `x-request-id` (or generates one), exposes it on the handler context as **`c.requestId`** (typed,
+ * threaded by `derive`), and echoes it on the response header. Idempotent — applying it twice is a
+ * no-op.
+ *
+ * ```ts
+ * app.use(requestId())          // c.requestId available downstream; X-Request-Id on responses
+ * ```
+ */
+export function requestId(options = {}) {
+    const header = options.header ?? "x-request-id";
+    const generate = options.generate ?? (() => crypto.randomUUID());
+    return definePlugin("requestId", (app) => app.derive((c) => {
+        const id = c.req.headers.get(header) ?? generate();
+        c.set.headers[header] = id; // echo on the response (route handlers)
+        return { requestId: id };
+    }));
+}
+//# sourceMappingURL=request-id.js.map

package/dist/request-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.js","sourceRoot":"","sources":["../src/request-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAS5C;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,UAA4B,EAAE;IACtD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,cAAc,CAAA;IAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAA;IAChE,OAAO,YAAY,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE,CACvC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QACf,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAA;QAClD,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAA,CAAC,wCAAwC;QACnE,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,CAAA;IAC1B,CAAC,CAAC,CACH,CAAA;AACH,CAAC"}

package/dist/security-headers.d.ts

@@ -0,0 +1,23 @@
+import type { Middleware } from "@nifrajs/core";
+export interface SecurityHeadersOptions {
+    /** `Strict-Transport-Security`. Off by default — opt in once you're sure you're HTTPS-only. */
+    readonly hsts?: {
+        readonly maxAge: number;
+        readonly includeSubDomains?: boolean;
+        readonly preload?: boolean;
+    };
+    /** `Content-Security-Policy` value. Off by default (app-specific). */
+    readonly contentSecurityPolicy?: string;
+    /** `X-Frame-Options`. Default `"DENY"`. */
+    readonly frameOptions?: "DENY" | "SAMEORIGIN";
+    /** `Referrer-Policy`. Default `"no-referrer"`. */
+    readonly referrerPolicy?: string;
+}
+/**
+ * A safe-by-default set of response security headers (`onResponse`, so they cover
+ * errors and 404s too): `X-Content-Type-Options: nosniff`, `X-Frame-Options`, and
+ * `Referrer-Policy` always; `Strict-Transport-Security` and `Content-Security-Policy`
+ * only when configured (both are environment-/app-specific).
+ */
+export declare function securityHeaders(options?: SecurityHeadersOptions): Middleware;
+//# sourceMappingURL=security-headers.d.ts.map

package/dist/security-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-headers.d.ts","sourceRoot":"","sources":["../src/security-headers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAG/C,MAAM,WAAW,sBAAsB;IACrC,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,CAAC,EAAE;QACd,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;QACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAC3B,CAAA;IACD,sEAAsE;IACtE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAA;IACvC,2CAA2C;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;IAC7C,kDAAkD;IAClD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,UAAU,CA0BhF"}

package/dist/security-headers.js

@@ -0,0 +1,36 @@
+import { withHeaders } from "./_utils.js";
+/**
+ * A safe-by-default set of response security headers (`onResponse`, so they cover
+ * errors and 404s too): `X-Content-Type-Options: nosniff`, `X-Frame-Options`, and
+ * `Referrer-Policy` always; `Strict-Transport-Security` and `Content-Security-Policy`
+ * only when configured (both are environment-/app-specific).
+ */
+export function securityHeaders(options = {}) {
+    const frameOptions = options.frameOptions ?? "DENY";
+    const referrerPolicy = options.referrerPolicy ?? "no-referrer";
+    const csp = options.contentSecurityPolicy;
+    let hstsValue;
+    if (options.hsts !== undefined) {
+        const parts = [`max-age=${options.hsts.maxAge}`];
+        if (options.hsts.includeSubDomains)
+            parts.push("includeSubDomains");
+        if (options.hsts.preload)
+            parts.push("preload");
+        hstsValue = parts.join("; ");
+    }
+    return {
+        name: "security-headers",
+        // Mutate in place on the common (mutable-headers) response; clone only for an immutable one
+        // (see withHeaders — the old always-clone was ~3% of a realistic request).
+        onResponse: (res) => withHeaders(res, (headers) => {
+            headers.set("X-Content-Type-Options", "nosniff");
+            headers.set("X-Frame-Options", frameOptions);
+            headers.set("Referrer-Policy", referrerPolicy);
+            if (hstsValue !== undefined)
+                headers.set("Strict-Transport-Security", hstsValue);
+            if (csp !== undefined)
+                headers.set("Content-Security-Policy", csp);
+        }),
+    };
+}
+//# sourceMappingURL=security-headers.js.map

package/dist/security-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security-headers.js","sourceRoot":"","sources":["../src/security-headers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAiBzC;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,MAAM,CAAA;IACnD,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,aAAa,CAAA;IAC9D,MAAM,GAAG,GAAG,OAAO,CAAC,qBAAqB,CAAA;IAEzC,IAAI,SAA6B,CAAA;IACjC,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,CAAC,WAAW,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;QAChD,IAAI,OAAO,CAAC,IAAI,CAAC,iBAAiB;YAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAA;QACnE,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QAC/C,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAED,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,4FAA4F;QAC5F,2EAA2E;QAC3E,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE,CAClB,WAAW,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE;YAC3B,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,SAAS,CAAC,CAAA;YAChD,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAA;YAC5C,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,cAAc,CAAC,CAAA;YAC9C,IAAI,SAAS,KAAK,SAAS;gBAAE,OAAO,CAAC,GAAG,CAAC,2BAA2B,EAAE,SAAS,CAAC,CAAA;YAChF,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,CAAC,GAAG,CAAC,yBAAyB,EAAE,GAAG,CAAC,CAAA;QACpE,CAAC,CAAC;KACL,CAAA;AACH,CAAC"}

package/dist/timing.d.ts

@@ -0,0 +1,25 @@
+export interface TimingMetric {
+    readonly name: string;
+    readonly duration: number;
+    readonly description?: string;
+}
+export interface TimingControls {
+    mark(name: string): void;
+    measure(name: string, start: string, end?: string): void;
+    metric(name: string, duration: number, description?: string): void;
+}
+export interface TimingOptions {
+    /** Name for the automatic total request metric. Default `"total"`; set `false` to disable. */
+    readonly total?: string | false;
+    /** Decimal places for durations. Default `1`. */
+    readonly precision?: number;
+    /** Only emit timing for matching requests. Default `true`. */
+    readonly enabled?: boolean | ((request: Request) => boolean);
+}
+/**
+ * Adds a `Server-Timing` response header and typed `c.timing` controls for custom metrics.
+ * Put request-rewriting middleware (for example `methodOverride`) before `timing()` so timing is
+ * attached to the final routed request.
+ */
+export declare function timing(options?: TimingOptions): import("@nifrajs/core").NifraPlugin<import("@nifrajs/core").AnyServer, import("@nifrajs/core").Server<any, any>>;
+//# sourceMappingURL=timing.d.ts.map

package/dist/timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACnE;AAED,MAAM,WAAW,aAAa;IAC5B,8FAA8F;IAC9F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC/B,iDAAiD;IACjD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAA;CAC7D;AAqCD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,oHAoEjD"}

package/dist/timing.js

@@ -0,0 +1,101 @@
+import { definePlugin } from "@nifrajs/core";
+import { withHeaders } from "./_utils.js";
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+function assertMetricName(name) {
+    if (!TOKEN.test(name))
+        throw new Error(`timing: invalid metric name "${name}"`);
+}
+function assertDuration(duration) {
+    if (!Number.isFinite(duration) || duration < 0) {
+        throw new Error("timing: duration must be a finite non-negative number");
+    }
+}
+function quoteDescription(value) {
+    let out = "";
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f)
+            continue;
+        const ch = value[i] ?? "";
+        out += ch === "\\" || ch === '"' ? `\\${ch}` : ch;
+    }
+    return out;
+}
+function formatMetric(metric, precision) {
+    let out = `${metric.name};dur=${metric.duration.toFixed(precision)}`;
+    if (metric.description !== undefined)
+        out += `;desc="${quoteDescription(metric.description)}"`;
+    return out;
+}
+/**
+ * Adds a `Server-Timing` response header and typed `c.timing` controls for custom metrics.
+ * Put request-rewriting middleware (for example `methodOverride`) before `timing()` so timing is
+ * attached to the final routed request.
+ */
+export function timing(options = {}) {
+    const totalName = options.total === undefined ? "total" : options.total;
+    if (totalName !== false)
+        assertMetricName(totalName);
+    const precision = options.precision ?? 1;
+    if (!Number.isInteger(precision) || precision < 0 || precision > 6) {
+        throw new Error("timing: precision must be an integer from 0 to 6");
+    }
+    const enabled = options.enabled ?? true;
+    const isEnabled = typeof enabled === "function" ? enabled : enabled ? () => true : () => false;
+    const states = new WeakMap();
+    const controls = (req) => ({
+        mark(name) {
+            assertMetricName(name);
+            const state = states.get(req);
+            if (state !== undefined)
+                state.marks.set(name, performance.now());
+        },
+        measure(name, start, end) {
+            assertMetricName(name);
+            const state = states.get(req);
+            if (state === undefined)
+                return;
+            const startAt = state.marks.get(start);
+            const endAt = end === undefined ? performance.now() : state.marks.get(end);
+            if (startAt === undefined || endAt === undefined) {
+                throw new Error("timing: unknown mark");
+            }
+            const duration = endAt - startAt;
+            assertDuration(duration);
+            state.metrics.push({ name, duration });
+        },
+        metric(name, duration, description) {
+            assertMetricName(name);
+            assertDuration(duration);
+            const state = states.get(req);
+            if (state !== undefined) {
+                state.metrics.push(description === undefined ? { name, duration } : { name, duration, description });
+            }
+        },
+    });
+    return definePlugin("timing", (app) => app
+        .onRequest((req) => {
+        if (!isEnabled(req))
+            return undefined;
+        states.set(req, { start: performance.now(), marks: new Map(), metrics: [] });
+        return undefined;
+    })
+        .derive((c) => ({ timing: controls(c.req) }))
+        .onResponse((res, req) => {
+        const state = states.get(req);
+        if (state === undefined)
+            return res;
+        states.delete(req);
+        const metrics = totalName === false
+            ? state.metrics
+            : [{ name: totalName, duration: performance.now() - state.start }, ...state.metrics];
+        if (metrics.length === 0)
+            return res;
+        const value = metrics.map((metric) => formatMetric(metric, precision)).join(", ");
+        return withHeaders(res, (headers) => {
+            const existing = headers.get("server-timing");
+            headers.set("server-timing", existing === null ? value : `${existing}, ${value}`);
+        });
+    }));
+}
+//# sourceMappingURL=timing.js.map

package/dist/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"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"}