@zerotal/core 1.8.1 → 1.10.0

package/src/doctor/throttleIdentity.ts

@@ -0,0 +1,118 @@
+/**
+ * Can the rate limiter tell two people apart?
+ *
+ * `ThrottleMiddleware` keys its buckets on the client IP, and resolves that IP
+ * from the socket address unless `trustedProxies` says how many proxies sit in
+ * front of the app. That default is right: `X-Forwarded-For` is written by the
+ * client, and trusting it without being told how deep the real value sits is how a
+ * limiter is bypassed with one header.
+ *
+ * But behind a reverse proxy the socket address is `127.0.0.1` — for every request
+ * ever made. Every visitor shares one bucket per form, and the middleware inverts
+ * into the thing it was installed to prevent: one attacker making twenty bad
+ * sign-ins a minute locks the entire staff out of the console, and five
+ * registrations in five minutes stops anybody in the world from creating an
+ * account. A limiter that cannot tell two people apart is a denial-of-service tool
+ * aimed at its own users.
+ *
+ * Nothing observable says this is happening. The proxy goes in, everything works,
+ * and the limiter quietly stops distinguishing people. The docblock on the option
+ * explains it, but the option is read while writing middleware and the mistake is
+ * made while writing a Caddyfile — so the two never meet. That gap is what this
+ * check closes.
+ *
+ * @module
+ */
+import type { Application } from "../application/Application.ts";
+import { ThrottleMiddleware, _isIpDerived } from "../middleware/ThrottleMiddleware.ts";
+import { Router } from "../router/Router.ts";
+
+/** A registered throttle and how it decides who is who. */
+export interface ThrottleIdentity {
+  /** The middleware class name, as it appears in a pipeline listing. */
+  name: string;
+  /** Where it is registered — `global`, or the route it guards. */
+  where: string;
+  /** Whether it resolves identity from a client-supplied header chain. */
+  trustsProxies: boolean;
+  /** Whether the app replaced IP-keying with its own resolver. */
+  customKey: boolean;
+}
+
+/** Whether a middleware class is `ThrottleMiddleware` or one of its `.with()` subclasses. */
+function isThrottle(cls: unknown): boolean {
+  if (typeof cls !== "function") return false;
+  if (cls === ThrottleMiddleware) return true;
+  return Object.prototype.isPrototypeOf.call(ThrottleMiddleware, cls);
+}
+
+/**
+ * Read a throttle's configured identity strategy.
+ *
+ * `.with()` applies its options in the constructor, so the only way to see them is
+ * to build one. That is safe here — the constructor merges `app.throttle` config
+ * over the defaults and does nothing else — and it is also the only way to observe
+ * the config layer, which can set `trustedProxies` for every throttle at once.
+ */
+function readIdentity(cls: unknown, where: string): ThrottleIdentity | null {
+  try {
+    const instance = new (cls as new () => unknown)() as {
+      options?: { trustedProxies?: number; keyResolver?: unknown };
+    };
+    const options = instance.options ?? {};
+    return {
+      name: (cls as { name?: string }).name || "ThrottleMiddleware",
+      where,
+      trustsProxies: typeof options.trustedProxies === "number" && options.trustedProxies > 0,
+      // A resolver that keys on the client address is not an exemption — it is
+      // exactly the case this check exists for. `RateLimiter`'s `.byIp()`,
+      // `.byUser()` and `.byApiKey()` all mark themselves, so the named-limiter API
+      // stops slipping past the audit that covers the middleware it builds on.
+      customKey: typeof options.keyResolver === "function" && !_isIpDerived(options.keyResolver),
+    };
+  } catch {
+    // A middleware that will not construct is a different problem, and not one
+    // the doctor should report as a rate-limiting finding.
+    return null;
+  }
+}
+
+/**
+ * Every throttle registered in this app, global and per-route.
+ *
+ * @param app - The booted application.
+ */
+export function registeredThrottles(app: Application): ThrottleIdentity[] {
+  const found: ThrottleIdentity[] = [];
+
+  for (const cls of app.globalMiddleware ?? []) {
+    if (!isThrottle(cls)) continue;
+    const identity = readIdentity(cls, "global");
+    if (identity) found.push(identity);
+  }
+
+  try {
+    for (const route of Router.routes.values()) {
+      for (const cls of route.middleware ?? []) {
+        if (!isThrottle(cls)) continue;
+        const identity = readIdentity(cls, `${route.method} ${route.path}`);
+        if (identity) found.push(identity);
+      }
+    }
+  } catch {
+    // No compiled router — a console-only app, or a test harness. Global
+    // middleware alone is still worth reporting on.
+  }
+
+  return found;
+}
+
+/**
+ * The throttles that will key every visitor to the same bucket behind a proxy.
+ *
+ * A custom `keyResolver` is excluded: an app that keys on a user id or an API key
+ * has already decided identity for itself, and this check has nothing to add.
+ */
+export function throttlesKeyedOnSocket(app: Application): ThrottleIdentity[] {
+  return registeredThrottles(app).filter((t) => !t.trustsProxies && !t.customKey);
+}

package/src/errors/RuntimeMismatchError.ts

@@ -0,0 +1,21 @@
+/**
+ * The error raised when a project has two Bun runtimes in it — the one this
+ * process is executing under, and a different one installed in `node_modules`.
+ */
+import { ZerotalError } from "./ZerotalError.ts";
+import type { RuntimeMismatch } from "../support/runtime.ts";
+
+/**
+ * Raised by `startZerotal()` when the running Bun and the installed Bun disagree.
+ *
+ * Carries both versions in `context` so a harness can report the disagreement
+ * rather than re-deriving it from the message.
+ */
+export class RuntimeMismatchError extends ZerotalError {
+  constructor(
+    message: string,
+    public readonly mismatch: RuntimeMismatch,
+  ) {
+    super(message, "E_RUNTIME_MISMATCH", 500, { ...mismatch });
+  }
+}

package/src/errors/index.ts

@@ -31,6 +31,7 @@ export {
 } from "./HttpError.ts";
 export { ValidationError } from "./ValidationError.ts";
 export { ConfigError } from "./ConfigError.ts";
+export { RuntimeMismatchError } from "./RuntimeMismatchError.ts";
 export { BootCheckError } from "../application/BootDoctor.ts";
 export type { BootCheckFailure } from "../application/BootDoctor.ts";
 export { ConfigValidationError } from "../config/validation.ts";

package/src/events/Emitter.ts

@@ -14,7 +14,11 @@ type ListenerClass<T extends object> = new (...args: unknown[]) => {
   retryDelay?: number;
 };
 
-/** A listener that opts into deferred execution by declaring a `queue` target. */
+/**
+ * A listener that opts into deferred execution by declaring a `queue` target.
+ *
+ * @internal
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the event payload type is listener-specific and not known at this boundary.
 export interface QueuedListener<T = any> {
   queue: boolean | string;

package/src/health/Health.ts

@@ -149,20 +149,20 @@ export const Health = new HealthRegistry();
 /** The health config, authored under the `health` key of `config/app.ts`. */
 export interface HealthConfigShape {
   /** Serve the endpoint. Default: on outside production, off in production. */
-  enabled?: boolean;
+  enabled?: boolean | undefined;
   /** Route path. Default: `/health`. */
-  path?: string;
+  path?: string | undefined;
   /** Shared secret. Required in production; supplied via `?key=` or `X-Health-Key`. */
-  secret?: string;
+  secret?: string | undefined;
   /** Include per-check details. Set false for a bare `{ status }` body. Default: true. */
-  showDetails?: boolean;
+  showDetails?: boolean | undefined;
 }
 
 /** The health config after defaults and back-compat have been applied. */
 export interface ResolvedHealthConfig {
   enabled: boolean;
   path: string;
-  secret?: string;
+  secret?: string | undefined;
   showDetails: boolean;
 }
 

package/src/helpers/html.ts

@@ -5,6 +5,8 @@
  * set (`&` `<` `>` `"` `'`, emitting `&#x27;` for the apostrophe). Safe for
  * both text content and double-quoted attribute values; both JSX runtimes and
  * the docs app render through it, so it runs on every SSR text child.
+ *
+ * @internal
  */
 export function escapeHtml(value: string): string {
   return Bun.escapeHTML(value);

package/src/helpers/index.ts

@@ -298,5 +298,6 @@ export { markdownPage, type BunMarkdownOptions } from "./markdown.ts";
 // must not carry private copies.
 export { escapeHtml } from "./html.ts";
 export { pluralize, singularize, tableNameFor } from "../support/str.ts";
-export { deepMerge } from "../support/deepMerge.ts";
+export { deepMerge, definedOnly } from "../support/deepMerge.ts";
+export type { Resolved } from "../support/deepMerge.ts";
 export { parseCookieHeader } from "../support/cookie.ts";

package/src/helpers/markdown.ts

@@ -8,7 +8,11 @@ export function markdownExtractTitle(content: string): string | undefined {
   return content.match(/^#{1,2}\s+(.+)$/m)?.[1]?.trim();
 }
 
-/** Minimal HTML shell for rendered markdown pages. */
+/**
+ * Minimal HTML shell for rendered markdown pages.
+ *
+ * @internal
+ */
 export function markdownPage(title: string, body: string): string {
   return `<html lang="en">
 <head>
@@ -44,6 +48,15 @@ ${body}
 /**
  * Options for `Bun.markdown.html()`. bun-types exposes the options type only inside
  * its `markdown` namespace; this is the named, exported equivalent the framework uses.
+ *
+ * Its optional properties stay `?: T` rather than `?: T | undefined`, unlike the
+ * framework's own option shapes. This one is not an option shape, it is a *mirror* of
+ * somebody else's signature, and a mirror that is wider than what it reflects stops
+ * being assignable to it — the value built here is handed straight to
+ * `Bun.markdown.html()`.
+ *
+ * @exact-optional-ignore
+ * @internal
  */
 export interface BunMarkdownOptions {
   tables?: boolean;

package/src/helpers/pageElements.ts

@@ -8,6 +8,8 @@
  * @param last - The last page number.
  * @param each - How many page links to show on each side of the current page (default `1`).
  * @returns Page numbers interleaved with `'...'` for elided ranges.
+ *
+ * @internal
  */
 export function pageElements(current: number, last: number, each = 1): (number | "...")[] {
   if (last <= 1) return [1];

package/src/http/HttpClient.ts

@@ -9,7 +9,11 @@ import { FrameworkEvents, OutgoingRequestCompleted } from "../events/FrameworkEv
 /** An HTTP request method. */
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
 
-/** A fake response definition matched by URL while `Http.fake()` is active. */
+/**
+ * A fake response definition matched by URL while `Http.fake()` is active.
+ *
+ * @internal
+ */
 export interface FakeStub {
   /** URL to match — exact string or glob-style `*` wildcard. */
   url: string;

package/src/http/UploadedFile.ts

@@ -19,9 +19,9 @@ export type StorageDisk = Pick<StorageDriver, "url"> & {
  */
 export interface FileValidationOptions {
   /** Maximum allowed size in bytes. */
-  maxSize?: number;
+  maxSize?: number | undefined;
   /** Allowed MIME types — e.g. `['image/jpeg', 'image/png', 'application/pdf']`. */
-  mimes?: string[];
+  mimes?: string[] | undefined;
 }
 
 /**

package/src/http/Uri.ts

@@ -40,7 +40,11 @@ interface UriParts {
   fragment?: string;
 }
 
-/** Read-only view over a URI's query string, returned by `Uri.query()`. */
+/**
+ * Read-only view over a URI's query string, returned by `Uri.query()`.
+ *
+ * @internal
+ */
 export interface UriQueryString {
   /** All query parameters as a plain object. */
   all(): Record<string, QueryValue>;

package/src/http/negotiate.ts

@@ -17,7 +17,11 @@ const ANSI: Record<string, string> = {
   dim: "\x1b[2m",
 };
 
-/** A supported ANSI text color for CLI output. */
+/**
+ * A supported ANSI text color for CLI output.
+ *
+ * @internal
+ */
 export type AnsiColor = "red" | "green" | "yellow" | "blue" | "cyan" | "dim";
 
 // ── Channel detection ──────────────────────────────────────────────────────────

package/src/http/originGuard.ts

@@ -36,6 +36,8 @@
  *   return new Response('Forbidden origin', { status: 403 });
  * }
  * ```
+ *
+ * @internal
  */
 export function isAllowedOrigin(request: Request, allowedOrigins: string[] = []): boolean {
   const origin = request.headers.get("origin");

package/src/http/sniffContentType.ts

@@ -65,7 +65,11 @@ export const FALLBACK_CONTENT_TYPE = "application/octet-stream";
 /** Extension stored when the bytes match nothing known. */
 export const FALLBACK_EXTENSION = "bin";
 
-/** What {@link sniffContentType} determined about a file. */
+/**
+ * What {@link sniffContentType} determined about a file.
+ *
+ * @internal
+ */
 export interface SniffedType {
   /** The detected media type, or {@link FALLBACK_CONTENT_TYPE} when unrecognised. */
   contentType: string;
@@ -88,6 +92,8 @@ export interface SniffedType {
  *
  * @example
  * const { contentType, extension } = sniffContentType(await file.bytes());
+ *
+ * @internal
  */
 export function sniffContentType(bytes: Uint8Array): SniffedType {
   for (const sig of SIGNATURES) {

package/src/index.ts

@@ -162,7 +162,8 @@ export {
 export { config } from "./helpers/config.ts";
 export { pluralize, singularize, snakeCase, camelCase, tableNameFor } from "./support/str.ts";
 export { deepMerge } from "./support/deepMerge.ts";
-export type { DeepPartial } from "./support/deepMerge.ts";
+// `definedOnly` is a helper, not kernel surface — it lives on `@zerotal/core/helpers`.
+export type { DeepPartial, Resolved } from "./support/deepMerge.ts";
 // The type every class-keyed registry uses — a class rather than an instance.
 export type { ClassRef } from "./support/classRef.ts";
 export { safeEqual, sha256Hex, hmacHex } from "./support/crypto.ts";

package/src/lock/LockManager.ts

@@ -17,13 +17,13 @@ export interface RefreshOptions {
    * question nobody can answer — and becomes "how long after a crash before
    * someone else may take over", which is a decision rather than a guess.
    */
-  refresh?: boolean;
+  refresh?: boolean | undefined;
 
   /**
    * Seconds between refreshes. Defaults to a third of the TTL, so two
    * consecutive failures still leave a full attempt before the lock lapses.
    */
-  refreshEvery?: number;
+  refreshEvery?: number | undefined;
 }
 
 /**
@@ -44,13 +44,13 @@ export interface BlockOptions extends RefreshOptions {
    * Maximum seconds to wait for the lock before throwing.
    * Defaults to the lock TTL.
    */
-  timeout?: number;
+  timeout?: number | undefined;
 
   /**
    * Milliseconds between polling attempts while waiting.
    * Default: 100 ms.
    */
-  retryDelay?: number;
+  retryDelay?: number | undefined;
 }
 
 /**

package/src/logger/LoggerMiddleware.ts

@@ -42,7 +42,7 @@ const LINE_WIDTH = 60;
 
 export interface LoggerOptions {
   /** Output format. Defaults to LOG_FORMAT env var, then 'text'. */
-  format?: "text" | "json";
+  format?: "text" | "json" | undefined;
 }
 
 /**

package/src/logger/types.ts

@@ -186,11 +186,11 @@ export interface LoggingConfigShape {
   /**
    * The terminal sink, on unless `false`. See {@link ConsoleSinkConfig}.
    */
-  console?: ConsoleSinkConfig;
+  console?: ConsoleSinkConfig | undefined;
   /**
    * The durable file trail, on unless `false`. See {@link FileSinkConfig}.
    */
-  file?: FileSinkConfig;
+  file?: FileSinkConfig | undefined;
   /** Name of the channel used by unqualified `Log.*` calls. */
   default: string;
   /**
@@ -203,10 +203,10 @@ export interface LoggingConfigShape {
    */
   channels: Record<string, ChannelConfig>;
   /** Threshold, in ms, above which ORM queries are logged as slow (default 1000). */
-  slowQueryMs?: number;
+  slowQueryMs?: number | undefined;
   /**
    * Log every HTTP request (method, path, status, duration) via `LoggerMiddleware`.
    * On by default; set `false` to silence the per-request access log.
    */
-  requests?: boolean;
+  requests?: boolean | undefined;
 }

package/src/macros/config.macro.ts

@@ -34,6 +34,8 @@ import { join } from "node:path";
  * Note: config files that read `Bun.env` capture their values from the
  * environment at macro-evaluation time. For bun build --compile this is the
  * CI/CD environment — the same intended behaviour as any immutable artifact.
+ *
+ * @internal
  */
 export function loadConfigsSync(configDir: string): Record<string, Record<string, unknown>> {
   const glob = new Bun.Glob("*.ts");

package/src/metrics/HttpMetrics.ts

@@ -25,12 +25,20 @@ let _2xx = 0,
 let _sumMs = 0,
   _maxMs = 0;
 
-/** Mark a request as started — increments the in-flight (currently-processing) gauge. */
+/**
+ * Mark a request as started — increments the in-flight (currently-processing) gauge.
+ *
+ * @internal
+ */
 export function beginHttp(): void {
   _inFlight++;
 }
 
-/** Mark a request as finished — decrements the in-flight gauge (floored at 0). */
+/**
+ * Mark a request as finished — decrements the in-flight gauge (floored at 0).
+ *
+ * @internal
+ */
 export function endHttp(): void {
   if (_inFlight > 0) _inFlight--;
 }

package/src/middleware/BaseMiddleware.ts

@@ -46,6 +46,26 @@ export abstract class BaseMiddleware<O extends object = object> implements Pipe<
    * Returns a zero-arg subclass with the given options deep-merged on top of
    * the subclass defaults, usable directly in app.use([...]).
    *
+   * **Each call creates a distinct class, and any per-class state goes with it —
+   * so sharing one `.with()` export across two routes shares that state.** For
+   * `ThrottleMiddleware` that state is the hit counter, which means two routes on
+   * one exported instance share a budget: a handful of fumbled sign-ins can spend
+   * the allowance a legitimate person needs to answer their second factor. That is
+   * defensible behaviour and it is not what a reader expects from a factory, so it
+   * is worth saying where the factory is. Call `.with()` once per thing that
+   * deserves its own budget.
+   *
+   * ```ts
+   * // One bucket, shared by both forms — 5 attempts across the pair.
+   * const AuthThrottle = ThrottleMiddleware.with({ maxAttempts: 5 });
+   * Router.post("/login", ...[AuthThrottle]);
+   * Router.post("/two-factor", ...[AuthThrottle]);
+   *
+   * // A bucket each, which is almost always what was meant.
+   * Router.post("/login", ...[ThrottleMiddleware.with({ maxAttempts: 5 })]);
+   * Router.post("/two-factor", ...[ThrottleMiddleware.with({ maxAttempts: 5 })]);
+   * ```
+   *
    * `NoInfer` on the parameter is what makes this type-check at all. `Opts` has
    * a default computed from the middleware class, but a type parameter that
    * appears in an argument position is inferred from the *argument* first and

package/src/middleware/CorsMiddleware.ts

@@ -26,17 +26,17 @@ export interface CorsOptions {
    * `new URL(o).hostname.endsWith('.example.com') && o.startsWith('https://')`, or just
    * list the origins.
    */
-  origin?: string | string[] | ((origin: string) => boolean);
+  origin?: string | string[] | ((origin: string) => boolean) | undefined;
   /** Allowed HTTP methods. Default: `['GET','POST','PUT','PATCH','DELETE','OPTIONS']`. */
-  methods?: string[];
+  methods?: string[] | undefined;
   /** Allowed request headers. Default: `['Content-Type','Authorization','X-Requested-With']`. */
-  allowedHeaders?: string[];
+  allowedHeaders?: string[] | undefined;
   /** Headers the browser may expose to JS. Default: `[]`. */
-  exposedHeaders?: string[];
+  exposedHeaders?: string[] | undefined;
   /** Allow cookies / auth headers in cross-origin requests. Default: `false`. */
-  credentials?: boolean;
+  credentials?: boolean | undefined;
   /** Preflight cache duration in seconds. Default: `600`. */
-  maxAge?: number;
+  maxAge?: number | undefined;
 }
 
 /**