@erenthedeveloper0/zen-middleware 0.1.0-alpha.1

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * `@erenthedeveloper0/zen-middleware` — the first-party pack (rfcs/0001 §24.2, §25 M4, §32).
+ *
+ * Four plugins, one shape: **a global `onRequest` hook that stages response
+ * metadata**. Both halves of that sentence are load-bearing and both were
+ * decided by measurement rather than by taste — see §32.1 and §32.2, or the
+ * header comment on `cors.ts`, which carries the numbers.
+ *
+ * What is *not* here, named rather than left as a silent gap:
+ *
+ * - **`compression` and `static`.** Both need a platform: `node:zlib` and
+ *   `node:fs`. §14.1 already puts compression on the adapter boundary as a
+ *   capability (`compression: 'native' | 'library' | 'none'`), which is the
+ *   right home for it — a middleware package that imported `node:zlib` would
+ *   be a package the edge adapters cannot load. They belong to an
+ *   adapter-coupled package and are recorded in §28.8.
+ * - **`timeout` and `body-limit`**, which §24.2 lists here. Both are already
+ *   built into core as first-class route policy — §4.4's deadlines and §19.2's
+ *   body limits — and a middleware wrapping them would be a second way to say
+ *   the same thing, with its own precedence rules for the case where both are
+ *   set. §24.2's row predates both features.
+ */
+export { cors } from "./cors.js";
+export { securityHeaders, } from "./security.js";
+export { requestId } from "./request-id.js";
+export { rateLimit, } from "./rate-limit.js";
+export { MemoryStore, ReferenceStore, } from "./store.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,IAAI,EAAuD,MAAM,WAAW,CAAA;AACrF,OAAO,EACL,eAAe,GAChB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,SAAS,EAAyB,MAAM,iBAAiB,CAAA;AAClE,OAAO,EACL,SAAS,GACV,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,WAAW,EAAE,cAAc,GAC5B,MAAM,YAAY,CAAA"}

package/dist/rate-limit.d.ts

@@ -0,0 +1,70 @@
+import { type Duration, type Plugin } from '@erenthedeveloper0/zen-core';
+import { type Store } from './store.ts';
+/**
+ * Rate limiting — rfcs/0001 §9.2, §19.2, §19.4, Annex B `ZEN_RATE_LIMITED`.
+ *
+ * ### Why it is a hook, and why that is the whole feature
+ *
+ * §9.2 states the defect this design exists to avoid, in the paragraph that
+ * made global `onRequest` hooks run on unmatched requests: *"a rate limiter
+ * that only sees matched routes is bypassed by requesting a path that does not
+ * exist."* Every framework whose rate limiter is route middleware has that
+ * hole, and it is not theoretical — `GET /aaaa` is unmatched, so the limiter
+ * never runs, so a 404 flood is free. A global `onRequest` hook counts it.
+ *
+ * §4.2 stage 5 puts it before body intake as well, so a request that is going
+ * to be refused is refused **without its body being read**. A limiter that
+ * counted after parsing would have already paid the expensive part.
+ *
+ * ### `Codes.RATE_LIMITED` was already here
+ *
+ * `TooManyRequests` and `ZEN_RATE_LIMITED` have been exported from
+ * `@erenthedeveloper0/zen-core` since 0.1 and read by nothing — the same state `COERCION_DEFAULTS`
+ * and `Codes.CONFIG_INVALID` were in before the two features that needed them.
+ * Using it rather than inventing a 429 means the refusal is an ordinary
+ * `HttpError`: it goes through the error engine, the RFC 9457 envelope, the
+ * registered `onError` hooks and `onSend`, and it appears in the same error
+ * dashboards as everything else. A rate limiter that answers with its own
+ * hand-built response is one whose refusals no error rate counts.
+ *
+ * ### What it does not do
+ *
+ * It is a **fixed-window counter**, and `store.ts` explains what that costs at
+ * the boundary. It is not distributed unless the `Store` is (§3.5). It does not
+ * read `X-Forwarded-For` — that is `ctx.ip`, and §19.4 makes it a deliberate
+ * `trustProxy` decision — but it *does* notice when the combination is the one
+ * §19.4 warns about, once, at the moment it is provably real. See {@link warnProxy}.
+ */
+export interface RateLimitOptions {
+    /** Requests per window, per key. */
+    readonly limit?: number | undefined;
+    /** Window length. Fixed, not sliding — see `store.ts`. */
+    readonly window?: Duration | undefined;
+    /**
+     * What to count by. Defaults to `ctx.ip`.
+     *
+     * Return `null` to exempt a request entirely — that is how an authenticated
+     * service account or an internal health poller opts out, and it is a
+     * deliberate hole rather than a second allowlist option nobody would find.
+     */
+    readonly key?: ((ctx: RateLimitContext) => string | null) | undefined;
+    /** Where counters live. Defaults to an in-process {@link MemoryStore}. */
+    readonly store?: Store | undefined;
+    /** Also emit `X-RateLimit-*`. Off by default: they were never standardised and they double the header cost. */
+    readonly legacyHeaders?: boolean | undefined;
+    /** Emit `RateLimit` / `RateLimit-Policy` (IETF draft). On by default. */
+    readonly standardHeaders?: boolean | undefined;
+    /** Message on the 429. The status, code and envelope are not configurable. */
+    readonly message?: string | undefined;
+}
+export interface RateLimitContext {
+    readonly ip: string;
+    readonly method: string;
+    readonly path: string;
+    readonly id: string;
+    readonly raw: {
+        header(name: never): string | undefined;
+    };
+}
+export declare function rateLimit(options?: RateLimitOptions): Plugin<void, {}>;
+//# 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,EAEL,KAAK,QAAQ,EAAE,KAAK,MAAM,EAC3B,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAe,KAAK,KAAK,EAAc,MAAM,YAAY,CAAA;AAGhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,gBAAgB,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,SAAS,CAAA;IACrE,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;IAClC,+GAA+G;IAC/G,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC5C,yEAAyE;IACzE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9C,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,GAAG,EAAE;QAAE,MAAM,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAA;CAC1D;AAID,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CA4F1E"}

package/dist/rate-limit.js

@@ -0,0 +1,125 @@
+import { definePlugin, parseDuration, Codes, TooManyRequests, ZenError, } from '@erenthedeveloper0/zen-core';
+import { MemoryStore } from "./store.js";
+const DEFAULTS = { limit: 100, window: '1m' };
+export function rateLimit(options = {}) {
+    return definePlugin({
+        name: 'rate-limit',
+        version: '0.1.0',
+        config: { namespace: 'rateLimit', defaults: { limit: DEFAULTS.limit, window: DEFAULTS.window } },
+        setup(app) {
+            // §16.1 layer order: an explicit option beats the plugin's own layer-2
+            // defaults, which a deployment can beat from configuration. Readable at
+            // setup because §16.2 resolved the environment before any plugin ran.
+            const namespace = (app.config['rateLimit'] ?? {});
+            const limit = options.limit ?? numberOr(namespace.limit, DEFAULTS.limit);
+            const windowMs = parseDuration(options.window ?? namespace.window ?? DEFAULTS.window);
+            if (!Number.isInteger(limit) || limit < 1) {
+                throw new ZenError(Codes.CONFIG_INVALID, `rateLimit needs a positive whole limit; got ${JSON.stringify(limit)}.`, {
+                    status: 500,
+                    expose: false,
+                    hint: 'Pass rateLimit({ limit: 100, window: "1m" }), or set rateLimit.limit in configuration.',
+                    consequence: 'A limit below one refuses every request, including the health probes an orchestrator uses to decide the pod is broken.',
+                });
+            }
+            // Annotated `Store`, not inferred: the inferred union of the supplied
+            // store and `MemoryStore` drops the optional members, so `store.close?.()`
+            // below would stop type-checking the moment the default is in play — for
+            // an interface whose whole point is that the two are interchangeable.
+            const store = options.store ?? new MemoryStore({ windowMs });
+            const keyOf = options.key ?? ((ctx) => ctx.ip);
+            const standard = options.standardHeaders !== false;
+            const legacy = options.legacyHeaders === true;
+            const policy = `${limit};w=${Math.floor(windowMs / 1000)}`;
+            const message = options.message ?? `Rate limit exceeded: ${limit} requests per ${options.window ?? namespace.window ?? DEFAULTS.window}.`;
+            // One warning per process, not per request — §12.7's rule applied to a
+            // runtime condition. See `warnProxy`.
+            let warned = false;
+            app.hook('onRequest', function rateLimit(ctx) {
+                const key = keyOf(ctx);
+                if (key === null)
+                    return undefined;
+                if (!warned && options.key === undefined)
+                    warned = warnProxy(ctx);
+                const tally = store.hit(key, Date.now());
+                // The in-memory store is synchronous and must stay on §8.4's fast path;
+                // a Redis store is a round trip. Branching on the *value* rather than
+                // declaring the hook async is what lets one implementation serve both
+                // without making every app that uses the default await a resolved
+                // promise per request.
+                return isThenable(tally)
+                    ? tally.then((settled) => verdict(ctx, settled))
+                    : verdict(ctx, tally);
+            }, 'rate-limit');
+            app.hook('onClose', async () => { await store.close?.(); });
+            function verdict(ctx, tally) {
+                const remaining = Math.max(0, limit - tally.count);
+                const resetSeconds = Math.max(0, Math.ceil((tally.resetAt - Date.now()) / 1000));
+                // Staged, not stamped: the headers have to be on the 429 *and* on the
+                // 200, and the 429 leaves through the error engine rather than through
+                // this hook's return value. `ctx.res` is downstream of both (§13.6).
+                if (standard) {
+                    ctx.res.header('ratelimit', `limit=${limit}, remaining=${remaining}, reset=${resetSeconds}`);
+                    ctx.res.header('ratelimit-policy', policy);
+                }
+                if (legacy) {
+                    ctx.res.header('x-ratelimit-limit', String(limit));
+                    ctx.res.header('x-ratelimit-remaining', String(remaining));
+                    ctx.res.header('x-ratelimit-reset', String(Math.ceil(tally.resetAt / 1000)));
+                }
+                if (tally.count <= limit)
+                    return undefined;
+                ctx.res.header('retry-after', String(resetSeconds));
+                // Thrown, not returned. A returned `Reply` would leave the error engine,
+                // the problem-details envelope and every registered `onError` hook out
+                // of the one response class an operator most wants counted.
+                throw new TooManyRequests(message, { retryable: true });
+            }
+            return { exports: { limit, windowMs, store } };
+        },
+    });
+}
+/**
+ * §19.4's detection, without the traffic sampling.
+ *
+ * The dangerous combination is: rate limiting keyed on the client IP,
+ * `trustProxy` off, and a proxy in front adding `X-Forwarded-For`. Then
+ * `ctx.ip` is the load balancer for every request, every caller shares one
+ * counter, and the limiter is globally throttling the service instead of
+ * limiting anybody — which looks exactly like the service being slow.
+ *
+ * §19.4 assigns this to `zen doctor` "with traffic samples", and that is the
+ * right home for the general check. But the specific one costs a header read on
+ * the first request that could possibly exhibit it, and it fires only when the
+ * misconfiguration is **already real**: a forwarding header is present and is
+ * being ignored. A boot-time version could not do that — at boot, "trustProxy
+ * is off" is also the correct configuration for a directly-exposed server, so a
+ * warning then would fire on every correct app until people turned it off.
+ *
+ * Returns `true` so the caller latches it: one line per process, naming the fix.
+ */
+function warnProxy(ctx) {
+    const forwarded = ctx.raw.header('x-forwarded-for');
+    if (forwarded === undefined)
+        return false;
+    // `ctx.ip` falls back to the socket address when trustProxy is off (§19.4),
+    // so the two disagreeing *is* the condition — no need to read the option.
+    const claimed = forwarded.split(',')[0]?.trim();
+    if (claimed === undefined || claimed === ctx.ip)
+        return false;
+    console.warn(`[zen] ${Codes.RATE_LIMITED}: rate limiting is keyed on ctx.ip, this request carried ` +
+        `X-Forwarded-For: ${claimed}, and trustProxy is off — so it was counted as ${ctx.ip}. ` +
+        'fix: set trustProxy to the number of proxies in front of the app — trustProxy: 1 for one ' +
+        'load balancer — so ctx.ip is the address your proxy saw; not `true`, which reads the ' +
+        'leftmost entry, and a client that writes its own X-Forwarded-For then gets a fresh budget ' +
+        'per request. Or pass rateLimit({ key }) to count by something you control. ' +
+        'also: until then every caller behind the proxy shares one counter, which throttles the ' +
+        'whole service at the configured limit instead of limiting anyone. Reported once per process.');
+    return true;
+}
+function numberOr(value, fallback) {
+    return typeof value === 'number' ? value : fallback;
+}
+function isThenable(value) {
+    return typeof value?.then === 'function';
+}
+//# 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":"AAAA,OAAO,EACL,YAAY,EAAE,aAAa,EAAE,KAAK,EAAE,eAAe,EAAE,QAAQ,GAE9D,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,WAAW,EAA0B,MAAM,YAAY,CAAA;AAsEhE,MAAM,QAAQ,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAW,CAAA;AAEtD,MAAM,UAAU,SAAS,CAAC,UAA4B,EAAE;IACtD,OAAO,YAAY,CAAW;QAC5B,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,OAAO;QAChB,MAAM,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,EAAE;QAEhG,KAAK,CAAC,GAAG;YACP,uEAAuE;YACvE,wEAAwE;YACxE,sEAAsE;YACtE,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,CAA0C,CAAA;YAC1F,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAA;YACxE,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,MAAM,IAAK,SAAS,CAAC,MAA+B,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAA;YAE/G,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBAC1C,MAAM,IAAI,QAAQ,CAChB,KAAK,CAAC,cAAc,EACpB,+CAA+C,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EACvE;oBACE,MAAM,EAAE,GAAG;oBACX,MAAM,EAAE,KAAK;oBACb,IAAI,EAAE,wFAAwF;oBAC9F,WAAW,EAAE,wHAAwH;iBACtI,CACF,CAAA;YACH,CAAC;YAED,sEAAsE;YACtE,2EAA2E;YAC3E,yEAAyE;YACzE,sEAAsE;YACtE,MAAM,KAAK,GAAU,OAAO,CAAC,KAAK,IAAI,IAAI,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAA;YACnE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,GAAqB,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;YAChE,MAAM,QAAQ,GAAG,OAAO,CAAC,eAAe,KAAK,KAAK,CAAA;YAClD,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,KAAK,IAAI,CAAA;YAC7C,MAAM,MAAM,GAAG,GAAG,KAAK,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAA;YAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,wBAAwB,KAAK,iBAAiB,OAAO,CAAC,MAAM,IAAI,SAAS,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAA;YAEzI,uEAAuE;YACvE,sCAAsC;YACtC,IAAI,MAAM,GAAG,KAAK,CAAA;YAElB,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,SAAS,CACtC,GAAwD;gBAExD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;gBACtB,IAAI,GAAG,KAAK,IAAI;oBAAE,OAAO,SAAS,CAAA;gBAElC,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS;oBAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAA;gBAEjE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;gBACxC,wEAAwE;gBACxE,sEAAsE;gBACtE,sEAAsE;gBACtE,kEAAkE;gBAClE,uBAAuB;gBACvB,OAAO,UAAU,CAAC,KAAK,CAAC;oBACtB,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;oBAChD,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YACzB,CAAC,EAAE,YAAY,CAAC,CAAA;YAEhB,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,EAAE,CAAA,CAAC,CAAC,CAAC,CAAA;YAE1D,SAAS,OAAO,CAAC,GAAwB,EAAE,KAAY;gBACrD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAA;gBAClD,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAA;gBAEhF,sEAAsE;gBACtE,uEAAuE;gBACvE,qEAAqE;gBACrE,IAAI,QAAQ,EAAE,CAAC;oBACb,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,KAAK,eAAe,SAAS,WAAW,YAAY,EAAE,CAAC,CAAA;oBAC5F,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAA;gBAC5C,CAAC;gBACD,IAAI,MAAM,EAAE,CAAC;oBACX,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;oBAClD,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAA;oBAC1D,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;gBAC9E,CAAC;gBAED,IAAI,KAAK,CAAC,KAAK,IAAI,KAAK;oBAAE,OAAO,SAAS,CAAA;gBAE1C,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC,CAAA;gBACnD,yEAAyE;gBACzE,uEAAuE;gBACvE,4DAA4D;gBAC5D,MAAM,IAAI,eAAe,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YACzD,CAAC;YAED,OAAO,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAA;QAChD,CAAC;KACF,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAS,SAAS,CAAC,GAAkC;IACnD,MAAM,SAAS,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAA;IACnD,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IACzC,4EAA4E;IAC5E,0EAA0E;IAC1E,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAA;IAC/C,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,GAAG,CAAC,EAAE;QAAE,OAAO,KAAK,CAAA;IAE7D,OAAO,CAAC,IAAI,CACV,SAAS,KAAK,CAAC,YAAY,2DAA2D;QACpF,oBAAoB,OAAO,kDAAkD,GAAG,CAAC,EAAE,IAAI;QACvF,2FAA2F;QAC3F,uFAAuF;QACvF,4FAA4F;QAC5F,6EAA6E;QAC7E,yFAAyF;QACzF,8FAA8F,CACjG,CAAA;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc,EAAE,QAAgB;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAA;AACrD,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,OAAQ,KAAmC,EAAE,IAAI,KAAK,UAAU,CAAA;AACzE,CAAC"}

package/dist/request-id.d.ts

@@ -0,0 +1,17 @@
+import { type Plugin } from '@erenthedeveloper0/zen-core';
+export interface RequestIdOptions {
+    /** Header to echo on the reply. `false` echoes nothing. */
+    readonly header?: string | false | undefined;
+    /**
+     * Adopt an inbound id when it is well-formed. Off by default — see above.
+     *
+     * `true` reads the same header as `header`. A string reads that one instead,
+     * which is what a deployment behind a load balancer that stamps its own
+     * (`x-amzn-trace-id`, `x-cloud-trace-context`) needs.
+     */
+    readonly trustHeader?: boolean | string | undefined;
+    /** Header carrying the rejection notice. `false` stays silent. */
+    readonly rejectedHeader?: string | false | undefined;
+}
+export declare function requestId(options?: RequestIdOptions): Plugin<void, {}>;
+//# 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":"AAAA,OAAO,EAAiC,KAAK,MAAM,EAAE,MAAM,6BAA6B,CAAA;AAwDxF,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAA;IACnD,kEAAkE;IAClE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;CACrD;AAaD,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CA8C1E"}

package/dist/request-id.js

@@ -0,0 +1,53 @@
+import { definePlugin, Codes, ZenError } from '@erenthedeveloper0/zen-core';
+/**
+ * 8–128 of `[A-Za-z0-9._-]`.
+ *
+ * Anchored, no alternation, no nested quantifier: linear in the input and
+ * therefore inside §19.3's bounded-work rule, which forbids backtracking
+ * regexes anywhere on the request path. The upper bound is part of the
+ * validation, not a courtesy — an id is copied into every log line for the
+ * request, so an unbounded one is an amplification the caller chooses.
+ */
+const ACCEPTABLE = /^[A-Za-z0-9._-]{8,128}$/;
+export function requestId(options = {}) {
+    const echo = options.header === undefined ? 'x-request-id' : options.header;
+    const trust = options.trustHeader === undefined || options.trustHeader === false ? null
+        : options.trustHeader === true
+            ? (echo === false ? 'x-request-id' : echo)
+            : options.trustHeader;
+    const rejected = options.rejectedHeader === undefined ? 'x-request-id-rejected' : options.rejectedHeader;
+    if (echo === false && trust === null) {
+        throw new ZenError(Codes.CONFIG_INVALID, 'requestId() was configured to neither echo an id nor adopt one, which leaves it with nothing to do.', {
+            status: 500,
+            expose: false,
+            hint: 'Drop the registration — Zen assigns ctx.id with or without this plugin — or turn one of the two back on.',
+            consequence: 'As configured it registers a hook on every route that returns immediately.',
+        });
+    }
+    return definePlugin({
+        name: 'request-id',
+        version: '0.1.0',
+        // First in the pack: a preflight answered by `cors` and a 429 refused by
+        // `rate-limit` both short-circuit, and both should still carry the id that
+        // the log line for them will be filed under.
+        before: ['cors', 'rate-limit', 'security-headers'],
+        setup(app) {
+            app.hook('onRequest', function requestId(ctx) {
+                if (trust !== null) {
+                    const inbound = ctx.raw.header(trust);
+                    if (inbound !== undefined) {
+                        if (ACCEPTABLE.test(inbound))
+                            ctx.id = inbound;
+                        else if (rejected !== false)
+                            ctx.res.header(rejected, '1');
+                    }
+                }
+                if (echo !== false)
+                    ctx.res.header(echo, ctx.id);
+                return undefined;
+            }, 'request-id');
+            return { exports: { header: echo, trusts: trust } };
+        },
+    });
+}
+//# 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,KAAK,EAAE,QAAQ,EAAe,MAAM,6BAA6B,CAAA;AAuExF;;;;;;;;GAQG;AACH,MAAM,UAAU,GAAG,yBAAyB,CAAA;AAE5C,MAAM,UAAU,SAAS,CAAC,UAA4B,EAAE;IACtD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAA;IAC3E,MAAM,KAAK,GACT,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,OAAO,CAAC,WAAW,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI;QACzE,CAAC,CAAC,OAAO,CAAC,WAAW,KAAK,IAAI;YAC5B,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;YAC1C,CAAC,CAAC,OAAO,CAAC,WAAW,CAAA;IACzB,MAAM,QAAQ,GAAG,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,CAAA;IAExG,IAAI,IAAI,KAAK,KAAK,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACrC,MAAM,IAAI,QAAQ,CAChB,KAAK,CAAC,cAAc,EACpB,qGAAqG,EACrG;YACE,MAAM,EAAE,GAAG;YACX,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,0GAA0G;YAChH,WAAW,EAAE,4EAA4E;SAC1F,CACF,CAAA;IACH,CAAC;IAED,OAAO,YAAY,CAAW;QAC5B,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,OAAO;QAChB,yEAAyE;QACzE,2EAA2E;QAC3E,6CAA6C;QAC7C,MAAM,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,kBAAkB,CAAC;QAElD,KAAK,CAAC,GAAG;YACP,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,SAAS,CAAC,GAAqC;gBAC5E,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;oBACnB,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;oBACrC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;wBAC1B,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;4BAAE,GAAG,CAAC,EAAE,GAAG,OAAO,CAAA;6BACzC,IAAI,QAAQ,KAAK,KAAK;4BAAE,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;oBAC5D,CAAC;gBACH,CAAC;gBACD,IAAI,IAAI,KAAK,KAAK;oBAAE,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;gBAChD,OAAO,SAAS,CAAA;YAClB,CAAC,EAAE,YAAY,CAAC,CAAA;YAEhB,OAAO,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAA;QACrD,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/security.d.ts

@@ -0,0 +1,80 @@
+import { type Plugin } from '@erenthedeveloper0/zen-core';
+/**
+ * Security response headers — rfcs/0001 §19.2.
+ *
+ * The header set is §19.2's table, and the table is the specification: every
+ * default here appears there with the sentence explaining why it is not looser.
+ * Nothing is invented in this file.
+ *
+ * ### Staged, so failures carry them too
+ *
+ * Same reason as `cors.ts`: an `after` middleware never runs on the error path
+ * (§4.6) or on an unmatched request, so a service that stamps `nosniff` in
+ * middleware does not have it on its 404s, its 500s or its validation errors —
+ * which are precisely the responses most likely to contain reflected input.
+ * `ctx.res` stages, and `prepareForWire` applies at egress on every path.
+ *
+ * ### It runs first, and that is a correctness requirement
+ *
+ * Staging is only half the answer. `cors` answers a preflight by returning a
+ * `Reply`, and `rate-limit` refuses by throwing — both short-circuit the
+ * `onRequest` chain, so a hook registered after them does not run at all on the
+ * responses that need it most. The first draft of this pack ordered
+ * `securityHeaders` last and every preflight and every 429 went out without
+ * `nosniff`; the manual end-to-end check found it before any test did, which is
+ * convention #2 again. Hence `before:` on all three siblings.
+ *
+ * ### The contradiction it can catch that a library cannot
+ *
+ * See `consistency.ts`. Both this plugin and `cors` call the same check with
+ * whatever the other has published, so whichever is registered second finds
+ * both halves — the ordering above means that is normally `cors`.
+ */
+export type ReferrerPolicy = 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url';
+export interface SecurityHeadersOptions {
+    /** `X-Content-Type-Options: nosniff`. Off is not a supported configuration; the flag exists for tests. */
+    readonly noSniff?: boolean | undefined;
+    /** `X-Frame-Options`. `false` omits it — do that only when a CSP `frame-ancestors` replaces it. */
+    readonly frameOptions?: 'DENY' | 'SAMEORIGIN' | false | undefined;
+    readonly referrerPolicy?: ReferrerPolicy | false | undefined;
+    /** `Cross-Origin-Opener-Policy`. */
+    readonly crossOriginOpener?: 'same-origin' | 'same-origin-allow-popups' | 'unsafe-none' | false | undefined;
+    /**
+     * `Cross-Origin-Resource-Policy`. Defaults to `same-site` rather than
+     * `same-origin`: `same-origin` is the stricter reading of §19.2's
+     * "conservative", and it is also the value that silently breaks a CDN
+     * subdomain serving the same site's assets. `same-site` blocks the
+     * cross-*site* read that CORP exists to prevent and leaves the arrangement
+     * every real deployment has intact.
+     */
+    readonly crossOriginResource?: 'same-origin' | 'same-site' | 'cross-origin' | false | undefined;
+    /**
+     * `Strict-Transport-Security`. **Off by default**, and this is the one
+     * default in the table that looks wrong until you have been bitten by it.
+     *
+     * §19.2 says "HSTS on when `secure: true`". A framework cannot tell whether
+     * it is behind TLS — `ctx.secure` reads `X-Forwarded-Proto`, which §19.4
+     * refuses to trust unless `trustProxy` is configured — so "on when secure"
+     * resolves to "on when a header we do not trust says so". And HSTS is not a
+     * header you can take back: a browser that has seen `max-age=31536000`
+     * refuses plain HTTP to that host for a year, including on the developer's
+     * own machine if it ever reached one. So it is opt-in, one line, in the file
+     * that already knows it is behind a load balancer.
+     */
+    readonly hsts?: {
+        readonly maxAge?: number;
+        readonly includeSubDomains?: boolean;
+        readonly preload?: boolean;
+    } | false | undefined;
+    /**
+     * `Content-Security-Policy`, verbatim. **Not set by default** — §19.2: "a
+     * wrong CSP is worse than none; we prompt instead of guessing." There is no
+     * builder here for the same reason: a policy assembled from options reads as
+     * if the framework vouched for it.
+     */
+    readonly contentSecurityPolicy?: string | false | undefined;
+    /** Extra headers, staged with the rest. */
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+}
+export declare function securityHeaders(options?: SecurityHeadersOptions): Plugin<void, {}>;
+//# sourceMappingURL=security.d.ts.map

package/dist/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,6BAA6B,CAAA;AAKvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,4BAA4B,GAC5B,QAAQ,GACR,0BAA0B,GAC1B,aAAa,GACb,eAAe,GACf,iCAAiC,GACjC,YAAY,CAAA;AAEhB,MAAM,WAAW,sBAAsB;IACrC,0GAA0G;IAC1G,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACtC,mGAAmG;IACnG,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,KAAK,GAAG,SAAS,CAAA;IACjE,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,KAAK,GAAG,SAAS,CAAA;IAC5D,oCAAoC;IACpC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,aAAa,GAAG,0BAA0B,GAAG,aAAa,GAAG,KAAK,GAAG,SAAS,CAAA;IAC3G;;;;;;;OAOG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,aAAa,GAAG,WAAW,GAAG,cAAc,GAAG,KAAK,GAAG,SAAS,CAAA;IAC/F;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,KAAK,GAAG,SAAS,CAAA;IAClI;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IAC3D,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAA;CAChE;AAKD,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CA8BtF"}

package/dist/security.js

@@ -0,0 +1,65 @@
+import { definePlugin } from '@erenthedeveloper0/zen-core';
+import { assertCorsCorpConsistent } from "./consistency.js";
+export function securityHeaders(options = {}) {
+    return definePlugin({
+        name: 'security-headers',
+        version: '0.1.0',
+        // Before everything that can short-circuit. `cors` answers preflights and
+        // `rate-limit` throws 429s; a hook that runs after either is absent from
+        // exactly the responses §19.2 most wants these headers on. Hints on
+        // unregistered plugins are ignored (§10.5 step 4), so this costs nothing
+        // when the siblings are not installed.
+        before: ['cors', 'rate-limit'],
+        config: { namespace: 'security' },
+        setup(app) {
+            const pairs = resolve(options);
+            const corp = options.crossOriginResource ?? 'same-site';
+            assertCorsCorpConsistent(corp, app.exportsOf('cors'), app.pluginName);
+            // Unrolled at boot into a fixed array; the hook is one loop over a frozen
+            // list of string pairs, with no option reads and no branches per request.
+            app.hook('onRequest', function securityHeaders(ctx) {
+                for (let i = 0; i < pairs.length; i++) {
+                    const pair = pairs[i];
+                    ctx.res.header(pair[0], pair[1]);
+                }
+                return undefined;
+            }, 'security-headers');
+            return { exports: { headers: pairs.map(([name]) => name), crossOriginResource: corp } };
+        },
+    });
+}
+function resolve(options) {
+    const out = [];
+    if (options.noSniff !== false)
+        out.push(['x-content-type-options', 'nosniff']);
+    const frame = options.frameOptions ?? 'DENY';
+    if (frame !== false)
+        out.push(['x-frame-options', frame]);
+    const referrer = options.referrerPolicy ?? 'no-referrer';
+    if (referrer !== false)
+        out.push(['referrer-policy', referrer]);
+    const coop = options.crossOriginOpener ?? 'same-origin';
+    if (coop !== false)
+        out.push(['cross-origin-opener-policy', coop]);
+    const corp = options.crossOriginResource ?? 'same-site';
+    if (corp !== false)
+        out.push(['cross-origin-resource-policy', corp]);
+    const hsts = options.hsts;
+    if (hsts !== undefined && hsts !== false) {
+        const maxAge = hsts.maxAge ?? 15_552_000; // 180 days
+        out.push([
+            'strict-transport-security',
+            `max-age=${maxAge}` +
+                (hsts.includeSubDomains === true ? '; includeSubDomains' : '') +
+                (hsts.preload === true ? '; preload' : ''),
+        ]);
+    }
+    const csp = options.contentSecurityPolicy;
+    if (typeof csp === 'string' && csp.length > 0)
+        out.push(['content-security-policy', csp]);
+    for (const [name, value] of Object.entries(options.headers ?? {})) {
+        out.push([name.toLowerCase(), value]);
+    }
+    return Object.freeze(out);
+}
+//# sourceMappingURL=security.js.map

package/dist/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAe,MAAM,6BAA6B,CAAA;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AA2F3D,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,OAAO,YAAY,CAAW;QAC5B,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,OAAO;QAChB,0EAA0E;QAC1E,yEAAyE;QACzE,oEAAoE;QACpE,yEAAyE;QACzE,uCAAuC;QACvC,MAAM,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC;QAC9B,MAAM,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE;QAEjC,KAAK,CAAC,GAAG;YACP,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;YAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,mBAAmB,IAAI,WAAW,CAAA;YACvD,wBAAwB,CAAC,IAAI,EAAE,GAAG,CAAC,SAAS,CAAC,MAAM,CAA4B,EAAE,GAAG,CAAC,UAAU,CAAC,CAAA;YAEhG,0EAA0E;YAC1E,0EAA0E;YAC1E,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,SAAS,eAAe,CAAC,GAAY;gBACzD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;oBACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAS,CAAA;oBAC7B,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;gBAClC,CAAC;gBACD,OAAO,SAAS,CAAA;YAClB,CAAC,EAAE,kBAAkB,CAAC,CAAA;YAEtB,OAAO,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,mBAAmB,EAAE,IAAI,EAAE,EAAE,CAAA;QACzF,CAAC;KACF,CAAC,CAAA;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,OAA+B;IAC9C,MAAM,GAAG,GAAW,EAAE,CAAA;IAEtB,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK;QAAE,GAAG,CAAC,IAAI,CAAC,CAAC,wBAAwB,EAAE,SAAS,CAAC,CAAC,CAAA;IAE9E,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,IAAI,MAAM,CAAA;IAC5C,IAAI,KAAK,KAAK,KAAK;QAAE,GAAG,CAAC,IAAI,CAAC,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC,CAAA;IAEzD,MAAM,QAAQ,GAAG,OAAO,CAAC,cAAc,IAAI,aAAa,CAAA;IACxD,IAAI,QAAQ,KAAK,KAAK;QAAE,GAAG,CAAC,IAAI,CAAC,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAC,CAAA;IAE/D,MAAM,IAAI,GAAG,OAAO,CAAC,iBAAiB,IAAI,aAAa,CAAA;IACvD,IAAI,IAAI,KAAK,KAAK;QAAE,GAAG,CAAC,IAAI,CAAC,CAAC,4BAA4B,EAAE,IAAI,CAAC,CAAC,CAAA;IAElE,MAAM,IAAI,GAAG,OAAO,CAAC,mBAAmB,IAAI,WAAW,CAAA;IACvD,IAAI,IAAI,KAAK,KAAK;QAAE,GAAG,CAAC,IAAI,CAAC,CAAC,8BAA8B,EAAE,IAAI,CAAC,CAAC,CAAA;IAEpE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAA;IACzB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,UAAU,CAAA,CAAC,WAAW;QACpD,GAAG,CAAC,IAAI,CAAC;YACP,2BAA2B;YAC3B,WAAW,MAAM,EAAE;gBACjB,CAAC,IAAI,CAAC,iBAAiB,KAAK,IAAI,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9D,CAAC,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7C,CAAC,CAAA;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,CAAC,qBAAqB,CAAA;IACzC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,CAAC,yBAAyB,EAAE,GAAG,CAAC,CAAC,CAAA;IAEzF,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;QAClE,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC,CAAA;IACvC,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;AAC3B,CAAC"}

package/dist/shared.d.ts

@@ -0,0 +1,55 @@
+import type { ReplyBuilder, Reply, LowercaseName } from '@erenthedeveloper0/zen-core';
+/**
+ * What this pack touches on a context, declared structurally — §10.4.
+ *
+ * `Registrar.hook` takes a `Function` on purpose: a plugin is written before
+ * the application's decoration set exists, so pinning its hooks to
+ * `Context<never, X>` would reject the pattern for an `X` the author cannot
+ * know. The convention the examples already follow is to declare exactly the
+ * surface the hook uses (`examples/openapi/src/plugins/request-id.ts` declares
+ * `{ id: string }` and nothing else), and the point of doing it is that a
+ * middleware cannot quietly start depending on `ctx.user` later.
+ *
+ * These are split by concern rather than merged into one context type for the
+ * same reason: `securityHeaders` may not read the request, and the type says so.
+ */
+/** Reading the request without materialising the header record. */
+export interface RawReading {
+    readonly method: string;
+    readonly raw: {
+        header(name: LowercaseName): string | undefined;
+    };
+}
+/** Staging response metadata (§13.6) — applied at egress on every path. */
+export interface Staging {
+    readonly res: ReplyBuilder;
+}
+/** Producing a reply from a hook, which is how a phase short-circuits (§9.2). */
+export interface Answering {
+    empty(status?: 204 | 205 | 304): Reply<null>;
+    json<T>(body: T, init?: {
+        status?: number;
+    }): Reply<T>;
+}
+export type CorsRequest = RawReading & Answering;
+/**
+ * `ctx.raw.header` rather than `ctx.headers[name]`.
+ *
+ * `ctx.headers` is lazy and memoised, but the first touch walks every header
+ * the adapter received and builds a record (`buildHeaders`, §7.2). These hooks
+ * run on *every* request in the application, including the ones whose handlers
+ * never look at a header, so making them the reason that record exists would be
+ * a cost the application did not ask for — §9.4's rule applied to a plugin
+ * rather than to the compiler.
+ */
+export declare function headerOf(ctx: RawReading, name: LowercaseName): string | undefined;
+/**
+ * A CORS preflight — an `OPTIONS` carrying `Access-Control-Request-Method`.
+ *
+ * Both halves are required by the Fetch standard and both are load-bearing
+ * here: an `OPTIONS` without the header is an ordinary request for a resource's
+ * options and may well have a route, and answering it with 204 would shadow
+ * that route with something the application did not write.
+ */
+export declare function isPreflight(ctx: RawReading): boolean;
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAErF;;;;;;;;;;;;;GAaG;AAEH,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE;QAAE,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAA;CAClE;AAED,2EAA2E;AAC3E,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAA;CAC3B;AAED,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAA;IAC5C,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;CACvD;AAED,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,CAAA;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAEjF;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAEpD"}

package/dist/shared.js

@@ -0,0 +1,25 @@
+/**
+ * `ctx.raw.header` rather than `ctx.headers[name]`.
+ *
+ * `ctx.headers` is lazy and memoised, but the first touch walks every header
+ * the adapter received and builds a record (`buildHeaders`, §7.2). These hooks
+ * run on *every* request in the application, including the ones whose handlers
+ * never look at a header, so making them the reason that record exists would be
+ * a cost the application did not ask for — §9.4's rule applied to a plugin
+ * rather than to the compiler.
+ */
+export function headerOf(ctx, name) {
+    return ctx.raw.header(name);
+}
+/**
+ * A CORS preflight — an `OPTIONS` carrying `Access-Control-Request-Method`.
+ *
+ * Both halves are required by the Fetch standard and both are load-bearing
+ * here: an `OPTIONS` without the header is an ordinary request for a resource's
+ * options and may well have a route, and answering it with 204 would shadow
+ * that route with something the application did not write.
+ */
+export function isPreflight(ctx) {
+    return ctx.method === 'OPTIONS' && ctx.raw.header('access-control-request-method') !== undefined;
+}
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAoCA;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAe,EAAE,IAAmB;IAC3D,OAAO,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,GAAe;IACzC,OAAO,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,+BAA+B,CAAC,KAAK,SAAS,CAAA;AAClG,CAAC"}