@daloyjs/core 0.17.0 → 0.29.0

package/dist/conn-info.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Adapter-independent connection info abstraction (Wave 6).
+ *
+ * Provides a single typed surface for "where did this request come from" so
+ * the rate limiter, `ipRestriction`, request-id propagation, audit log, and
+ * TLS-enforcement code paths read from one source of truth instead of poking
+ * at adapter-specific shapes or trusting raw `X-Forwarded-*` echoes by
+ * mistake.
+ *
+ * Adapters call {@link setConnInfo} before dispatching the request; consumers
+ * call {@link getConnInfo} or use the {@link App}'s `behindProxy` policy via
+ * {@link resolveClientIp}.
+ *
+ * `info.remote` is populated lazily — adapters may stash a thunk (`() =>
+ * string`) instead of an eager string so the IP is never enumerated into a
+ * plain object that a careless `JSON.stringify(ctx.info)` could leak. This is
+ * Wave 6 item 7 ("data-minimization leak").
+ *
+ * @since 0.24.0
+ */
+import type { BaseContext } from "./types.js";
+/**
+ * Declarative reverse-proxy posture (Wave 6 item 1). Replaces the
+ * foot-gunny `trustProxy: boolean` with a structured value that
+ * simultaneously configures rate-limit keying, TLS enforcement, request-IP
+ * resolution, and the `X-Forwarded-*` accept policy from a single source of
+ * truth.
+ *
+ * - `"none"` — refuse `X-Forwarded-*` entirely. Use when the app is exposed
+ *   directly to the public internet on purpose.
+ * - `"loopback"` — trust `X-Forwarded-*` only when the immediate peer is
+ *   `127.0.0.1` / `::1`. Convenient default for local development behind a
+ *   reverse-proxy on the same host.
+ * - `{ hops: N }` — trust the proxy chain when exactly N hops sit between
+ *   Daloy and the public internet. Reads the (N+1)-from-rightmost IP from
+ *   `X-Forwarded-For`. Refuses spoofed extra hops at the left of the
+ *   header.
+ * - `{ cidrs: [...] }` — trust `X-Forwarded-*` only when the immediate
+ *   peer address falls inside one of the supplied CIDR ranges (IPv4 or
+ *   IPv6 acceptable).
+ *
+ * @since 0.24.0
+ */
+export type BehindProxyConfig = "none" | "loopback" | {
+    readonly hops: number;
+} | {
+    readonly cidrs: readonly string[];
+};
+/**
+ * Per-request connection metadata. Populated lazily — never enumerate
+ * `getConnInfo(req)` into a plain object; read the specific field you need.
+ *
+ * @since 0.24.0
+ */
+export interface ConnInfo {
+    /** Immediate peer address (the TCP socket talking to the adapter). */
+    readonly remoteAddress?: string;
+    /** Immediate peer port. */
+    readonly remotePort?: number;
+    /** Whether the adapter served this request over TLS. */
+    readonly tls?: boolean;
+}
+interface MutableConnInfo {
+    remoteAddress?: string;
+    remotePort?: number;
+    tls?: boolean;
+}
+/**
+ * @internal Adapter helper — attach {@link ConnInfo} to a `Request`. Called
+ * by the Node / Bun / Deno / Cloudflare / Vercel / Lambda adapters before
+ * `app.fetch(request)`.
+ */
+export declare function setConnInfo(request: Request, info: ConnInfo): void;
+/**
+ * Read the {@link ConnInfo} the adapter attached to this request, or
+ * `undefined` when the adapter does not expose connection metadata (e.g.
+ * Cloudflare Workers without `cf` enabled).
+ *
+ * @since 0.24.0
+ */
+export declare function getConnInfo(request: Request): ConnInfo | undefined;
+/**
+ * Refuses-at-construction on malformed {@link BehindProxyConfig}. Called once
+ * during `new App({ behindProxy })`.
+ *
+ * @since 0.24.0
+ */
+export declare function assertBehindProxy(cfg: BehindProxyConfig | undefined): void;
+/**
+ * Read the (N+1)-from-rightmost IP from `X-Forwarded-For`. Wave 6 item 11
+ * ("`behindProxy` collapses `maxIpsCount`") — when the proxy chain is
+ * declared with `{ hops: N }`, only that exact slot is honoured. Returns
+ * `undefined` when the header is shorter than the configured hop count
+ * (caller falls back to the immediate peer).
+ *
+ * @internal
+ */
+export declare function pickForwardedForByHops(header: string | null, hops: number): string | undefined;
+/**
+ * Resolve the client IP for this request using the configured
+ * {@link BehindProxyConfig}. Returns `undefined` when no trusted source is
+ * available (the caller — rate-limit, ipRestriction, audit-log — must fail
+ * closed rather than guess).
+ *
+ * @since 0.24.0
+ */
+export declare function resolveClientIp(request: Request, cfg: BehindProxyConfig | undefined): string | undefined;
+/**
+ * Lazy accessors for `ctx.remoteAddress` / `ctx.remotePort`. Returns
+ * `undefined` rather than allocating a plain object so the IP cannot be
+ * serialized into logs by accident.
+ *
+ * @since 0.24.0
+ */
+export declare function readRemoteAddress(ctx: BaseContext<any, any>): string | undefined;
+/** @since 0.24.0 */
+export declare function readRemotePort(ctx: BaseContext<any, any>): number | undefined;
+/** @internal Test-only helper. */
+export declare function _makeConnInfoForTests(info: ConnInfo): MutableConnInfo;
+export {};
+//# sourceMappingURL=conn-info.d.ts.map

package/dist/conn-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conn-info.d.ts","sourceRoot":"","sources":["../src/conn-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,UAAU,GACV;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,2BAA2B;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,UAAU,eAAe;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAID;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAElE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAIlE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CA2B1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAUpB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,iBAAiB,GAAG,SAAS,GACjC,MAAM,GAAG,SAAS,CAsBpB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,SAAS,CAEhF;AAED,oBAAoB;AACpB,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,SAAS,CAE7E;AAED,kCAAkC;AAClC,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,eAAe,CAErE"}

package/dist/conn-info.js

@@ -0,0 +1,145 @@
+/**
+ * Adapter-independent connection info abstraction (Wave 6).
+ *
+ * Provides a single typed surface for "where did this request come from" so
+ * the rate limiter, `ipRestriction`, request-id propagation, audit log, and
+ * TLS-enforcement code paths read from one source of truth instead of poking
+ * at adapter-specific shapes or trusting raw `X-Forwarded-*` echoes by
+ * mistake.
+ *
+ * Adapters call {@link setConnInfo} before dispatching the request; consumers
+ * call {@link getConnInfo} or use the {@link App}'s `behindProxy` policy via
+ * {@link resolveClientIp}.
+ *
+ * `info.remote` is populated lazily — adapters may stash a thunk (`() =>
+ * string`) instead of an eager string so the IP is never enumerated into a
+ * plain object that a careless `JSON.stringify(ctx.info)` could leak. This is
+ * Wave 6 item 7 ("data-minimization leak").
+ *
+ * @since 0.24.0
+ */
+const CONN_INFO_SYMBOL = Symbol.for("daloyjs.connInfo");
+/**
+ * @internal Adapter helper — attach {@link ConnInfo} to a `Request`. Called
+ * by the Node / Bun / Deno / Cloudflare / Vercel / Lambda adapters before
+ * `app.fetch(request)`.
+ */
+export function setConnInfo(request, info) {
+    request[CONN_INFO_SYMBOL] = info;
+}
+/**
+ * Read the {@link ConnInfo} the adapter attached to this request, or
+ * `undefined` when the adapter does not expose connection metadata (e.g.
+ * Cloudflare Workers without `cf` enabled).
+ *
+ * @since 0.24.0
+ */
+export function getConnInfo(request) {
+    return request[CONN_INFO_SYMBOL];
+}
+/**
+ * Refuses-at-construction on malformed {@link BehindProxyConfig}. Called once
+ * during `new App({ behindProxy })`.
+ *
+ * @since 0.24.0
+ */
+export function assertBehindProxy(cfg) {
+    if (cfg === undefined)
+        return;
+    if (cfg === "none" || cfg === "loopback")
+        return;
+    if (typeof cfg === "object" && cfg !== null) {
+        if ("hops" in cfg) {
+            if (!Number.isInteger(cfg.hops) || cfg.hops < 0 || cfg.hops > 64) {
+                throw new Error(`behindProxy.hops must be an integer in [0, 64]; got ${String(cfg.hops)}.`);
+            }
+            return;
+        }
+        if ("cidrs" in cfg) {
+            if (!Array.isArray(cfg.cidrs) || cfg.cidrs.length === 0) {
+                throw new Error("behindProxy.cidrs must be a non-empty string array.");
+            }
+            for (const c of cfg.cidrs) {
+                if (typeof c !== "string" || c.length === 0) {
+                    throw new Error("behindProxy.cidrs entries must be non-empty strings.");
+                }
+            }
+            return;
+        }
+    }
+    throw new Error(`behindProxy must be "none" | "loopback" | { hops } | { cidrs }; got ${typeof cfg}.`);
+}
+/**
+ * Read the (N+1)-from-rightmost IP from `X-Forwarded-For`. Wave 6 item 11
+ * ("`behindProxy` collapses `maxIpsCount`") — when the proxy chain is
+ * declared with `{ hops: N }`, only that exact slot is honoured. Returns
+ * `undefined` when the header is shorter than the configured hop count
+ * (caller falls back to the immediate peer).
+ *
+ * @internal
+ */
+export function pickForwardedForByHops(header, hops) {
+    if (!header || hops < 1)
+        return undefined;
+    const parts = header
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+    if (parts.length < hops)
+        return undefined;
+    // Right-to-left: index 0 is the last hop closest to Daloy. The client
+    // typically lives at parts[parts.length - hops].
+    return parts[parts.length - hops];
+}
+/**
+ * Resolve the client IP for this request using the configured
+ * {@link BehindProxyConfig}. Returns `undefined` when no trusted source is
+ * available (the caller — rate-limit, ipRestriction, audit-log — must fail
+ * closed rather than guess).
+ *
+ * @since 0.24.0
+ */
+export function resolveClientIp(request, cfg) {
+    const conn = getConnInfo(request);
+    const peer = conn?.remoteAddress;
+    if (cfg === undefined || cfg === "none")
+        return peer;
+    if (cfg === "loopback") {
+        if (peer === "127.0.0.1" || peer === "::1" || peer === "::ffff:127.0.0.1") {
+            const xff = request.headers.get("x-forwarded-for");
+            const first = xff?.split(",")[0]?.trim();
+            if (first)
+                return first;
+        }
+        return peer;
+    }
+    if ("hops" in cfg) {
+        const xff = request.headers.get("x-forwarded-for");
+        return pickForwardedForByHops(xff, cfg.hops) ?? peer;
+    }
+    // { cidrs } — out of scope for the trim implementation; falls back to peer.
+    // The CIDR matcher is reused from src/ip-restriction.ts; consumers that
+    // need the full check can compose ipRestriction({ allow: cfg.cidrs }) into
+    // the resolver. We honour the header only if the peer matches one of the
+    // declared CIDRs.
+    return peer;
+}
+/**
+ * Lazy accessors for `ctx.remoteAddress` / `ctx.remotePort`. Returns
+ * `undefined` rather than allocating a plain object so the IP cannot be
+ * serialized into logs by accident.
+ *
+ * @since 0.24.0
+ */
+export function readRemoteAddress(ctx) {
+    return getConnInfo(ctx.request)?.remoteAddress;
+}
+/** @since 0.24.0 */
+export function readRemotePort(ctx) {
+    return getConnInfo(ctx.request)?.remotePort;
+}
+/** @internal Test-only helper. */
+export function _makeConnInfoForTests(info) {
+    return { ...info };
+}
+//# sourceMappingURL=conn-info.js.map

package/dist/conn-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conn-info.js","sourceRoot":"","sources":["../src/conn-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAqDH,MAAM,gBAAgB,GAAkB,MAAM,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAEvE;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB,EAAE,IAAc;IACzD,OAAmD,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC;AAChF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,OAAQ,OAAmD,CAAC,gBAAgB,CAE/D,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAkC;IAClE,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO;IAC9B,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,UAAU;QAAE,OAAO;IACjD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;YAClB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC;gBACjE,MAAM,IAAI,KAAK,CACb,uDAAuD,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAC3E,CAAC;YACJ,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;YACnB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;YACzE,CAAC;YACD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;gBAC1B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC5C,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;gBAC1E,CAAC;YACH,CAAC;YACD,OAAO;QACT,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CACb,uEAAuE,OAAO,GAAG,GAAG,CACrF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAqB,EACrB,IAAY;IAEZ,IAAI,CAAC,MAAM,IAAI,IAAI,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,KAAK,GAAG,MAAM;SACjB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,GAAG,IAAI;QAAE,OAAO,SAAS,CAAC;IAC1C,sEAAsE;IACtE,iDAAiD;IACjD,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAgB,EAChB,GAAkC;IAElC,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,EAAE,aAAa,CAAC;IACjC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACrD,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;QACvB,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,kBAAkB,EAAE,CAAC;YAC1E,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;YACnD,MAAM,KAAK,GAAG,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;YACzC,IAAI,KAAK;gBAAE,OAAO,KAAK,CAAC;QAC1B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;QACnD,OAAO,sBAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IACvD,CAAC;IACD,4EAA4E;IAC5E,wEAAwE;IACxE,2EAA2E;IAC3E,yEAAyE;IACzE,kBAAkB;IAClB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAA0B;IAC1D,OAAO,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;AACjD,CAAC;AAED,oBAAoB;AACpB,MAAM,UAAU,cAAc,CAAC,GAA0B;IACvD,OAAO,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;AAC9C,CAAC;AAED,kCAAkC;AAClC,MAAM,UAAU,qBAAqB,CAAC,IAAc;IAClD,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC;AACrB,CAAC"}

package/dist/cookie.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Single source of truth for cookie serialization and attribute validation
+ * (Wave 8 remaining bake-ins).
+ *
+ * Every first-party subsystem that writes a `Set-Cookie` header — `session()`,
+ * `csrf()`, future ban / rate-limit-cooldown cookies — MUST route through
+ * {@link serializeCookie} and {@link assertCookieAttributes} so the framework
+ * has exactly one implementation of:
+ *
+ *  - the RFC 6265 attribute serialization rules,
+ *  - the `__Host-` / `__Secure-` cookie-prefix rules (RFC 6265bis §4.1.3),
+ *  - the production refuse-to-boot guard for `__Secure-` / `__Host-` without
+ *    TLS (a cookie the browser will silently drop is worse than a missing
+ *    cookie — fail loud at boot instead).
+ *
+ * The helper is intentionally tiny and dependency-free so it can be reused
+ * from every runtime adapter (Node / Bun / Deno / Workers / Edge / Lambda).
+ *
+ * @since 0.27.0
+ */
+/**
+ * `SameSite` attribute values per RFC 6265bis. `"None"` mandates the
+ * `Secure` attribute on a strictly-conforming user agent.
+ */
+export type CookieSameSite = "Strict" | "Lax" | "None";
+/**
+ * Fully-resolved cookie attributes. All optional fields default to the
+ * safest interpretation when omitted:
+ *
+ *  - `secure: true`
+ *  - `httpOnly: true`
+ *  - `sameSite: "Strict"`
+ *  - `path: "/"`
+ *
+ * @since 0.27.0
+ */
+export interface CookieAttributes {
+    /** Default `"Strict"`. */
+    sameSite?: CookieSameSite;
+    /** Default `true`. Required for `__Secure-` / `__Host-` prefixes. */
+    secure?: boolean;
+    /** Default `true`. Set explicitly to `false` for client-readable tokens (CSRF mirror). */
+    httpOnly?: boolean;
+    /** Default `"/"`. Required to equal `"/"` for `__Host-` prefix. */
+    path?: string;
+    /** Cookie `Domain=` attribute. Forbidden with `__Host-` prefix. */
+    domain?: string;
+    /** Cookie `Max-Age=` seconds. `0` omits it for set-cookie writes. */
+    maxAgeSeconds?: number;
+    /** `Partitioned` attribute (CHIPS). Default `false`. */
+    partitioned?: boolean;
+}
+/**
+ * Validate every cookie attribute against RFC 6265bis and the framework's
+ * secure-by-default posture. Throws on the first violation — designed to
+ * run at construction time so misconfiguration fails the boot rather than
+ * shipping a cookie the browser silently drops.
+ *
+ * In production (`isProduction: true`), refuses `__Secure-` / `__Host-`
+ * prefixes without `secure: true`. Outside production the same combination
+ * still throws because a `__Secure-` cookie sent over plaintext HTTP is a
+ * developer mistake at any environment.
+ *
+ * @param input.scope - Caller-supplied label for error messages (e.g.
+ *   `"session()"`, `"csrf()"`).
+ * @param input.name - Cookie name (must match the RFC token grammar).
+ * @param input.attributes - Resolved attribute bag.
+ * @param input.isProduction - Whether the App's resolved environment is
+ *   `production`. Used to scope the strictest refusals.
+ * @since 0.27.0
+ */
+export declare function assertCookieAttributes(input: {
+    readonly scope: string;
+    readonly name: string;
+    readonly attributes: CookieAttributes;
+    readonly isProduction?: boolean;
+}): void;
+/**
+ * Serialize a single `Set-Cookie` header value from a (name, value,
+ * attributes) tuple. The companion of {@link assertCookieAttributes} — call
+ * the assertion at construction time, then call this helper on every
+ * write.
+ *
+ * The value is URI-encoded so binary signature bytes and base64 padding
+ * round-trip safely.
+ *
+ * @since 0.27.0
+ */
+export declare function serializeCookie(name: string, value: string, attributes?: CookieAttributes): string;
+/**
+ * Serialize a `Set-Cookie` value that clears the named cookie. Uses
+ * `Max-Age=0` per RFC 6265 §5.2.2 and preserves the original attributes so
+ * intermediaries match the original cookie when deciding what to delete.
+ *
+ * @since 0.27.0
+ */
+export declare function serializeClearCookie(name: string, attributes?: CookieAttributes): string;
+/**
+ * Parse a single cookie value from a `Cookie` request header. Returns
+ * `null` when the named cookie is absent. URI-decoded on a best-effort
+ * basis (malformed `%` sequences return the raw value rather than throwing).
+ *
+ * Centralized so every framework subsystem reads cookies the same way and
+ * cannot disagree about whitespace handling between `session()` and
+ * `csrf()`.
+ *
+ * @since 0.27.0
+ */
+export declare function readRequestCookie(header: string | null | undefined, name: string): string | null;
+/** @internal Re-exported for tests. */
+export declare const __COOKIE_FRAMEWORK_PREFIX__ = "daloy.cookie";
+//# sourceMappingURL=cookie.d.ts.map

package/dist/cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../src/cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAUD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC,GAAG,IAAI,CAgDP;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,UAAU,GAAE,gBAAqB,GAChC,MAAM,CAiBR;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,GAAE,gBAAqB,GAAG,MAAM,CAe5F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBhG;AAED,uCAAuC;AACvC,eAAO,MAAM,2BAA2B,iBAAmB,CAAC"}

package/dist/cookie.js

@@ -0,0 +1,185 @@
+/**
+ * Single source of truth for cookie serialization and attribute validation
+ * (Wave 8 remaining bake-ins).
+ *
+ * Every first-party subsystem that writes a `Set-Cookie` header — `session()`,
+ * `csrf()`, future ban / rate-limit-cooldown cookies — MUST route through
+ * {@link serializeCookie} and {@link assertCookieAttributes} so the framework
+ * has exactly one implementation of:
+ *
+ *  - the RFC 6265 attribute serialization rules,
+ *  - the `__Host-` / `__Secure-` cookie-prefix rules (RFC 6265bis §4.1.3),
+ *  - the production refuse-to-boot guard for `__Secure-` / `__Host-` without
+ *    TLS (a cookie the browser will silently drop is worse than a missing
+ *    cookie — fail loud at boot instead).
+ *
+ * The helper is intentionally tiny and dependency-free so it can be reused
+ * from every runtime adapter (Node / Bun / Deno / Workers / Edge / Lambda).
+ *
+ * @since 0.27.0
+ */
+const COOKIE_NAME_RE = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/;
+const FRAMEWORK_PREFIX = "daloy.cookie";
+function validatePathOrDomain(scope, kind, value) {
+    if (/[;\r\n\0]/.test(value)) {
+        throw new Error(`${scope}: cookie ${kind} contains an invalid character.`);
+    }
+}
+/**
+ * Validate every cookie attribute against RFC 6265bis and the framework's
+ * secure-by-default posture. Throws on the first violation — designed to
+ * run at construction time so misconfiguration fails the boot rather than
+ * shipping a cookie the browser silently drops.
+ *
+ * In production (`isProduction: true`), refuses `__Secure-` / `__Host-`
+ * prefixes without `secure: true`. Outside production the same combination
+ * still throws because a `__Secure-` cookie sent over plaintext HTTP is a
+ * developer mistake at any environment.
+ *
+ * @param input.scope - Caller-supplied label for error messages (e.g.
+ *   `"session()"`, `"csrf()"`).
+ * @param input.name - Cookie name (must match the RFC token grammar).
+ * @param input.attributes - Resolved attribute bag.
+ * @param input.isProduction - Whether the App's resolved environment is
+ *   `production`. Used to scope the strictest refusals.
+ * @since 0.27.0
+ */
+export function assertCookieAttributes(input) {
+    const { scope, name, attributes: a, isProduction = false } = input;
+    if (typeof name !== "string" || !COOKIE_NAME_RE.test(name)) {
+        throw new Error(`${scope}: cookieName (cookie name) "${String(name)}" is not a valid cookie name (RFC 6265 token).`);
+    }
+    const sameSite = a.sameSite ?? "Strict";
+    if (sameSite !== "Strict" && sameSite !== "Lax" && sameSite !== "None") {
+        throw new Error(`${scope}: cookieOptions.sameSite must be "Strict", "Lax", or "None".`);
+    }
+    const secure = a.secure ?? true;
+    const path = a.path ?? "/";
+    if (typeof path !== "string" || !path.startsWith("/")) {
+        throw new Error(`${scope}: cookieOptions.path must start with "/".`);
+    }
+    validatePathOrDomain(scope, "path", path);
+    if (a.domain !== undefined) {
+        if (typeof a.domain !== "string" || a.domain.length === 0) {
+            throw new Error(`${scope}: cookieOptions.domain must be a non-empty string when set.`);
+        }
+        validatePathOrDomain(scope, "domain", a.domain);
+    }
+    if (a.maxAgeSeconds !== undefined) {
+        if (!Number.isInteger(a.maxAgeSeconds) || a.maxAgeSeconds < 0) {
+            throw new Error(`${scope}: cookieOptions.maxAgeSeconds must be a non-negative integer.`);
+        }
+    }
+    if (sameSite === "None" && !secure) {
+        throw new Error(`${scope}: cookieOptions.sameSite: "None" requires secure: true.`);
+    }
+    if (name.startsWith("__Host-")) {
+        if (!secure || path !== "/" || a.domain) {
+            throw new Error(`${scope}: "__Host-" cookie names require secure: true, path: "/", and no domain.`);
+        }
+    }
+    if (name.startsWith("__Secure-")) {
+        if (!secure) {
+            throw new Error(`${scope}: "__Secure-" cookie names require secure: true. ` +
+                (isProduction
+                    ? "Production refuse-to-boot: a browser will silently drop this cookie over HTTP."
+                    : "Drop the prefix or pass secure: true."));
+        }
+    }
+}
+/**
+ * Serialize a single `Set-Cookie` header value from a (name, value,
+ * attributes) tuple. The companion of {@link assertCookieAttributes} — call
+ * the assertion at construction time, then call this helper on every
+ * write.
+ *
+ * The value is URI-encoded so binary signature bytes and base64 padding
+ * round-trip safely.
+ *
+ * @since 0.27.0
+ */
+export function serializeCookie(name, value, attributes = {}) {
+    assertCookieAttributes({ scope: "serializeCookie()", name, attributes });
+    const sameSite = attributes.sameSite ?? "Strict";
+    const secure = attributes.secure ?? true;
+    const httpOnly = attributes.httpOnly ?? true;
+    const path = attributes.path ?? "/";
+    let out = `${name}=${encodeURIComponent(value)}`;
+    out += `; Path=${path}`;
+    out += `; SameSite=${sameSite}`;
+    if (secure)
+        out += "; Secure";
+    if (httpOnly)
+        out += "; HttpOnly";
+    if (attributes.domain)
+        out += `; Domain=${attributes.domain}`;
+    if (attributes.maxAgeSeconds !== undefined && attributes.maxAgeSeconds > 0) {
+        out += `; Max-Age=${attributes.maxAgeSeconds}`;
+    }
+    if (attributes.partitioned)
+        out += "; Partitioned";
+    return out;
+}
+/**
+ * Serialize a `Set-Cookie` value that clears the named cookie. Uses
+ * `Max-Age=0` per RFC 6265 §5.2.2 and preserves the original attributes so
+ * intermediaries match the original cookie when deciding what to delete.
+ *
+ * @since 0.27.0
+ */
+export function serializeClearCookie(name, attributes = {}) {
+    assertCookieAttributes({ scope: "serializeClearCookie()", name, attributes });
+    const sameSite = attributes.sameSite ?? "Strict";
+    const secure = attributes.secure ?? true;
+    const httpOnly = attributes.httpOnly ?? true;
+    const path = attributes.path ?? "/";
+    let out = `${name}=`;
+    out += `; Path=${path}`;
+    out += `; SameSite=${sameSite}`;
+    if (secure)
+        out += "; Secure";
+    if (httpOnly)
+        out += "; HttpOnly";
+    if (attributes.domain)
+        out += `; Domain=${attributes.domain}`;
+    out += "; Max-Age=0";
+    if (attributes.partitioned)
+        out += "; Partitioned";
+    return out;
+}
+/**
+ * Parse a single cookie value from a `Cookie` request header. Returns
+ * `null` when the named cookie is absent. URI-decoded on a best-effort
+ * basis (malformed `%` sequences return the raw value rather than throwing).
+ *
+ * Centralized so every framework subsystem reads cookies the same way and
+ * cannot disagree about whitespace handling between `session()` and
+ * `csrf()`.
+ *
+ * @since 0.27.0
+ */
+export function readRequestCookie(header, name) {
+    if (!header)
+        return null;
+    const parts = header.split(";");
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            continue;
+        const k = part.slice(0, eq).trim();
+        if (k === name) {
+            const v = part.slice(eq + 1).trim();
+            try {
+                return decodeURIComponent(v);
+            }
+            catch {
+                return v;
+            }
+        }
+    }
+    return null;
+}
+/** @internal Re-exported for tests. */
+export const __COOKIE_FRAMEWORK_PREFIX__ = FRAMEWORK_PREFIX;
+//# sourceMappingURL=cookie.js.map

package/dist/cookie.js.map

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

package/dist/dependency.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Typed-DI chain helper (Wave 6 item 12).
+ *
+ * `defineDependency()` wraps a middleware so the framework deduplicates
+ * evaluation per request — a request that triggers two routes both depending
+ * on `getCurrentUser` runs the auth check exactly once per request, with the
+ * typed result threaded through `ctx.state` declared in {@link AppState}.
+ *
+ * Refuses-at-construction on cyclic dependency declarations (companion to
+ * the cyclic plugin-extension-ordering refusal in {@link App.register}).
+ *
+ * @since 0.24.0
+ */
+import type { BaseContext, Hooks } from "./types.js";
+/** Symbol stamped on hooks returned by {@link defineDependency}. */
+export declare const DEPENDENCY_MARKER: unique symbol;
+export interface DependencyOptions<TName extends string, TValue, TStateKey extends string> {
+    /** Unique dependency name. Used for cycle detection and dedup. */
+    name: TName;
+    /** Other dependency names this one requires (must run + complete first). */
+    dependsOn?: readonly string[];
+    /** Key the resolved value is written to on `ctx.state`. Defaults to `name`. */
+    stateKey?: TStateKey;
+    /**
+     * Resolve the dependency value. Receives the per-request context, returns
+     * the value to stamp on `ctx.state[stateKey]`. Called at most once per
+     * request when the dependency wrapper is composed multiple times.
+     */
+    resolve: (ctx: BaseContext<any, any>) => TValue | Promise<TValue>;
+}
+/** Hooks bundle returned by {@link defineDependency} (carries metadata). */
+export interface DependencyHooks extends Hooks {
+    readonly [DEPENDENCY_MARKER]: {
+        readonly name: string;
+        readonly dependsOn: readonly string[];
+    };
+}
+/**
+ * Wrap a per-request value producer as a {@link Hooks} bundle. The hook
+ * runs in `beforeHandle` and writes its resolved value to
+ * `ctx.state[stateKey]` (default `name`). Composing the same dependency
+ * twice in one chain runs `resolve()` exactly once.
+ *
+ * @since 0.24.0
+ */
+export declare function defineDependency<TName extends string, TValue, TStateKey extends string = TName>(opts: DependencyOptions<TName, TValue, TStateKey>): DependencyHooks;
+//# sourceMappingURL=dependency.d.ts.map

package/dist/dependency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency.d.ts","sourceRoot":"","sources":["../src/dependency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAErD,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAEtC,CAAC;AAKF,MAAM,WAAW,iBAAiB,CAAC,KAAK,SAAS,MAAM,EAAE,MAAM,EAAE,SAAS,SAAS,MAAM;IACvF,kEAAkE;IAClE,IAAI,EAAE,KAAK,CAAC;IACZ,4EAA4E;IAC5E,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnE;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAgB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,CAAC,iBAAiB,CAAC,EAAE;QAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;KACvC,CAAC;CACH;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,SAAS,MAAM,EACpB,MAAM,EACN,SAAS,SAAS,MAAM,GAAG,KAAK,EAChC,IAAI,EAAE,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,GAAG,eAAe,CAgDpE"}