@nifrajs/core 0.1.0-alpha.1

package/dist/server/contract.d.ts

@@ -0,0 +1,142 @@
+import { type Method } from "../router/router.js";
+import type { InferOutput, StandardSchemaV1 } from "../schema/standard.js";
+import type { Context, Params, RouteSchema } from "./context.js";
+import type { OutputOf } from "./registry.js";
+import { Server } from "./server.js";
+/** An additional (non-success) response a contract operation can document, e.g. a `404`. */
+export interface ResponseDef {
+    readonly description?: string;
+    /** Response body schema (any Standard Schema; a `t` schema yields full JSON Schema in OpenAPI). */
+    readonly schema?: StandardSchemaV1;
+    /** Content type. Default `application/json`. */
+    readonly contentType?: string;
+}
+/**
+ * One operation in a contract. Input schemas are any Standard Schema; `response` is optional.
+ *
+ * The fields below `response` are **optional OpenAPI metadata** — they don't affect runtime
+ * validation or the inferred handler types, they enrich the document `toOpenAPI` emits. A contract is
+ * the natural home for them: it's the versionable description of the API, decoupled from the impl.
+ */
+export interface OperationDef {
+    readonly method: Method;
+    readonly path: string;
+    readonly body?: StandardSchemaV1;
+    readonly query?: StandardSchemaV1;
+    readonly response?: StandardSchemaV1;
+    /** Short summary (OpenAPI `summary`). */
+    readonly summary?: string;
+    /** Longer description (OpenAPI `description`, CommonMark). */
+    readonly description?: string;
+    /** Grouping tags (OpenAPI `tags`). */
+    readonly tags?: readonly string[];
+    /** Mark the operation deprecated. */
+    readonly deprecated?: boolean;
+    /** Security requirements (names ref `securitySchemes`); `[]` = explicitly public. Omit ⇒ inherit the document default. */
+    readonly security?: ReadonlyArray<Readonly<Record<string, readonly string[]>>>;
+    /** Request body content type. Default `application/json`. */
+    readonly requestContentType?: string;
+    /** Content type of the success (`200`) response. Default `application/json`. */
+    readonly responseContentType?: string;
+    /** Additional responses by status code, e.g. `{ "404": { description: "Not found" } }`. */
+    readonly responses?: Readonly<Record<string, ResponseDef>>;
+}
+/** A contract: named operations. Names are the handler keys and OpenAPI operationIds. */
+export type ContractShape = Record<string, OperationDef>;
+type OpBody<O extends OperationDef> = O extends {
+    body: infer B extends StandardSchemaV1;
+} ? InferOutput<B> : never;
+type OpQuery<O extends OperationDef> = O extends {
+    query: infer Q extends StandardSchemaV1;
+} ? InferOutput<Q> : never;
+type OpResponse<O extends OperationDef> = O extends {
+    response: infer R extends StandardSchemaV1;
+} ? InferOutput<R> : unknown;
+/**
+ * RouteInfo as a *decoupled consumer* sees it from the contract alone: the
+ * `output` is the declared `response` schema's type, or `unknown` when none is
+ * declared (the consumer can't know the response without the server). Path/method
+ * levels are mutable and fields are `readonly` — matching the inline registry, so
+ * the two are mutually assignable.
+ */
+type RouteInfoForOp<O extends OperationDef> = {
+    readonly params: Params<O["path"]>;
+    readonly query: OpQuery<O>;
+    readonly body: OpBody<O>;
+    readonly output: OpResponse<O>;
+};
+/** Re-key the name-keyed ops into the `path → method → RouteInfo` registry. */
+export type RegistryFor<C extends ContractShape> = {
+    [P in C[keyof C]["path"]]: {
+        [K in keyof C as C[K]["path"] extends P ? C[K]["method"] : never]: RouteInfoForOp<C[K]>;
+    };
+};
+/** The schema shape an op contributes to its handler context (mirrors inline `RouteSchema`). */
+type SchemaForOp<O extends OperationDef> = (O extends {
+    body: infer B extends StandardSchemaV1;
+} ? {
+    body: B;
+} : Record<never, never>) & (O extends {
+    query: infer Q extends StandardSchemaV1;
+} ? {
+    query: Q;
+} : Record<never, never>);
+/**
+ * The handler context for an op — identical to the inline `Context<Path, S>`, so a
+ * handler written for an inline route type-checks unchanged under `implement`
+ * (the graduation guarantee).
+ */
+export type ContextForOp<O extends OperationDef> = Context<O["path"], SchemaForOp<O> & RouteSchema>;
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * What a handler may return for an op. When the op declares a `response`, the return is constrained to
+ * that contract shape (or a raw `Response`) — so an `implement`ed backend can't drift from the response
+ * the contract's client was built against. With no `response` it's unconstrained (`unknown`), identical
+ * to before. Purely type-level — erased at compile time, zero runtime cost — and mirrors the inline
+ * route's `ResponseOf` constraint, so a handler graduates inline↔contract unchanged.
+ */
+type HandlerReturnForOp<O extends OperationDef> = O extends {
+    response: infer R extends StandardSchemaV1;
+} ? Response | InferOutput<R> : unknown;
+/** The handlers `implement` requires: one per operation, typed from the op's input + response contract. */
+export type HandlersFor<C extends ContractShape> = {
+    [K in keyof C]: (context: ContextForOp<C[K]>) => MaybePromise<HandlerReturnForOp<C[K]>>;
+};
+/**
+ * Define a standalone, versionable contract. Identity at runtime (it returns the
+ * contract for type inference via the `const` type parameter, which preserves the
+ * path/method literals) plus boot-time (L2) validation: each operation must use a
+ * known method, a path starting with `/`, and no two operations may share a
+ * `(method, path)`. Deeper path validation (param names, wildcard position) runs
+ * when the contract is `implement`ed.
+ */
+export declare function defineContract<const C extends ContractShape>(contract: C): C;
+type AnyFn = (...args: never[]) => unknown;
+/**
+ * The registry produced by `implement`: input from the contract op; `output` is the declared `response`
+ * contract when present (it wins — exactly as in the inline path), else the bound HANDLER's return — so
+ * the implemented server stays route-for-route identical to the equivalent inline server (the
+ * mode-conformance guarantee), and a contract-typed client and a `typeof app`-typed client agree.
+ */
+export type RegistryFromImpl<C extends ContractShape, H extends HandlersFor<C>> = {
+    [P in C[keyof C]["path"]]: {
+        [K in keyof C as C[K]["path"] extends P ? C[K]["method"] : never]: {
+            readonly params: Params<C[K]["path"]>;
+            readonly query: OpQuery<C[K]>;
+            readonly body: OpBody<C[K]>;
+            readonly output: C[K] extends {
+                response: infer R extends StandardSchemaV1;
+            } ? InferOutput<R> : H[K] extends AnyFn ? OutputOf<H[K]> : unknown;
+        };
+    };
+};
+/**
+ * Bind handlers to a contract, producing a real {@link Server} you can `.listen()`
+ * or `.fetch()`. Each op is registered through the same path as the inline
+ * builder, so the result is identical to writing the routes inline — handlers
+ * lift over **unchanged** ("graduation"), and body/query schemas validate at the
+ * request boundary exactly as in inline mode.
+ */
+export declare function implement<const C extends ContractShape, H extends HandlersFor<C>>(contract: C, handlers: H): Server<RegistryFromImpl<C, H>>;
+export {};
+//# sourceMappingURL=contract.d.ts.map

package/dist/server/contract.d.ts.map

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

package/dist/server/contract.js

@@ -0,0 +1,59 @@
+import { RouteConfigError } from "../errors.js";
+import { METHODS } from "../router/router.js";
+import { Server } from "./server.js";
+const METHOD_SET = new Set(METHODS);
+/**
+ * Define a standalone, versionable contract. Identity at runtime (it returns the
+ * contract for type inference via the `const` type parameter, which preserves the
+ * path/method literals) plus boot-time (L2) validation: each operation must use a
+ * known method, a path starting with `/`, and no two operations may share a
+ * `(method, path)`. Deeper path validation (param names, wildcard position) runs
+ * when the contract is `implement`ed.
+ */
+export function defineContract(contract) {
+    const seen = new Set();
+    for (const [name, op] of Object.entries(contract)) {
+        const method = op.method.toUpperCase();
+        if (!METHOD_SET.has(method)) {
+            throw new RouteConfigError("INVALID_METHOD", `operation "${name}": unsupported method "${op.method}"`);
+        }
+        if (op.path.length === 0 || op.path.charCodeAt(0) !== 47 /* "/" */) {
+            throw new RouteConfigError("INVALID_PATH", `operation "${name}": path must start with "/": "${op.path}"`);
+        }
+        const key = `${method} ${op.path}`;
+        if (seen.has(key)) {
+            throw new RouteConfigError("DUPLICATE_ROUTE", `duplicate operation route: ${key}`);
+        }
+        seen.add(key);
+    }
+    return contract;
+}
+/**
+ * Bind handlers to a contract, producing a real {@link Server} you can `.listen()`
+ * or `.fetch()`. Each op is registered through the same path as the inline
+ * builder, so the result is identical to writing the routes inline — handlers
+ * lift over **unchanged** ("graduation"), and body/query schemas validate at the
+ * request boundary exactly as in inline mode.
+ */
+export function implement(contract, handlers) {
+    const app = new Server();
+    for (const [name, op] of Object.entries(contract)) {
+        // body/query are validated at the request boundary; `response` is a type + introspection contract
+        // ONLY — never validated at runtime and never read on the request hot path (the lifecycle reads
+        // schema.body/query by name; the `bare`/bodyOnly/queryOnly fast-path gates ignore `response`). Built
+        // once here at bind time, not per request — it just carries a reference to the op's existing schema.
+        // A response-less op still yields `undefined`, byte-identical to before.
+        const schema = op.body !== undefined || op.query !== undefined || op.response !== undefined
+            ? {
+                ...(op.body !== undefined ? { body: op.body } : {}),
+                ...(op.query !== undefined ? { query: op.query } : {}),
+                ...(op.response !== undefined ? { response: op.response } : {}),
+            }
+            : undefined;
+        app.register(op.method, op.path, schema, handlers[name]);
+    }
+    // Runtime registered exactly the contract's routes through the inline path; the
+    // registry type is computed from the contract inputs + handler return types.
+    return app;
+}
+//# sourceMappingURL=contract.js.map

package/dist/server/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/server/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,OAAO,EAAe,MAAM,qBAAqB,CAAA;AAI1D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AA6GpC,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAC,OAAO,CAAC,CAAA;AAExD;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAgC,QAAW;IACvE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,CAAA;QACtC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,gBAAgB,CACxB,gBAAgB,EAChB,cAAc,IAAI,0BAA0B,EAAE,CAAC,MAAM,GAAG,CACzD,CAAA;QACH,CAAC;QACD,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,SAAS,EAAE,CAAC;YACnE,MAAM,IAAI,gBAAgB,CACxB,cAAc,EACd,cAAc,IAAI,iCAAiC,EAAE,CAAC,IAAI,GAAG,CAC9D,CAAA;QACH,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,EAAE,CAAC,IAAI,EAAE,CAAA;QAClC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,gBAAgB,CAAC,iBAAiB,EAAE,8BAA8B,GAAG,EAAE,CAAC,CAAA;QACpF,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACf,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAyBD;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CACvB,QAAW,EACX,QAAW;IAEX,MAAM,GAAG,GAAG,IAAI,MAAM,EAAE,CAAA;IACxB,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClD,kGAAkG;QAClG,gGAAgG;QAChG,qGAAqG;QACrG,qGAAqG;QACrG,yEAAyE;QACzE,MAAM,MAAM,GACV,EAAE,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,CAAC,QAAQ,KAAK,SAAS;YAC1E,CAAC,CAAC;gBACE,GAAG,CAAC,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnD,GAAG,CAAC,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtD,GAAG,CAAC,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAChE;YACH,CAAC,CAAC,SAAS,CAAA;QACf,GAAG,CAAC,QAAQ,CACV,EAAE,CAAC,MAAM,EACT,EAAE,CAAC,IAAI,EACP,MAAM,EACN,QAAQ,CAAC,IAAe,CAAgC,CACzD,CAAA;IACH,CAAC;IACD,gFAAgF;IAChF,6EAA6E;IAC7E,OAAO,GAAgD,CAAA;AACzD,CAAC"}

package/dist/server/cookies.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Cookie primitives — parse a request `Cookie` header, serialize a `Set-Cookie`, and sign/verify a
+ * value with HMAC-SHA256 via **WebCrypto** (`crypto.subtle`), so they're portable across Bun, Node,
+ * Deno, and workerd with no `node:crypto` dependency. Pure + runtime-agnostic: `c.cookies` (read) and
+ * `c.set.cookie` (write) build on these, and `@nifrajs/auth` builds sessions on top.
+ */
+/** Attributes for a `Set-Cookie`. `expires` is a `Date`; `maxAge` is in **seconds**. */
+export interface CookieOptions {
+    /** Lifetime in seconds. `0` (with a past `expires`) deletes the cookie. */
+    readonly maxAge?: number;
+    readonly expires?: Date;
+    readonly path?: string;
+    readonly domain?: string;
+    readonly secure?: boolean;
+    readonly httpOnly?: boolean;
+    readonly sameSite?: "strict" | "lax" | "none";
+    readonly partitioned?: boolean;
+}
+/** Parse a request `Cookie` header into a name→value map (values URL-decoded). Unparseable pairs are
+ * skipped rather than throwing — a junk `Cookie` header shouldn't fail the request.
+ *
+ * Hand-rolled index walk instead of `split(";")` + `trim()` chains: those allocated an array + up
+ * to three substrings per pair and showed up at ~6% of a realistic (auth + cookie) request. Same
+ * semantics, two slices per pair, no intermediate array. */
+export declare function parseCookies(header: string | null | undefined): Record<string, string>;
+/**
+ * Serialize a `Set-Cookie` header value. Pure — applies **no** security defaults (the caller, e.g.
+ * `c.set.cookie`, layers `HttpOnly`/`Secure`/`SameSite` on). Throws on an invalid cookie name, a
+ * header-injecting `Path`/`Domain`, a non-integer `maxAge`, or an oversized result — a serialization
+ * bug should fail loudly, not silently emit a cookie the browser drops.
+ */
+export declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+/** Append an HMAC-SHA256 signature to a value → `value.signature` (base64url). For signed cookies. */
+export declare function signValue(value: string, secret: string): Promise<string>;
+/**
+ * Verify a `value.signature` produced by {@link signValue} and return the value, or `null` if the
+ * signature is missing, malformed, or doesn't match. Verification is **constant-time**
+ * (`crypto.subtle.verify`), so a wrong signature can't be discovered byte-by-byte via timing.
+ */
+export declare function unsignValue(signed: string, secret: string): Promise<string | null>;
+//# sourceMappingURL=cookies.d.ts.map

package/dist/server/cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/server/cookies.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAA;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAC/B;AA2BD;;;;;4DAK4D;AAC5D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2CtF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAoChG;AAoCD,sGAAsG;AACtG,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAI9E;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASxF"}

package/dist/server/cookies.js

@@ -0,0 +1,181 @@
+/**
+ * Cookie primitives — parse a request `Cookie` header, serialize a `Set-Cookie`, and sign/verify a
+ * value with HMAC-SHA256 via **WebCrypto** (`crypto.subtle`), so they're portable across Bun, Node,
+ * Deno, and workerd with no `node:crypto` dependency. Pure + runtime-agnostic: `c.cookies` (read) and
+ * `c.set.cookie` (write) build on these, and `@nifrajs/auth` builds sessions on top.
+ */
+import { requireSecretBytes } from "../internal/secret.js";
+// RFC 6265 cookie-name token: visible ASCII minus separators/whitespace/controls.
+const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const MAX_COOKIE_BYTES = 4096; // browsers cap a cookie near 4 KB — reject oversized before the wire
+/** True if `v` contains a character illegal in a cookie attribute (control char or `;` separator) —
+ * the header-injection guard for dev-supplied `Path`/`Domain`. */
+const hasIllegalChar = (v) => {
+    for (let i = 0; i < v.length; i++) {
+        const code = v.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f || code === 0x3b /* ; */)
+            return true;
+    }
+    return false;
+};
+const safeDecode = (v) => {
+    // No `%` ⇒ nothing to decode — skip the call AND its try frame (profiled: cookie values are
+    // overwhelmingly plain; this was ~3% of a realistic request).
+    if (!v.includes("%"))
+        return v;
+    try {
+        return decodeURIComponent(v);
+    }
+    catch {
+        return v; // a malformed %-escape from a hostile/garbage cookie must not throw (it'd 500 the request)
+    }
+};
+/** Parse a request `Cookie` header into a name→value map (values URL-decoded). Unparseable pairs are
+ * skipped rather than throwing — a junk `Cookie` header shouldn't fail the request.
+ *
+ * Hand-rolled index walk instead of `split(";")` + `trim()` chains: those allocated an array + up
+ * to three substrings per pair and showed up at ~6% of a realistic (auth + cookie) request. Same
+ * semantics, two slices per pair, no intermediate array. */
+export function parseCookies(header) {
+    // Null-prototype: cookie NAMES come straight from the untrusted header, so a cookie named
+    // `constructor`/`__proto__`/`toString` must be an inert own key, not a shadow of a prototype
+    // member. Matches the query/form/params parsers (all `Object.create(null)`); values are always
+    // strings so global pollution was never possible, but this keeps the whole request-parse layer
+    // consistent and safe to treat as a plain dictionary.
+    const out = Object.create(null);
+    if (!header)
+        return out;
+    const len = header.length;
+    let pos = 0;
+    while (pos < len) {
+        let end = header.indexOf(";", pos);
+        if (end === -1)
+            end = len;
+        // trim() equivalent on the segment, without allocating the untrimmed slice
+        let start = pos;
+        while (start < end && header.charCodeAt(start) === 32)
+            start++;
+        let stop = end;
+        while (stop > start && header.charCodeAt(stop - 1) === 32)
+            stop--;
+        const eq = header.indexOf("=", start);
+        if (eq > start && eq < stop) {
+            // name: trim trailing spaces before '='; value: trim leading spaces after it
+            let nameEnd = eq;
+            while (nameEnd > start && header.charCodeAt(nameEnd - 1) === 32)
+                nameEnd--;
+            let valueStart = eq + 1;
+            while (valueStart < stop && header.charCodeAt(valueStart) === 32)
+                valueStart++;
+            if (nameEnd > start) {
+                const name = header.slice(start, nameEnd);
+                let value;
+                if (stop - valueStart >= 2 &&
+                    header.charCodeAt(valueStart) === 34 /* " */ &&
+                    header.charCodeAt(stop - 1) === 34) {
+                    value = header.slice(valueStart + 1, stop - 1);
+                }
+                else {
+                    value = header.slice(valueStart, stop);
+                }
+                out[name] = safeDecode(value);
+            }
+        }
+        pos = end + 1;
+    }
+    return out;
+}
+/**
+ * Serialize a `Set-Cookie` header value. Pure — applies **no** security defaults (the caller, e.g.
+ * `c.set.cookie`, layers `HttpOnly`/`Secure`/`SameSite` on). Throws on an invalid cookie name, a
+ * header-injecting `Path`/`Domain`, a non-integer `maxAge`, or an oversized result — a serialization
+ * bug should fail loudly, not silently emit a cookie the browser drops.
+ */
+export function serializeCookie(name, value, options = {}) {
+    if (!COOKIE_NAME.test(name)) {
+        throw new Error(`[nifra] invalid cookie name ${JSON.stringify(name)}: must be an RFC 6265 token`);
+    }
+    let str = `${name}=${encodeURIComponent(value)}`;
+    if (options.maxAge !== undefined) {
+        if (!Number.isInteger(options.maxAge)) {
+            throw new Error("[nifra] cookie maxAge must be an integer number of seconds");
+        }
+        str += `; Max-Age=${options.maxAge}`;
+    }
+    if (options.domain !== undefined) {
+        if (hasIllegalChar(options.domain))
+            throw new Error("[nifra] cookie Domain contains an illegal character");
+        str += `; Domain=${options.domain}`;
+    }
+    if (options.path !== undefined) {
+        if (hasIllegalChar(options.path))
+            throw new Error("[nifra] cookie Path contains an illegal character");
+        str += `; Path=${options.path}`;
+    }
+    if (options.expires !== undefined)
+        str += `; Expires=${options.expires.toUTCString()}`;
+    if (options.httpOnly === true)
+        str += "; HttpOnly";
+    if (options.secure === true)
+        str += "; Secure";
+    if (options.partitioned === true)
+        str += "; Partitioned";
+    if (options.sameSite !== undefined) {
+        str += `; SameSite=${options.sameSite === "strict" ? "Strict" : options.sameSite === "none" ? "None" : "Lax"}`;
+    }
+    if (str.length > MAX_COOKIE_BYTES) {
+        throw new Error(`[nifra] cookie ${JSON.stringify(name)} is ${str.length}B, over the ${MAX_COOKIE_BYTES}B limit`);
+    }
+    return str;
+}
+const TEXT = new TextEncoder();
+const importHmacKey = (secret) => {
+    // Reject a weak secret at the choke point both signing and verification flow through (so signed
+    // cookies AND @nifrajs/auth sessions, which delegate here via signValue/unsignValue, are covered).
+    requireSecretBytes(secret, "signed-cookie");
+    return crypto.subtle.importKey("raw", TEXT.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
+};
+const toBase64Url = (buf) => {
+    let bin = "";
+    for (const b of new Uint8Array(buf))
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+// Returns `Uint8Array<ArrayBuffer>` (not the generic `Uint8Array<ArrayBufferLike>`) so it satisfies
+// WebCrypto's `BufferSource` parameter under TS 5.7+'s typed-array generics.
+const fromBase64Url = (s) => {
+    try {
+        const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/"));
+        const bytes = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            bytes[i] = bin.charCodeAt(i);
+        return bytes;
+    }
+    catch {
+        return null; // not valid base64 — treat as a bad signature
+    }
+};
+/** Append an HMAC-SHA256 signature to a value → `value.signature` (base64url). For signed cookies. */
+export async function signValue(value, secret) {
+    const key = await importHmacKey(secret);
+    const sig = await crypto.subtle.sign("HMAC", key, TEXT.encode(value));
+    return `${value}.${toBase64Url(sig)}`;
+}
+/**
+ * Verify a `value.signature` produced by {@link signValue} and return the value, or `null` if the
+ * signature is missing, malformed, or doesn't match. Verification is **constant-time**
+ * (`crypto.subtle.verify`), so a wrong signature can't be discovered byte-by-byte via timing.
+ */
+export async function unsignValue(signed, secret) {
+    const dot = signed.lastIndexOf(".");
+    if (dot < 1)
+        return null; // no signature segment (or empty value)
+    const value = signed.slice(0, dot);
+    const sig = fromBase64Url(signed.slice(dot + 1));
+    if (sig === null)
+        return null;
+    const key = await importHmacKey(secret);
+    const ok = await crypto.subtle.verify("HMAC", key, sig, TEXT.encode(value));
+    return ok ? value : null;
+}
+//# sourceMappingURL=cookies.js.map

package/dist/server/cookies.js.map

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

package/dist/server/logger.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Structured, redacting logger. The framework logs through this interface so
+ * secrets/PII are scrubbed once, centrally (per the project's logging rule), not at
+ * each call site. Bring your own by passing `logger` to `server()`.
+ */
+export type LogFields = Record<string, unknown>;
+export interface Logger {
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+}
+/**
+ * Tunes redaction. Key-name redaction always runs; the rest is **opt-in**:
+ * - `keyParts` — extra case-insensitive key fragments, added to the built-in denylist.
+ * - `valuePatterns` — regexes matched against string **values** *and* the log message; each match is
+ *   replaced with the placeholder. This is the value-scanning hook for secrets that land in a value or
+ *   message (e.g. `err.message`), which key-name redaction can't catch. Off unless provided — the
+ *   default path does no value scanning, so it stays allocation-light. See {@link commonSecretPatterns}.
+ * - `placeholder` — the replacement string (default `[REDACTED]`).
+ */
+export interface RedactOptions {
+    readonly keyParts?: readonly string[];
+    readonly valuePatterns?: readonly RegExp[];
+    readonly placeholder?: string;
+}
+/**
+ * A conservative, high-signal set of patterns for {@link RedactOptions.valuePatterns} — opt in by
+ * passing it (or a subset) to `jsonLogger`/`redactLogFields`. Covers bearer tokens, JWTs, emails, and a
+ * few well-known key formats (Stripe, GitHub, AWS access-key ids). Chosen to minimize false positives;
+ * add your own (e.g. internal id formats) as needed. Every pattern is global so all matches are scrubbed.
+ */
+export declare const commonSecretPatterns: ReadonlyArray<RegExp>;
+/**
+ * Deep-copy `fields`, replacing values under sensitive keys with the placeholder; cycle-safe. With
+ * `options.valuePatterns`, also scans string values for those patterns (opt-in). Without options, this
+ * is pure key-name redaction (the long-standing default).
+ */
+export declare function redactLogFields(fields: LogFields, options?: RedactOptions): LogFields;
+/**
+ * The default logger: one redacted JSON object per line. `write` is injectable for tests or
+ * alternative sinks (defaults to stderr). `options` tunes redaction — pass `valuePatterns` (e.g.
+ * {@link commonSecretPatterns}) to also scrub secrets embedded in values + the message. Framework keys
+ * (`level`, `message`, `time`) always win over user fields of the same name.
+ */
+export declare function jsonLogger(write?: (line: string) => void, options?: RedactOptions): Logger;
+/** Discards everything — for tests, or when log output is handled elsewhere. */
+export declare const silentLogger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/server/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/server/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE/C,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;CACjD;AAsBD;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,MAAM,CAOtD,CAAA;AAqDD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAErF;AAMD;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,KAAK,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAoB,EAC7C,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM,CAkBR;AAID,gFAAgF;AAChF,eAAO,MAAM,YAAY,EAAE,MAK1B,CAAA"}

package/dist/server/logger.js

@@ -0,0 +1,125 @@
+/**
+ * Structured, redacting logger. The framework logs through this interface so
+ * secrets/PII are scrubbed once, centrally (per the project's logging rule), not at
+ * each call site. Bring your own by passing `logger` to `server()`.
+ */
+const REDACTED = "[REDACTED]";
+/**
+ * Field-name fragments whose values are replaced with `[REDACTED]` (case-insensitive
+ * substring match). Key-name redaction is the default + always on.
+ */
+const SENSITIVE_KEY_PARTS = [
+    "authorization",
+    "cookie",
+    "password",
+    "passwd",
+    "secret",
+    "token",
+    "apikey",
+    "api_key",
+    "api-key",
+    "credential",
+    "ssn",
+];
+/**
+ * A conservative, high-signal set of patterns for {@link RedactOptions.valuePatterns} — opt in by
+ * passing it (or a subset) to `jsonLogger`/`redactLogFields`. Covers bearer tokens, JWTs, emails, and a
+ * few well-known key formats (Stripe, GitHub, AWS access-key ids). Chosen to minimize false positives;
+ * add your own (e.g. internal id formats) as needed. Every pattern is global so all matches are scrubbed.
+ */
+export const commonSecretPatterns = [
+    /Bearer\s+[A-Za-z0-9._~+/-]+=*/gi, // Authorization: Bearer <token>
+    /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, // JWT (header.payload.signature)
+    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, // email
+    /\b[sprk]k_(?:live|test)_[A-Za-z0-9]{8,}/g, // Stripe-style secret/restricted keys
+    /\bgh[pousr]_[A-Za-z0-9]{20,}/g, // GitHub personal/OAuth/refresh tokens
+    /\bAKIA[0-9A-Z]{16}\b/g, // AWS access key id
+];
+// `String.replace` with a global regex replaces every match and is stateless across calls; a
+// non-global pattern would only scrub the first occurrence, so normalize to global once up front.
+const ensureGlobal = (re) => re.flags.includes("g") ? re : new RegExp(re.source, `${re.flags}g`);
+function buildConfig(options) {
+    const extra = options?.keyParts;
+    return {
+        keyParts: extra !== undefined && extra.length > 0
+            ? [...SENSITIVE_KEY_PARTS, ...extra.map((k) => k.toLowerCase())]
+            : SENSITIVE_KEY_PARTS,
+        valuePatterns: (options?.valuePatterns ?? []).map(ensureGlobal),
+        placeholder: options?.placeholder ?? REDACTED,
+    };
+}
+function isSensitiveKey(key, parts) {
+    const lower = key.toLowerCase();
+    return parts.some((part) => lower.includes(part));
+}
+function redactString(value, config) {
+    if (config.valuePatterns.length === 0)
+        return value; // default fast path: no value scanning
+    let out = value;
+    for (const pattern of config.valuePatterns)
+        out = out.replace(pattern, config.placeholder);
+    return out;
+}
+function redactValue(value, seen, config) {
+    if (typeof value === "string")
+        return redactString(value, config);
+    if (value === null || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return "[Circular]";
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((item) => redactValue(item, seen, config));
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+        // A sensitive key wins outright (don't scan it) — the whole value is replaced.
+        out[key] = isSensitiveKey(key, config.keyParts)
+            ? config.placeholder
+            : redactValue(val, seen, config);
+    }
+    return out;
+}
+/**
+ * Deep-copy `fields`, replacing values under sensitive keys with the placeholder; cycle-safe. With
+ * `options.valuePatterns`, also scans string values for those patterns (opt-in). Without options, this
+ * is pure key-name redaction (the long-standing default).
+ */
+export function redactLogFields(fields, options) {
+    return redactValue(fields, new WeakSet(), buildConfig(options));
+}
+function writeToStderr(line) {
+    process.stderr.write(`${line}\n`);
+}
+/**
+ * The default logger: one redacted JSON object per line. `write` is injectable for tests or
+ * alternative sinks (defaults to stderr). `options` tunes redaction — pass `valuePatterns` (e.g.
+ * {@link commonSecretPatterns}) to also scrub secrets embedded in values + the message. Framework keys
+ * (`level`, `message`, `time`) always win over user fields of the same name.
+ */
+export function jsonLogger(write = writeToStderr, options) {
+    const config = buildConfig(options); // normalize patterns once, reuse per entry
+    const emit = (level, message, fields) => {
+        const entry = fields === undefined
+            ? {}
+            : redactValue(fields, new WeakSet(), config);
+        entry.level = level;
+        entry.message = redactString(message, config); // scan the message too (no-op without valuePatterns)
+        entry.time = new Date().toISOString();
+        write(JSON.stringify(entry));
+    };
+    return {
+        debug: (message, fields) => emit("debug", message, fields),
+        info: (message, fields) => emit("info", message, fields),
+        warn: (message, fields) => emit("warn", message, fields),
+        error: (message, fields) => emit("error", message, fields),
+    };
+}
+const noop = () => undefined;
+/** Discards everything — for tests, or when log output is handled elsewhere. */
+export const silentLogger = {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+};
+//# sourceMappingURL=logger.js.map