@lovrozagar/honey 0.7.2 → 1.0.0-rc.1

package/dist/context/context.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `HoneyContext`: what a handler and its middleware see for one request. Dispatch hands it the
+ * request state and the route's precomputed info positionally; cookies, headers, the query and
+ * the abort signal are read from the request only when first asked for.
+ */
+import type { HoneyError } from "../errors/error.ts";
+import { HoneyRes } from "../response/response.ts";
+import type { Logger } from "../telemetry/logger.ts";
+import type { RequestTrace } from "../telemetry/request-trace.ts";
+export type ExecutionCtx = {
+    waitUntil?: (p: Promise<unknown>) => void;
+};
+/** The per-request state dispatch owns; the context reads its request fields from it. */
+export type RequestState<TEnv> = {
+    readonly env: TEnv;
+    readonly executionCtx: ExecutionCtx | undefined;
+    /** the app's logger */
+    readonly logger: Logger;
+    readonly path: string;
+    readonly req: Request;
+    /** `ctx.ip` once something asked: the canonical peer, or `null` when no runtime reports one */
+    ip?: string | null;
+    /** set when the route's handler answered, on a route with taps only: they fire on nothing else */
+    answered?: true;
+    /** this request's spans, when the app has telemetry */
+    trace?: RequestTrace;
+};
+/** What a context reads from its route, computed once at finalize. */
+export type RouteInfo = {
+    /** the route's id (`GET /users/:id`); empty for a request no route serves */
+    readonly id: string;
+    readonly errors: Readonly<Record<string, (...args: never[]) => unknown>> | null;
+    readonly meta: Readonly<Record<string, unknown>>;
+    readonly pattern: string;
+};
+/** The route info of a context that serves no route (a miss, a bare context). */
+export declare const NO_ROUTE: RouteInfo;
+/** The context's slot for its request state: not exported from the package, so user code cannot reach it. */
+export declare const REQUEST: unique symbol;
+/** Abort `ctx.signal` from inside honey (a timeout): not exported from the package. */
+export declare const ABORT_CONTEXT: unique symbol;
+/** The request's trace when the app has telemetry: read by requestId and proxy, never part of the package API. */
+export declare const TRACE: unique symbol;
+/** The taps `ctx.tap()` queued, and whether the route's handler answered: read by routing/tap.ts only. */
+export declare const TAPS: unique symbol;
+/** One `ctx.tap(key, payload)` call, waiting for the handler's answer. */
+export type TapCall = {
+    readonly key: string;
+    readonly payload: unknown;
+};
+export declare function isReservedCtxKey(key: string): boolean;
+/**
+ * Put `req` in place of `ctx.req`: bodyLimit's counted body. The headers, method and URL stay what
+ * they were, so ctx's parsed views (headers, cookies, the query) still describe it.
+ */
+export declare function replaceRequest(ctx: object, req: Request): void;
+/** Record the error behind the response on `ctx.error`, read-only for user code. */
+export declare function setCtxError(ctx: HoneyContext<never> | HoneyContext, error: HoneyError): void;
+export declare class HoneyContext<TEnv = Record<string, unknown>> {
+    #private;
+    /**
+     * Keep a promise running past the response: `waitUntil` on Workers, which reports a rejection
+     * itself; elsewhere a rejection goes to the request's logger.
+     */
+    readonly background: (p: Promise<unknown>) => void;
+    readonly env: TEnv;
+    /**
+     * The error behind the response, once a handler or a deeper middleware threw and the `next()`
+     * boundary turned it into an error response; `undefined` while nothing failed.
+     */
+    readonly error: HoneyError | undefined;
+    readonly errors: Readonly<Record<string, (...args: never[]) => unknown>>;
+    readonly executionCtx: ExecutionCtx | undefined;
+    readonly meta: Readonly<Record<string, unknown>>;
+    readonly params: Record<string, string>;
+    readonly path: string;
+    readonly req: Request;
+    readonly res: HoneyRes;
+    readonly routePattern: string;
+    readonly [REQUEST]: RequestState<TEnv>;
+    constructor(state: RequestState<TEnv>, route: RouteInfo, params: Record<string, string>);
+    get [TRACE](): RequestTrace | null;
+    /** The peer the platform reports, canonical (H23): CF-Connecting-IP on Workers, the socket on Bun and Node. */
+    get ip(): string | null;
+    /**
+     * This request's logger: a child of the app's that binds method, path (without its query), route
+     * id, the request id when one is set, and the trace's ids when traced. Built on first use.
+     */
+    get log(): Logger;
+    get cookies(): Record<string, string>;
+    /** The request headers as a record: keys are lower-case and request data, so no prototype. */
+    get headers(): Record<string, string>;
+    /** The query: the first value of each key. Keys are request data, so no prototype. */
+    get search(): Record<string, string>;
+    /** The query: every value of each key, in order. */
+    get searchAll(): Record<string, string[]>;
+    /**
+     * Aborts when the client disconnects or the server shuts down. Pass it to `fetch()`, database
+     * drivers and timers so abandoned work stops.
+     */
+    get signal(): AbortSignal;
+    /**
+     * Fire the app's tap for `key` with `payload` once this request's handler answered: after the
+     * response, never on an error answer, never delaying it. A key no tap is registered for is ignored.
+     */
+    tap(key: string, payload: unknown): void;
+    /** What `tap()` queued, or null when nothing was. */
+    get [TAPS](): readonly TapCall[] | null;
+    /** Abort `signal` with `reason`, so work that takes it stops (a timeout answered for it). */
+    [ABORT_CONTEXT](reason: unknown): void;
+}

package/dist/context/context.js

@@ -0,0 +1,213 @@
+import { isNodeOutbound } from "../response/builder.js";
+import { HoneyRes } from "../response/response.js";
+import { searchOfUrl } from "../routing/request-path.js";
+import { dict } from "../routing/tree.js";
+import { requestBindings } from "../telemetry/fields.js";
+import { parseCookieHeader } from "./cookie.js";
+import { ipOf } from "./peer.js";
+const EMPTY = /* @__PURE__ */ Object.freeze({});
+/** The route info of a context that serves no route (a miss, a bare context). */
+export const NO_ROUTE = /* @__PURE__ */ Object.freeze({ errors: null, id: "", meta: EMPTY, pattern: "" });
+/** The context's slot for its request state: not exported from the package, so user code cannot reach it. */
+export const REQUEST = /* @__PURE__ */ Symbol("honey.request");
+/** Abort `ctx.signal` from inside honey (a timeout): not exported from the package. */
+export const ABORT_CONTEXT = /* @__PURE__ */ Symbol("honey.abortContext");
+/** The request's trace when the app has telemetry: read by requestId and proxy, never part of the package API. */
+export const TRACE = /* @__PURE__ */ Symbol("honey.trace");
+/** The taps `ctx.tap()` queued, and whether the route's handler answered: read by routing/tap.ts only. */
+export const TAPS = /* @__PURE__ */ Symbol("honey.taps");
+/**
+ * Every name the framework owns on a context. `next({ ... })` additions and `.context()` values may
+ * not use them: an addition would silently replace framework state, and one assigned over a
+ * getter-only field throws on every request.
+ */
+const RESERVED = /* @__PURE__ */ Object.freeze({
+    background: true,
+    cookies: true,
+    env: true,
+    error: true,
+    errors: true,
+    executionCtx: true,
+    headers: true,
+    input: true,
+    ip: true,
+    log: true,
+    meta: true,
+    params: true,
+    path: true,
+    req: true,
+    res: true,
+    routePattern: true,
+    search: true,
+    searchAll: true,
+    signal: true,
+    tap: true,
+});
+export function isReservedCtxKey(key) {
+    return Object.hasOwn(RESERVED, key);
+}
+/**
+ * Put `req` in place of `ctx.req`: bodyLimit's counted body. The headers, method and URL stay what
+ * they were, so ctx's parsed views (headers, cookies, the query) still describe it.
+ */
+export function replaceRequest(ctx, req) {
+    ;
+    ctx.req = req;
+}
+/** Record the error behind the response on `ctx.error`, read-only for user code. */
+export function setCtxError(ctx, error) {
+    ;
+    ctx.error = error;
+}
+export class HoneyContext {
+    /**
+     * Keep a promise running past the response: `waitUntil` on Workers, which reports a rejection
+     * itself; elsewhere a rejection goes to the request's logger.
+     */
+    background;
+    env;
+    /**
+     * The error behind the response, once a handler or a deeper middleware threw and the `next()`
+     * boundary turned it into an error response; `undefined` while nothing failed.
+     */
+    error = undefined;
+    errors;
+    executionCtx;
+    meta;
+    params;
+    path;
+    req;
+    res;
+    routePattern;
+    [REQUEST];
+    #ac = null;
+    #cookies = null;
+    #headers = null;
+    #log = null;
+    #routeId;
+    #search = null;
+    #searchAll = null;
+    #taps = null;
+    constructor(state, route, params) {
+        this.env = state.env;
+        this.errors = route.errors ?? EMPTY;
+        this.executionCtx = state.executionCtx;
+        this.meta = route.meta;
+        this.params = params;
+        this.path = state.path;
+        this.req = state.req;
+        /* the context is the res's link to its request: signal and headers read only when a stream needs them */
+        this.res = new HoneyRes(isNodeOutbound(state.req), this);
+        this.routePattern = route.pattern;
+        this.#routeId = route.id;
+        this[REQUEST] = state;
+        /* called on its owner: workerd's waitUntil throws "Illegal invocation" when detached */
+        const executionCtx = state.executionCtx;
+        const waitUntil = executionCtx?.waitUntil;
+        this.background = waitUntil
+            ? (p) => waitUntil.call(executionCtx, p)
+            : (p) => void p.catch((error) => this.log.error({ err: error }, "background task failed"));
+    }
+    get [TRACE]() {
+        return this[REQUEST].trace ?? null;
+    }
+    /** The peer the platform reports, canonical (H23): CF-Connecting-IP on Workers, the socket on Bun and Node. */
+    get ip() {
+        return ipOf(this[REQUEST]);
+    }
+    /**
+     * This request's logger: a child of the app's that binds method, path (without its query), route
+     * id, the request id when one is set, and the trace's ids when traced. Built on first use.
+     */
+    get log() {
+        this.#log ??= this[REQUEST].logger.child(requestBindings(this.req.method, this.path, this.#routeId, {
+            requestId: this.requestId,
+            trace: this[REQUEST].trace?.ids(),
+        }));
+        return this.#log;
+    }
+    get cookies() {
+        this.#cookies ??= parseCookieHeader(this.req.headers.get("cookie") ?? "");
+        return this.#cookies;
+    }
+    /** The request headers as a record: keys are lower-case and request data, so no prototype. */
+    get headers() {
+        if (this.#headers === null) {
+            const out = dict();
+            for (const [key, value] of this.req.headers)
+                out[key] = value;
+            this.#headers = out;
+        }
+        return this.#headers;
+    }
+    /** The query: the first value of each key. Keys are request data, so no prototype. */
+    get search() {
+        if (this.#search === null)
+            this.#parseSearch();
+        return this.#search;
+    }
+    /** The query: every value of each key, in order. */
+    get searchAll() {
+        if (this.#searchAll === null)
+            this.#parseSearch();
+        return this.#searchAll;
+    }
+    /**
+     * Aborts when the client disconnects or the server shuts down. Pass it to `fetch()`, database
+     * drivers and timers so abandoned work stops.
+     */
+    get signal() {
+        this.#ac ??= this.#linkSignal();
+        return this.#ac.signal;
+    }
+    /**
+     * Fire the app's tap for `key` with `payload` once this request's handler answered: after the
+     * response, never on an error answer, never delaying it. A key no tap is registered for is ignored.
+     */
+    tap(key, payload) {
+        ;
+        (this.#taps ??= []).push({ key, payload });
+    }
+    /** What `tap()` queued, or null when nothing was. */
+    get [TAPS]() {
+        return this.#taps;
+    }
+    /** Abort `signal` with `reason`, so work that takes it stops (a timeout answered for it). */
+    [ABORT_CONTEXT](reason) {
+        this.#ac ??= this.#linkSignal();
+        this.#ac.abort(reason);
+    }
+    #parseSearch() {
+        const first = dict();
+        const all = dict();
+        for (const [key, value] of new URLSearchParams(searchOfUrl(this.req.url))) {
+            const values = all[key];
+            if (values === undefined) {
+                first[key] = value;
+                all[key] = [value];
+            }
+            else {
+                values.push(value);
+            }
+        }
+        this.#search = first;
+        this.#searchAll = all;
+    }
+    /** A controller that follows the request's own signal; a request shim without one stands alone. */
+    #linkSignal() {
+        const ac = new AbortController();
+        let request;
+        try {
+            request = this.req.signal;
+        }
+        catch {
+            /* a request shim with no usable signal: the controller stands alone, nothing failed */
+            return ac;
+        }
+        if (request?.aborted)
+            ac.abort(request.reason);
+        else
+            request?.addEventListener("abort", () => ac.abort(request.reason), { once: true });
+        return ac;
+    }
+}

package/dist/context/cookie-sign.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Signed cookie values: HMAC-SHA256 over WebCrypto, verified in constant time by
+ * `crypto.subtle.verify`. Key rotation is a secret list: the first signs, any verifies.
+ *
+ * - v2 (current): `<value>.~<sig>`, the HMAC of `"honey-cookie-v2\0" + name + "\0" + value`. The
+ *   cookie name is bound into the MAC, so a signature cannot be replayed under another cookie that
+ *   shares the secret. `~` is outside the base64url alphabet, so the two formats never overlap.
+ * - v1 (legacy): `<value>.<sig>`, the HMAC of the value alone. `verify` accepts it while `legacy` is
+ *   true (the default), so cookies issued before v2 keep working during a migration window.
+ */
+export type SignOptions = {
+    /** The cookie name to bind the signature to. Pass the same name to `verify`. */
+    name?: string;
+};
+export type VerifyOptions = {
+    /**
+     * Also accept legacy (v1) signatures, which are not bound to a name.
+     * Default `true`; set `false` once every v1 cookie has expired.
+     */
+    legacy?: boolean;
+    /** The cookie name the signature must be bound to. */
+    name?: string;
+};
+export type CookieSigner = {
+    /** Sign with the first secret. */
+    sign(value: string, opts?: SignOptions): Promise<string>;
+    /** The original value, or `null` when no secret verifies it or the input is malformed. */
+    verify(signed: string, opts?: VerifyOptions): Promise<string | null>;
+};
+/**
+ * A signer over a secret list: the first signs, any verifies. Each key is imported once, on first
+ * use, and held by the signer, so a per-request verify costs no key import. Build one per app.
+ */
+export declare function createCookieSigner(secrets: readonly string[]): CookieSigner;
+/** Sign one value; imports the key each call. A hot path holds a `createCookieSigner` instead. */
+export declare function sign(value: string, secret: string, opts?: SignOptions): Promise<string>;
+/** Verify one value; imports the keys each call. A hot path holds a `createCookieSigner` instead. */
+export declare function verify(signed: string, secrets: readonly string[], opts?: VerifyOptions): Promise<string | null>;

package/dist/context/cookie-sign.js

@@ -0,0 +1,113 @@
+/**
+ * Signed cookie values: HMAC-SHA256 over WebCrypto, verified in constant time by
+ * `crypto.subtle.verify`. Key rotation is a secret list: the first signs, any verifies.
+ *
+ * - v2 (current): `<value>.~<sig>`, the HMAC of `"honey-cookie-v2\0" + name + "\0" + value`. The
+ *   cookie name is bound into the MAC, so a signature cannot be replayed under another cookie that
+ *   shares the secret. `~` is outside the base64url alphabet, so the two formats never overlap.
+ * - v1 (legacy): `<value>.<sig>`, the HMAC of the value alone. `verify` accepts it while `legacy` is
+ *   true (the default), so cookies issued before v2 keep working during a migration window.
+ */
+// per-process-constant: text-codec
+const encoder = /* @__PURE__ */ new TextEncoder();
+const V2_MARKER = "~";
+const V2_DOMAIN = "honey-cookie-v2\0";
+/* an HMAC-SHA256 tag is 32 bytes: 43 base64url characters, no padding */
+const SIG_RE = /^[A-Za-z0-9_-]{43}$/;
+/**
+ * Import a secret's HMAC key. The rejection is observed here, so an unused unusable secret raises
+ * no unhandled rejection; awaiting the key still throws.
+ */
+function importKey(secret) {
+    const key = crypto.subtle.importKey("raw", encoder.encode(secret), { hash: "SHA-256", name: "HMAC" }, false, [
+        "sign",
+        "verify",
+    ]);
+    /* marked handled here; every caller awaits the key, and verify() answers false for one that failed */
+    key.catch(() => undefined);
+    return key;
+}
+function toBase64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+/** Strict decode: the input must be the canonical encoding of a 32-byte tag. */
+function fromBase64Url(str) {
+    if (!SIG_RE.test(str))
+        return null;
+    const binary = atob(str.replaceAll("-", "+").replaceAll("_", "/"));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    /* non-zero trailing bits would make signatures malleable */
+    if (toBase64Url(bytes) !== str)
+        return null;
+    return bytes;
+}
+function v2Payload(name, value) {
+    return encoder.encode(`${V2_DOMAIN}${name}\0${value}`);
+}
+/** Split a signed value into the value, its tag and the payload the tag covers; `null` when malformed. */
+function parseSigned(signed, opts) {
+    if (typeof signed !== "string" || signed.length === 0)
+        return null;
+    const lastDot = signed.lastIndexOf(".");
+    if (lastDot === -1)
+        return null;
+    const value = signed.slice(0, lastDot);
+    let sigText = signed.slice(lastDot + 1);
+    const isV2 = sigText.startsWith(V2_MARKER);
+    if (isV2)
+        sigText = sigText.slice(V2_MARKER.length);
+    else if (opts.legacy === false)
+        return null;
+    const sig = fromBase64Url(sigText);
+    if (sig === null)
+        return null;
+    return { payload: isV2 ? v2Payload(opts.name ?? "", value) : encoder.encode(value), sig, value };
+}
+async function verifiesWith(key, sig, payload) {
+    try {
+        return await crypto.subtle.verify("HMAC", await key, sig, payload);
+    }
+    catch {
+        /* an unusable secret never verifies */
+        return false;
+    }
+}
+/**
+ * A signer over a secret list: the first signs, any verifies. Each key is imported once, on first
+ * use, and held by the signer, so a per-request verify costs no key import. Build one per app.
+ */
+export function createCookieSigner(secrets) {
+    let keys = null;
+    const keysOf = () => (keys ??= secrets.map(importKey));
+    return {
+        async sign(value, opts = {}) {
+            const first = keysOf()[0];
+            if (first === undefined)
+                throw new TypeError("no secret to sign with");
+            const signature = await crypto.subtle.sign("HMAC", await first, v2Payload(opts.name ?? "", value));
+            return `${value}.${V2_MARKER}${toBase64Url(new Uint8Array(signature))}`;
+        },
+        async verify(signed, opts = {}) {
+            const parsed = parseSigned(signed, opts);
+            if (parsed === null)
+                return null;
+            for (const key of keysOf())
+                if (await verifiesWith(key, parsed.sig, parsed.payload))
+                    return parsed.value;
+            return null;
+        },
+    };
+}
+/** Sign one value; imports the key each call. A hot path holds a `createCookieSigner` instead. */
+export function sign(value, secret, opts = {}) {
+    return createCookieSigner([secret]).sign(value, opts);
+}
+/** Verify one value; imports the keys each call. A hot path holds a `createCookieSigner` instead. */
+export function verify(signed, secrets, opts = {}) {
+    return createCookieSigner(secrets).verify(signed, opts);
+}

package/dist/context/cookie.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The cookie codec: parse a `Cookie` request header and serialize one `Set-Cookie` value. Values
+ * are percent-encoded outside the RFC 6265 cookie-octet range so they always decode back to what
+ * was set; names, domains and paths are validated so no input can inject an attribute.
+ */
+export type CookieOptions = {
+    domain?: string;
+    expires?: Date;
+    httpOnly?: boolean;
+    maxAge?: number;
+    path?: string;
+    sameSite?: "lax" | "none" | "strict";
+    secure?: boolean;
+    value: string;
+};
+/**
+ * Decode `%XX` sequences that form valid UTF-8 and keep every other byte as sent: a stray `%` in a
+ * foreign cookie does not disable decoding for the whole value.
+ */
+export declare function decodeCookieValue(value: string): string;
+/**
+ * Parse a `Cookie` request header. When a name repeats, the first value wins: browsers send the
+ * cookie with the most specific path first (RFC 6265 §5.4). Names are trimmed and empty names
+ * skipped. The record has no prototype, so a cookie named like an Object.prototype member is a
+ * plain key and nothing else answers to such a name.
+ */
+export declare function parseCookieHeader(header: string): Record<string, string>;
+export declare function serializeCookie(name: string, opts: CookieOptions): string;

package/dist/context/cookie.js

@@ -0,0 +1,142 @@
+/**
+ * The cookie codec: parse a `Cookie` request header and serialize one `Set-Cookie` value. Values
+ * are percent-encoded outside the RFC 6265 cookie-octet range so they always decode back to what
+ * was set; names, domains and paths are validated so no input can inject an attribute.
+ */
+const validCookieNameRe = /^[\w!#$%&'*.^`|~+-]+$/;
+/* a host name or IP literal, optionally with a leading dot */
+const validDomainRe = /^\.?(?:[A-Za-z0-9-]+\.)*[A-Za-z0-9-]+$|^\[[0-9A-Fa-f:.]+\]$/;
+/* av-value: any CHAR except CTLs or ";" (RFC 6265 §4.1.1) */
+const invalidPathRe = /[^\x20-\x3a\x3c-\x7e]/;
+/** Cookie-octets: 0x21, 0x23-0x2B, 0x2D-0x3A, 0x3C-0x5B, 0x5D-0x7E; `%` is encoded so it round-trips. */
+function isCookieOctet(c) {
+    if (c === 0x25)
+        return false;
+    return (c === 0x21 ||
+        (c >= 0x23 && c <= 0x2b) ||
+        (c >= 0x2d && c <= 0x3a) ||
+        (c >= 0x3c && c <= 0x5b) ||
+        (c >= 0x5d && c <= 0x7e));
+}
+function encodeCookieValue(value) {
+    let encoded = "";
+    for (const ch of value) {
+        const c = ch.charCodeAt(0);
+        if (isCookieOctet(c))
+            encoded += ch;
+        /* an astral character is two units; a single unit in the surrogate range is a lone surrogate */ else if (ch.length === 1 &&
+            c >= 0xd800 &&
+            c <= 0xdfff)
+            throw new TypeError("Cookie value contains a lone surrogate and cannot be encoded");
+        else
+            encoded += encodeURIComponent(ch);
+    }
+    return encoded;
+}
+/**
+ * Decode `%XX` sequences that form valid UTF-8 and keep every other byte as sent: a stray `%` in a
+ * foreign cookie does not disable decoding for the whole value.
+ */
+export function decodeCookieValue(value) {
+    if (!value.includes("%"))
+        return value;
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        /* a malformed escape is client data, not a failure: every run that decodes is decoded, the rest kept */
+        return value.replace(/(?:%[0-9A-Fa-f]{2})+/g, (run) => {
+            try {
+                return decodeURIComponent(run);
+            }
+            catch {
+                /* this run is not UTF-8: kept as written */
+                return run;
+            }
+        });
+    }
+}
+/**
+ * Parse a `Cookie` request header. When a name repeats, the first value wins: browsers send the
+ * cookie with the most specific path first (RFC 6265 §5.4). Names are trimmed and empty names
+ * skipped. The record has no prototype, so a cookie named like an Object.prototype member is a
+ * plain key and nothing else answers to such a name.
+ */
+export function parseCookieHeader(header) {
+    const result = Object.create(null);
+    if (header.length === 0)
+        return result;
+    for (const pair of header.split(";")) {
+        const eqIdx = pair.indexOf("=");
+        if (eqIdx === -1)
+            continue;
+        const name = pair.slice(0, eqIdx).trim();
+        if (name.length === 0 || Object.hasOwn(result, name))
+            continue;
+        let value = pair.slice(eqIdx + 1).trim();
+        /* RFC 6265: strip surrounding double quotes before decoding, so an encoded quote survives */
+        if (value.length >= 2 && value.charCodeAt(0) === 34 && value.charCodeAt(value.length - 1) === 34)
+            value = value.slice(1, -1);
+        result[name] = decodeCookieValue(value);
+    }
+    return result;
+}
+/** Apply the `__Host-`/`__Secure-` prefix rules; browsers match them case-insensitively (RFC 6265bis §4.1.3). */
+function prefixRules(name, opts) {
+    const lower = name.toLowerCase();
+    if (lower.startsWith("__host-")) {
+        if (!opts.secure)
+            throw new Error("__Host- cookies require secure: true");
+        if (opts.domain)
+            throw new Error("__Host- cookies must not set domain");
+        if (opts.path !== "/" && opts.path !== undefined)
+            throw new Error("__Host- cookies must have path: '/'");
+        return { path: "/", secure: true };
+    }
+    if (lower.startsWith("__secure-") && !opts.secure)
+        throw new Error("__Secure- cookies require secure: true");
+    return { path: opts.path, secure: opts.secure === true };
+}
+function validate(opts, path, secure) {
+    if (opts.sameSite === "none" && !secure)
+        throw new Error("SameSite=None cookies require secure: true");
+    if (opts.domain && !validDomainRe.test(opts.domain))
+        throw new Error("Cookie domain contains invalid characters");
+    if (path && invalidPathRe.test(path))
+        throw new Error("Cookie path contains invalid characters");
+}
+/** The Max-Age and Expires attributes, validated. */
+function lifetime(opts) {
+    let out = "";
+    if (opts.maxAge !== undefined) {
+        if (!Number.isFinite(opts.maxAge) || opts.maxAge < 0)
+            throw new Error(`Invalid cookie Max-Age: ${opts.maxAge}`);
+        /* clamp so the value prints as digits; browsers cap Max-Age at 400 days anyway */
+        out += `; Max-Age=${Math.min(Math.floor(opts.maxAge), Number.MAX_SAFE_INTEGER)}`;
+    }
+    if (opts.expires) {
+        if (Number.isNaN(opts.expires.getTime()))
+            throw new Error("Invalid cookie Expires: date is invalid");
+        out += `; Expires=${opts.expires.toUTCString()}`;
+    }
+    return out;
+}
+export function serializeCookie(name, opts) {
+    if (!validCookieNameRe.test(name))
+        throw new Error(`Invalid cookie name: ${JSON.stringify(name)}`);
+    const { path, secure } = prefixRules(name, opts);
+    validate(opts, path, secure);
+    let cookie = `${name}=${encodeCookieValue(opts.value)}`;
+    if (opts.domain)
+        cookie += `; Domain=${opts.domain}`;
+    if (path)
+        cookie += `; Path=${path}`;
+    cookie += lifetime(opts);
+    if (opts.httpOnly)
+        cookie += "; HttpOnly";
+    if (secure)
+        cookie += "; Secure";
+    if (opts.sameSite)
+        cookie += `; SameSite=${opts.sameSite.charAt(0).toUpperCase()}${opts.sameSite.slice(1)}`;
+    return cookie;
+}

package/dist/context/peer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `ctx.ip`: the peer the platform reports, in one canonical spelling (H23). There is no proxy
+ * trust: the address is the connection's other end as the runtime sees it.
+ *
+ * - Cloudflare Workers: `CF-Connecting-IP`, which the edge sets and a client cannot override. It
+ *   is read only when running on Workers; anywhere else it is client-sent text.
+ * - Bun: `server.requestIP(req)`, from the server Bun passes as fetch's env (or `env.server`).
+ * - Node: the socket's `remoteAddress`, which the Node adapter's request reports under
+ *   `PEER_ADDRESS`.
+ *
+ * Behind a self-hosted reverse proxy that is the proxy's address.
+ */
+/** A request that knows its peer reports it under this key, allocation-free (the Node adapter's request). */
+export declare const PEER_ADDRESS: unique symbol;
+/** The peer address as the runtime reports it, unparsed, or `null` when nothing reports one. */
+export declare function peerAddressOf(req: Request, env: unknown): string | null;
+/** What a request carries for `ctx.ip`: the request, the env (which may be a Bun server), and the address once read. */
+export type PeerSource = {
+    readonly env: unknown;
+    readonly req: Request;
+    ip?: string | null;
+};
+/** The request's canonical peer, read on first ask and kept on its state. */
+export declare function ipOf(source: PeerSource): string | null;
+/** Dotted IPv4, strict: four decimal octets, no leading zero; `null` otherwise. */
+export declare function parseIpv4(s: string): number | null;
+/** IPv6 text (an embedded IPv4 tail allowed) as its 128-bit value; no brackets, zone or port; `null` otherwise. */
+export declare function parseIpv6(s: string): bigint | null;
+/**
+ * One spelling per address, so the same client reads the same on every runtime: dotted IPv4 (an
+ * IPv4-mapped IPv6 address and an IPv4 address with a port included) or RFC 5952 IPv6. `null`
+ * for anything that is not exactly one address.
+ */
+export declare function canonicalIp(input: string): string | null;