@zerotal/core 1.8.1 → 1.9.0

package/src/doctor/AppDoctor.ts

@@ -17,6 +17,7 @@ import { appKeyStrengthWarning } from "../support/appKey.ts";
 import { unroutedRoutesWarning } from "../support/unroutedRoutes.ts";
 import { isWritableDir } from "../dev/bootBuild.ts";
 import { isProdLike } from "../support/env.ts";
+import { throttlesKeyedOnSocket } from "./throttleIdentity.ts";
 
 /** One finding: ok is silent health, warn is worth reading, fail is broken now. */
 export interface DoctorCheckResult {
@@ -365,12 +366,53 @@ const secureHeadersCheck: DoctorCheck = {
   },
 };
 
-/** The core checks every app gets. */
+/**
+ * A rate limiter behind a proxy that was never told about the proxy keys every
+ * visitor to the same bucket, because the socket address is the proxy's. It then
+ * does the opposite of its job: one attacker spends the allowance for everybody.
+ *
+ * A warning rather than a failure, because the framework cannot see the deployment.
+ * An app served directly, with no proxy in front of it, is correctly configured
+ * exactly as it stands — and that app should not be blocked from deploying by a
+ * guess. What is worth saying is that the combination is almost always wrong, and
+ * that nothing else will ever tell you.
+ */
+const throttleIdentityCheck: DoctorCheck = {
+  id: "throttle-trusted-proxies",
+  label: "Rate-limit identity",
+  run(app) {
+    const exposed = throttlesKeyedOnSocket(app);
+    if (exposed.length === 0) return ok("every registered throttle can identify a client.");
+    if (!_isProductionEnv(app)) {
+      return ok(`${exposed.length} throttle(s) key on the socket address — fine locally.`);
+    }
+    const where = exposed
+      .slice(0, 3)
+      .map((t) => t.where)
+      .join(", ");
+    return warn(
+      `${exposed.length} throttle(s) (${where}${exposed.length > 3 ? ", …" : ""}) key on the ` +
+        `socket address and no trustedProxies is set. Behind a reverse proxy that address is ` +
+        `the proxy's for every request, so all visitors share one bucket and one of them can ` +
+        `lock out the rest.`,
+      "If a proxy fronts this app, set trustedProxies to how many — `ThrottleMiddleware.with({ " +
+        "maxAttempts: 5, trustedProxies: 1 })`, or `app.throttle.trustedProxies` for all of " +
+        "them. If nothing fronts it, this is already correct.",
+    );
+  },
+};
+
+/**
+ * The core checks every app gets.
+ *
+ * @internal
+ */
 export const builtinDoctorChecks: DoctorCheck[] = [
   appKeyCheck,
   allowedOriginsCheck,
   corsWildcardCheck,
   secureHeadersCheck,
+  throttleIdentityCheck,
   bootAssetWriteCheck,
   syncVsMigrationsCheck,
   unroutedRoutesCheck,

package/src/doctor/throttleIdentity.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 } 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,
+      customKey: typeof options.keyResolver === "function",
+    };
+  } 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/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/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,8 @@ ${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.
+ *
+ * @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/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/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/pipeline/ContextRegistry.ts

@@ -32,11 +32,21 @@
  * still compiles and returns `unknown`.
  *
  * @category Extension registries
+ *
+ * @internal
  */
 export interface ContextRegistry {}
 
-/** Union of every registered context key. `never` until a package augments {@link ContextRegistry}. */
+/**
+ * Union of every registered context key. `never` until a package augments {@link ContextRegistry}.
+ *
+ * @internal
+ */
 export type ContextKey = keyof ContextRegistry;
 
-/** The value type stored under a registered context key. */
+/**
+ * The value type stored under a registered context key.
+ *
+ * @internal
+ */
 export type ContextValue<K extends ContextKey> = ContextRegistry[K];

package/src/pipeline/HttpContext.ts

@@ -31,6 +31,8 @@ type AnyViewComponent = (ctx: HttpContext<any>, props: any) => ViewMarkup | Prom
 /**
  * Minimal Bun server interface needed for socket-level IP resolution.
  * Duck-typed so HttpContext has no hard dependency on Bun's global types.
+ *
+ * @internal
  */
 export interface RequestIPProvider {
   requestIP(req: Request): { address: string; family: string; port: number } | null;
@@ -874,6 +876,8 @@ const _prototypeMethods: ReadonlyArray<[string, (...args: unknown[]) => unknown]
  * @param origin - The current request origin to match against.
  * @returns The same-origin `url`, or `undefined` when it is absent, unparseable,
  * or points to a different origin.
+ *
+ * @internal
  */
 export function safeRedirectPath(
   url: string | null | undefined,

package/src/pipeline/currentPage.ts

@@ -5,6 +5,8 @@ import { HttpContext } from "./HttpContext.ts";
  *
  * @param pageName - The paginator's name, so one request can drive several independently.
  * @returns The 1-based page, or `undefined` to fall back to the query string.
+ *
+ * @internal
  */
 export type CurrentPageResolver = (pageName: string) => number | undefined;
 
@@ -21,6 +23,8 @@ export type CurrentPageResolver = (pageName: string) => number | undefined;
  * another one. Keep it that way — a module-level slot would not be request-scoped.
  *
  * @param resolver - Called with the paginator name; return `undefined` to defer to the query string.
+ *
+ * @internal
  */
 export function setCurrentPageResolver(resolver: CurrentPageResolver): void {
   const ctx = HttpContext.tryGet();

package/src/pipeline/types.ts

@@ -74,6 +74,8 @@ export interface Pipe<T> {
 /**
  * A payload that can carry a `Response`. Pipes set `response` and return the
  * payload to short-circuit; the pipeline terminal reads it back.
+ *
+ * @internal
  */
 export interface HasResponse {
   response: Response | undefined;

package/src/router/FileRouter.ts

@@ -23,6 +23,8 @@ export type { FileHandler };
 /**
  * Per-method middleware map for a route file's `export const middleware`.
  * `ALL` applies to every method the file handles; the per-verb arrays add to it.
+ *
+ * @internal
  */
 export interface RouteMethodMiddleware {
   ALL?: MiddlewareClass[];
@@ -45,6 +47,7 @@ export type RouteMiddleware = MiddlewareClass[] | RouteMethodMiddleware;
 
 /** Shape of a route module. `default` may be a FileHandler or a ViewComponent;
  *  `layout` overrides the directory `_layout` (null = no layout). */
+/** @internal */
 export interface RouteModule {
   default?: FileHandler | ViewComponent;
   GET?: FileHandler;
@@ -57,7 +60,11 @@ export interface RouteModule {
   middleware?: RouteMiddleware;
 }
 
-/** Optional `export const meta = { GET: { name: 'users.show' } }` in route files. */
+/**
+ * Optional `export const meta = { GET: { name: 'users.show' } }` in route files.
+ *
+ * @internal
+ */
 export interface RouteFileMeta {
   GET?: { name?: string };
   POST?: { name?: string };
@@ -66,7 +73,11 @@ export interface RouteFileMeta {
   DELETE?: { name?: string };
 }
 
-/** Shape of a `_middleware.ts` file. */
+/**
+ * Shape of a `_middleware.ts` file.
+ *
+ * @internal
+ */
 export interface MiddlewareModule {
   middleware: MiddlewareClass[];
 }
@@ -75,6 +86,8 @@ export interface MiddlewareModule {
 
 /**
  * Context handed to a file-route resolver for each scanned route file.
+ *
+ * @internal
  */
 export interface FileRouteContext {
   /** URL path derived from the file location (e.g. '/users/:id'). */
@@ -105,6 +118,8 @@ export interface FileRouteContext {
  *   Router.flow(urlPath, PageClass, middleware);
  *   return true;
  * });
+ *
+ * @internal
  */
 export type FileRouteResolver = (ctx: FileRouteContext) => boolean;
 
@@ -112,6 +127,7 @@ const _fileRouteResolvers: FileRouteResolver[] = [];
 
 /** Register a resolver. Call from a provider's onRegister() so it is in place
  *  before Application.boot() scans file routes. */
+/** @internal */
 export function registerFileRouteResolver(resolver: FileRouteResolver): void {
   _fileRouteResolvers.push(resolver);
 }
@@ -390,6 +406,8 @@ async function _collectLayout(
  *                  creates a fresh module namespace instead of returning the
  *                  cached version.  Omit on first boot.
  * @returns The number of individual method handlers registered.
+ *
+ * @internal
  */
 export async function scanFileRoutes(baseDir: string, reloadId?: string): Promise<number> {
   const absoluteBase = _resolveAbsoluteBase(baseDir);

package/src/router/Route.ts

@@ -18,6 +18,7 @@ export type MiddlewareClass = new (...args: any[]) => Pipe<HttpContext>;
 /** Handler signature for file-based routes. Receives the request {@link HttpContext}
  *  directly — route params and resolved model bindings live on `ctx.params`. May return
  *  a Response or mutate `ctx` directly. */
+/** @internal */
 export type FileHandler = (ctx: HttpContext) => void | Response | Promise<void | Response>;
 
 /**
@@ -49,6 +50,8 @@ export type ViewLayout = (ctx: HttpContext, props: { children: unknown }) => unk
  * Receives the raw string param value and the current context;
  * must return (or resolve to) the model instance.
  * Throw `ModelNotFoundError` (or any 404 error) when the record does not exist.
+ *
+ * @internal
  */
 export type ModelBindingResolver = (value: string, ctx: HttpContext) => Promise<unknown>;
 

package/src/router/Router.ts

@@ -178,6 +178,8 @@ function _toResolver(modelOrResolver: ModelClass | ModelBindingResolver): ModelB
  * All mutable router state in one swappable object: registered routes, the
  * active group prefix/middleware/domain, static and markdown directories, named
  * routes, and named middleware groups.
+ *
+ * @internal
  */
 export class RouterState {
   routes = new Map<string, RouteDefinition>();

package/src/router/domain.ts

@@ -6,6 +6,7 @@
  * exposed on the request via `ctx.subdomains`.
  */
 
+/** @internal */
 export interface CompiledDomain {
   /** The original pattern, e.g. ':tenant.app.com'. */
   source: string;

package/src/router/registry.ts

@@ -23,7 +23,11 @@
  * updates with it.
  */
 
-/** A value that can be substituted into a `:param` segment. */
+/**
+ * A value that can be substituted into a `:param` segment.
+ *
+ * @internal
+ */
 export type RouteParamValue = string | number;
 
 /** The loose param bag accepted by the untyped `route()` overload. */
@@ -68,7 +72,11 @@ export type RouteName = Extract<keyof RouteRegistry, string>;
  */
 export type RouteTarget = [RouteName] extends [never] ? string : RouteName;
 
-/** The URL pattern registered for route `N`, or plain `string` when it isn't a known name. */
+/**
+ * The URL pattern registered for route `N`, or plain `string` when it isn't a known name.
+ *
+ * @internal
+ */
 export type RoutePattern<N extends string> = N extends RouteName
   ? RouteRegistry[N] extends string
     ? RouteRegistry[N]
@@ -101,6 +109,8 @@ export type RouteParams<N extends string> = Prettify<ParamsOf<RoutePattern<N>>>;
  * generated, loose before that. Used by the helpers that take params without
  * being able to take `route()`'s rest-tuple — `redirect().to(name, params,
  * status)` and Flow's `redirectRoute`.
+ *
+ * @internal
  */
 export type RouteParamsArg<N extends string> = [RouteName] extends [never]
   ? RouteParamValues