@zerotal/core 1.0.0

package/src/support/cookie.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared cookie helpers.
+ *
+ * A single place to build a `Set-Cookie` value and to read a cookie off a
+ * request, so session drivers, CSRF, and "remember me" don't each re-implement
+ * the attribute assembly and header parsing (the 2026-07 review found the pair
+ * copied across four files). Keeping it here means a future change — a
+ * `__Host-` prefix, `SameSite=Strict`, a `Partitioned` attribute — happens once.
+ */
+
+export type SameSite = "Strict" | "Lax" | "None";
+
+export interface CookieOptions {
+  /** Cookie name. */
+  name: string;
+  /** Cookie value (caller is responsible for encoding if needed). */
+  value: string;
+  /** `Path` attribute. Defaults to `/`. */
+  path?: string;
+  /** `Max-Age` in seconds. Omit for a session cookie. `0` clears the cookie. */
+  maxAge?: number;
+  /** `SameSite` attribute. Defaults to `Lax`. */
+  sameSite?: SameSite;
+  /** Add the `HttpOnly` attribute. Defaults to `true` — pass `false` for cookies JS must read (e.g. XSRF-TOKEN). */
+  httpOnly?: boolean;
+  /** Add the `Secure` attribute. Defaults to `false`. */
+  secure?: boolean;
+  /** `Domain` attribute. Omitted when absent. */
+  domain?: string;
+}
+
+/**
+ * Build a `Set-Cookie` header value from structured options.
+ *
+ * @example
+ * buildCookie({ name: "session", value, maxAge: 86400, secure: true });
+ * // "session=…; Path=/; HttpOnly; SameSite=Lax; Max-Age=86400; Secure"
+ */
+export function buildCookie(options: CookieOptions): string {
+  const parts = [`${options.name}=${options.value}`, `Path=${options.path ?? "/"}`];
+  if (options.domain) parts.push(`Domain=${options.domain}`);
+  if (options.httpOnly ?? true) parts.push("HttpOnly");
+  parts.push(`SameSite=${options.sameSite ?? "Lax"}`);
+  if (options.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);
+  if (options.secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+/**
+ * Read a single cookie value off a request by name.
+ *
+ * Prefers Bun's native `request.cookies` (`Bun.CookieMap`, populated on
+ * `Bun.serve`-served requests) and falls back to parsing the `Cookie` header
+ * for synthetic requests (e.g. tests) where the native map is absent.
+ */
+export function readCookie(request: Request, name: string): string | undefined {
+  const cookies = (request as { cookies?: Bun.CookieMap }).cookies;
+  if (cookies) return cookies.get(name) ?? undefined;
+  return parseCookieHeader(request.headers.get("Cookie") ?? "", name);
+}
+
+/** Extract a single cookie value from a raw `Cookie` header string. */
+export function parseCookieHeader(header: string, name: string): string | undefined {
+  for (const part of header.split(";")) {
+    const eqIdx = part.indexOf("=");
+    if (eqIdx === -1) continue;
+    if (part.slice(0, eqIdx).trim() === name) {
+      return part.slice(eqIdx + 1).trim();
+    }
+  }
+  return undefined;
+}

package/src/support/crypto.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared cryptographic helpers.
+ *
+ * These exist so that constant-time comparison and SHA-256 hex digests are
+ * implemented exactly once. Auth, session, and crypt code must use these
+ * instead of re-implementing `timingSafeEqual` casts or hashing idioms —
+ * the 2026-07 code review found six independent copies of the compare and
+ * four of the digest, in two different idioms.
+ */
+import { timingSafeEqual } from "node:crypto";
+
+/**
+ * Constant-time string comparison.
+ *
+ * Returns `false` (rather than throwing) when lengths differ. Length is not
+ * secret for the token formats used across the framework (fixed-length
+ * hashes, hex digests, OTP codes), so the early return does not leak
+ * anything useful.
+ *
+ * @example
+ * if (!safeEqual(candidateHash, storedHash)) throw new InvalidTokenError();
+ */
+export function safeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ab.length !== bb.length) return false;
+  return timingSafeEqual(ab as unknown as Uint8Array, bb as unknown as Uint8Array);
+}
+
+/**
+ * SHA-256 digest of `input`, hex-encoded. Synchronous, via `Bun.CryptoHasher`.
+ *
+ * This is the canonical helper for token-hash storage (remember tokens,
+ * reset tokens, OTPs, PATs, recovery codes): store `sha256Hex(token)`,
+ * never the token itself.
+ */
+export function sha256Hex(input: string | Uint8Array): string {
+  return new Bun.CryptoHasher("sha256").update(input).digest("hex");
+}
+
+/**
+ * HMAC-SHA256 of `payload` under `key`, hex-encoded. Synchronous, via
+ * `Bun.CryptoHasher`.
+ *
+ * The canonical helper for keyed signing across the framework (signed URLs,
+ * snapshot checksums, signed upload paths). Pair it with {@link safeEqual} to
+ * verify — never compare digests with `===`. Use {@link sha256Hex} instead when
+ * hashing an unkeyed token for storage.
+ */
+export function hmacHex(payload: string | Uint8Array, key: string): string {
+  return new Bun.CryptoHasher("sha256", key).update(payload).digest("hex");
+}

package/src/support/deepMerge.ts

@@ -0,0 +1,117 @@
+/**
+ * Recursive object merge (lodash.merge-style): merges `override` onto `base`
+ * and returns a brand-new value, used by config factories and middleware option
+ * builders. See the notes below for the full merge semantics.
+ */
+
+// Semantics:
+//   • Nested PLAIN objects merge key-by-key, recursively — a partial override of a
+//     deep object keeps the base's other keys, at any depth.
+//   • Arrays and primitives REPLACE wholesale (see "Arrays" below).
+//   • Class instances, Dates, Maps, Sets, RegExps, functions, etc. are treated as
+//     atomic values: replaced wholesale and passed through by reference (never
+//     merged into and never cloned), so their prototype and identity survive.
+//   • `undefined` values in `override` are ignored, so a partial override never
+//     blanks out a default.
+//   • Neither `base` nor `override` is mutated, and the result shares no mutable
+//     plain structure with either: every plain object and array in the result is a
+//     fresh copy. This means mutating the merged config can never corrupt the
+//     module-level `defaults` object a factory merges onto, nor the options object
+//     the caller passed in.
+//   • Prototype-polluting keys (`__proto__`, `constructor`, `prototype`) are
+//     skipped, so merging untrusted input (env files, parsed JSON) is safe.
+//
+// ── Arrays ────────────────────────────────────────────────────────────────────
+// Arrays are REPLACED as a whole — never concatenated, de-duplicated, or merged
+// element-by-element:
+//
+//   deepMerge({ hosts: ["a", "b"] }, { hosts: ["c"] })  →  { hosts: ["c"] }
+//   // NOT ["a","b","c"], and NOT ["c","b"].
+//
+// This is deliberate: there is no surprise-free universal rule for merging two
+// arrays (append? replace-by-index? union?), so the override is given the final
+// say. Guidance when designing config/middleware option shapes:
+//   • If an option is a list users should be able to EXTEND, expose it as a plain
+//     array and document that providing it replaces the default outright. Tell
+//     users to spread the default themselves, e.g.
+//     `SomeConfig({ hosts: [...DEFAULT_HOSTS, "extra"] })`.
+//   • If you need a keyed, extensible sub-config, model it as a nested OBJECT keyed
+//     by name (like `cache.stores` or `storage.disks`) rather than an array.
+//     Objects merge, so a user can add one key without losing the built-ins.
+//   • The replacement array is deep-cloned, so mutating the merged result never
+//     reaches back into the value the caller passed in.
+
+/** Keys that must never be copied across — they can pollute `Object.prototype`. */
+const _UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/**
+ * A *plain* object: a `{}`-style record whose prototype is `Object.prototype` or
+ * `null`. Class instances, arrays, Dates, Maps, etc. are intentionally excluded so
+ * deepMerge treats them as atomic values instead of recursing into them.
+ */
+function _isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Deep-clone plain objects and arrays; return everything else (primitives,
+ * functions, class instances, Dates, …) by reference. Keeps merged results
+ * structurally isolated from their inputs without breaking non-plain values.
+ */
+function _clone<T>(value: T): T {
+  if (Array.isArray(value)) return value.map((el) => _clone(el)) as unknown as T;
+  if (_isPlainObject(value)) {
+    const out: Record<string, unknown> = {};
+    for (const key in value) {
+      if (!Object.prototype.hasOwnProperty.call(value, key)) continue;
+      if (_UNSAFE_KEYS.has(key)) continue;
+      out[key] = _clone((value as Record<string, unknown>)[key]);
+    }
+    return out as unknown as T;
+  }
+  return value;
+}
+
+/**
+ * Deep-merge `override` onto `base`. Used by config factories (`AppConfig`,
+ * `CacheConfig`, …) and `BaseMiddleware.with()` so user overrides change only the
+ * keys they specify — at any depth — leaving every other default in place.
+ *
+ * Nested plain objects merge recursively; arrays, primitives, and class instances
+ * replace wholesale; `undefined` overrides are ignored; and the result is a fresh
+ * value that shares no mutable plain structure with `base` or `override`. See the
+ * file header for full semantics, including the array-replacement rule.
+ *
+ * @example
+ * deepMerge(
+ *   { cors: { origin: "*", credentials: false }, port: 3000 },
+ *   { cors: { credentials: true } },
+ * );
+ * // → { cors: { origin: "*", credentials: true }, port: 3000 }
+ *
+ * @example
+ * // Arrays replace — they are not concatenated:
+ * deepMerge({ tags: ["a", "b"] }, { tags: ["c"] });
+ * // → { tags: ["c"] }
+ */
+export function deepMerge<T extends object>(base: T, override: Partial<T>): T {
+  const result = _clone(base) as T;
+  for (const key in override) {
+    if (!Object.prototype.hasOwnProperty.call(override, key)) continue;
+    if (_UNSAFE_KEYS.has(key)) continue;
+    const overrideValue = override[key];
+    if (overrideValue === undefined) continue;
+    const baseValue = (result as Record<string, unknown>)[key];
+    if (_isPlainObject(overrideValue) && _isPlainObject(baseValue)) {
+      (result as Record<string, unknown>)[key] = deepMerge(
+        baseValue,
+        overrideValue as Partial<typeof baseValue>,
+      );
+    } else {
+      (result as Record<string, unknown>)[key] = _clone(overrideValue);
+    }
+  }
+  return result;
+}

package/src/support/env.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared deployment-environment predicates.
+ *
+ * These exist so "are we in production?" is answered exactly once. The 2026-07
+ * code review found two divergent copies — one accepting only "production",
+ * one also accepting "prod" — which meant APP_ENV=prod or staging deployments
+ * served full stack traces on 500s from one code path but not the other.
+ */
+
+/**
+ * Whether `env` names a production-like deployment environment — one where
+ * debug output (stack traces, dev error pages, open health details) must be
+ * suppressed. Accepts `"production"`, `"prod"`, and `"staging"`,
+ * case-insensitively.
+ *
+ * @example
+ * if (!isProdLike(Bun.env["APP_ENV"] ?? "")) return renderDevErrorPage(error);
+ */
+export function isProdLike(env: string): boolean {
+  const normalized = env.trim().toLowerCase();
+  return normalized === "production" || normalized === "prod" || normalized === "staging";
+}
+
+/**
+ * Whether `env` names an environment where dev-only surfaces (the devtools
+ * trace inspector, the monitor panel's default open access, dev error pages)
+ * may be exposed without authentication.
+ *
+ * Only *explicitly* non-production environments qualify. Unset or unknown
+ * values return `false` — the gate fails closed, so a production deploy that
+ * forgets to set `APP_ENV` (or sets `staging`) never accidentally exposes an
+ * internal surface. This is the inverse-but-stricter companion to
+ * {@link isProdLike}: `isProdLike("")` is `false`, but so is this.
+ */
+export function isDevSurfaceAllowed(env: string): boolean {
+  const n = env.trim().toLowerCase();
+  return n === "development" || n === "dev" || n === "local" || n === "test" || n === "testing";
+}
+
+/**
+ * Environment variable the dev orchestrator sets on the server it supervises.
+ * @internal
+ */
+export const DEV_WORKER_ENV_VAR = "ZT_DEV";
+
+/**
+ * Whether *this process* may expose dev-only surfaces — the stack-trace error
+ * page, the trace inspector, an open monitor panel.
+ *
+ * Two things qualify a process, and both are needed because they answer
+ * different questions:
+ *
+ *   - `serve --dev` supervises this process. The orchestrator only ever runs
+ *     from a developer's terminal (it watches the filesystem and rebundles
+ *     assets — nothing a deployment does), so its worker is a dev machine by
+ *     construction. This is the case that carries dev mode, because `APP_ENV`
+ *     cannot: `setAppEnv()` overwrites it with a *runtime mode* (`web`,
+ *     `worker`, `console`) before the app boots, so by the time any gate reads
+ *     it, whatever deployment name the developer configured is gone.
+ *
+ *   - `APP_ENV` still names an explicitly non-production environment. This
+ *     covers processes started outside the CLI — the test harness, and any
+ *     embedder that sets `APP_ENV` itself rather than through `setAppEnv()`.
+ *
+ * Anything else fails closed, so a production deploy that sets no `APP_ENV`
+ * exposes nothing.
+ */
+export function devSurfacesEnabled(): boolean {
+  if (Bun.env[DEV_WORKER_ENV_VAR] === "1") return true;
+  return isDevSurfaceAllowed(Bun.env["APP_ENV"] ?? "");
+}

package/src/support/network.ts

@@ -0,0 +1,79 @@
+/**
+ * This machine's address on the local network, so a starting server can print a
+ * URL that other devices can actually open.
+ *
+ * `http://localhost` only ever reaches the machine serving it. Opening the app
+ * on a phone means knowing this box's LAN address, and hunting for it with
+ * `ipconfig` is the kind of thing a dev server should just tell you.
+ */
+import { networkInterfaces } from "node:os";
+
+/** The shape read off each interface — narrowed so tests can pass plain objects. */
+type InterfaceInfo = {
+  address: string;
+  /** `"IPv4"` from Bun and Node's `os` module; some runtimes report the number `4`. */
+  family: string | number;
+  internal: boolean;
+};
+
+/** An interface table, as returned by `os.networkInterfaces()`. */
+type Interfaces = Record<string, readonly InterfaceInfo[] | undefined>;
+
+/**
+ * Adapters belonging to a virtual machine, container runtime, or VPN rather than
+ * to the network the developer's phone is on. They hold real, non-internal IPv4
+ * addresses — a Windows box with WSL and Hyper-V reports several — so they are
+ * ranked last rather than dropped: on a machine that has nothing else, a
+ * reachable address still beats none at all.
+ */
+const VIRTUAL_ADAPTER =
+  /vethernet|virtualbox|vmware|hyper-?v|wsl|docker|tailscale|zerotier|utun|veth|br-|tun\d|tap\d/i;
+
+/**
+ * The best guess at this machine's LAN address, or `undefined` when it is on no
+ * network at all (an offline laptop, most containers).
+ *
+ * @example
+ * const host = localNetworkAddress();
+ * console.log(host ? `http://${host}:3000` : "no network");
+ */
+export function localNetworkAddress(): string | undefined {
+  return _pickAddress(networkInterfaces());
+}
+
+// ── Private ──────────────────────────────────────────────────────────────────
+
+/**
+ * The choice itself, over an injected interface table.
+ *
+ * @internal Exported so the ranking can be tested against machines this one is not.
+ */
+export function _pickAddress(interfaces: Interfaces): string | undefined {
+  let best: { address: string; rank: number } | undefined;
+
+  for (const [adapter, addresses] of Object.entries(interfaces)) {
+    for (const info of addresses ?? []) {
+      if (info.internal) continue;
+      if (info.family !== "IPv4" && info.family !== 4) continue;
+      // 169.254.x.x is the address an adapter gives itself when DHCP never
+      // answered: the interface is up, but on no network anyone can reach.
+      if (info.address.startsWith("169.254.")) continue;
+
+      const rank = (VIRTUAL_ADAPTER.test(adapter) ? 10 : 0) + _scopeRank(info.address);
+      if (!best || rank < best.rank) best = { address: info.address, rank };
+    }
+  }
+
+  return best?.address;
+}
+
+/** Lower is better: the ranges a home or office LAN actually hands out come first. */
+function _scopeRank(address: string): number {
+  if (address.startsWith("192.168.")) return 0;
+  if (address.startsWith("10.")) return 1;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(address)) return 2;
+  // 100.64–127.x is carrier-grade NAT space, which is how Tailscale and similar
+  // overlays address a machine — reachable, but not from the phone on this Wi-Fi.
+  if (/^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(address)) return 4;
+  return 3;
+}

package/src/support/port.ts

@@ -0,0 +1,197 @@
+/**
+ * Port availability, and the OS lookups behind `serve`'s busy-port prompt.
+ *
+ * `Bun.serve()` throws a bare `EADDRINUSE` when something already holds the
+ * port, which tells a developer nothing about *what* holds it or how to get it
+ * back. These helpers answer both questions before the server tries to bind.
+ */
+
+/**
+ * Environment variable marking a child process that inherits an already-resolved
+ * port from its supervisor. Such a process must never prompt: its stdin belongs
+ * to the parent (the dev worker reads reload signals on it), so a prompt there
+ * would wait forever on input that never arrives.
+ *
+ * @internal
+ */
+export const PORT_RESOLVED_ENV_VAR = "ZT_PORT_RESOLVED";
+
+/** A process holding a port: its pid, and its executable name when discoverable. */
+export type PortOwner = {
+  pid: number;
+  /** e.g. `bun.exe`, `node`. Undefined when the platform lookup came up empty. */
+  name?: string;
+};
+
+/**
+ * Whether `port` can be bound right now.
+ *
+ * Binds and immediately releases, which is the only answer that matches what
+ * `Bun.serve()` will do — a connect probe would miss a socket bound to a
+ * different interface. The default hostname mirrors `Bun.serve()`'s own, so a
+ * port this reports as free is one the server can actually take.
+ *
+ * @example
+ * if (!(await isPortAvailable(3000))) console.log("something is already there");
+ */
+export async function isPortAvailable(port: number, hostname = "0.0.0.0"): Promise<boolean> {
+  try {
+    const probe = Bun.listen({ hostname, port, socket: { data(): void {} } });
+    probe.stop(true);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Poll until `port` frees up, giving up after `timeoutMs`.
+ *
+ * Returns `true` as soon as the port is bindable, `false` on timeout. This is
+ * the restart case: a server that has just been signalled still holds its
+ * socket for a moment after the signal is delivered.
+ */
+export async function waitForPort(port: number, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (await isPortAvailable(port)) return true;
+    if (Date.now() >= deadline) return false;
+    await Bun.sleep(100);
+  }
+}
+
+/**
+ * The first bindable port at or after `start`, or `undefined` when `attempts`
+ * consecutive ports are all taken (or the scan runs past 65535).
+ *
+ * @example
+ * const port = (await findAvailablePort(3001)) ?? 0; // 0 lets the OS choose
+ */
+export async function findAvailablePort(start: number, attempts = 20): Promise<number | undefined> {
+  for (let port = start; port < start + attempts && port <= 65535; port++) {
+    if (await isPortAvailable(port)) return port;
+  }
+  return undefined;
+}
+
+/**
+ * The process listening on `port`, or `undefined` when it cannot be identified.
+ *
+ * Identification is best-effort and shells out to the platform's socket table
+ * (`netstat` on Windows, `lsof` elsewhere), so it can come up empty on a
+ * stripped-down container or for a socket owned by another user. Callers must
+ * treat `undefined` as "unknown", not "nothing is listening".
+ */
+export async function findPortOwner(port: number): Promise<PortOwner | undefined> {
+  const pid =
+    process.platform === "win32"
+      ? _parseNetstat(await _capture(["netstat", "-ano", "-p", "TCP"]), port)
+      : _parseFirstPid(await _capture(["lsof", "-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"]));
+
+  if (pid === undefined) return undefined;
+  const name = await _processName(pid);
+  return name === undefined ? { pid } : { pid, name };
+}
+
+/**
+ * End the process `pid`, returning whether it is gone afterwards.
+ *
+ * Elsewhere this is SIGTERM first, escalating to SIGKILL only if the process is
+ * still alive a beat later, so a server gets to run its shutdown hooks. Windows
+ * has no signals — `taskkill /F` is the only way to end another process, and it
+ * is always abrupt.
+ */
+export async function stopProcess(pid: number): Promise<boolean> {
+  if (process.platform === "win32") {
+    try {
+      const killer = Bun.spawn(["taskkill", "/PID", String(pid), "/F"], {
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+      return (await killer.exited) === 0;
+    } catch {
+      return false;
+    }
+  }
+
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    // ESRCH (already gone) counts as success; EPERM does not.
+    return !_isAlive(pid);
+  }
+
+  for (let waited = 0; waited < 1_500; waited += 50) {
+    if (!_isAlive(pid)) return true;
+    await Bun.sleep(50);
+  }
+
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {
+    return !_isAlive(pid);
+  }
+  await Bun.sleep(100);
+  return !_isAlive(pid);
+}
+
+// ── Private ──────────────────────────────────────────────────────────────────
+
+/** Whether the process still exists. Signal 0 checks without delivering anything. */
+function _isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Run a command and return its stdout, or "" if it cannot be run at all. */
+async function _capture(command: string[]): Promise<string> {
+  try {
+    const proc = Bun.spawn(command, { stdin: "ignore", stdout: "pipe", stderr: "ignore" });
+    const output = await new Response(proc.stdout).text();
+    await proc.exited;
+    return output;
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Pull the listening pid for `port` out of `netstat -ano` output, whose rows are
+ * `TCP  <local>  <foreign>  <state>  <pid>` with the local address written as
+ * `0.0.0.0:3000` or `[::]:3000`.
+ */
+function _parseNetstat(output: string, port: number): number | undefined {
+  for (const line of output.split("\n")) {
+    const columns = line.trim().split(/\s+/);
+    if (columns.length < 5) continue;
+    const [protocol, local, , state, pid] = columns;
+    if (!protocol?.toUpperCase().startsWith("TCP")) continue;
+    if (state?.toUpperCase() !== "LISTENING") continue;
+    if (!local?.endsWith(`:${port}`)) continue;
+    const parsed = Number(pid);
+    if (Number.isInteger(parsed) && parsed > 0) return parsed;
+  }
+  return undefined;
+}
+
+/** First pid from newline-separated output (`lsof -t` prints one per line). */
+function _parseFirstPid(output: string): number | undefined {
+  for (const line of output.split("\n")) {
+    const parsed = Number(line.trim());
+    if (Number.isInteger(parsed) && parsed > 0) return parsed;
+  }
+  return undefined;
+}
+
+/** The executable name for `pid`, so the prompt can say more than a number. */
+async function _processName(pid: number): Promise<string | undefined> {
+  if (process.platform === "win32") {
+    const output = await _capture(["tasklist", "/FI", `PID eq ${pid}`, "/NH", "/FO", "CSV"]);
+    return /^"([^"]+)"/.exec(output.trim())?.[1];
+  }
+  return (await _capture(["ps", "-p", String(pid), "-o", "comm="])).trim() || undefined;
+}