@zerotal/core 1.6.3 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.6.3",
+  "version": "1.7.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -34,6 +34,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",

package/src/application/Application.ts

@@ -27,7 +27,10 @@ import {
 import { builtinConcerns } from "../conventions/builtinConcerns.ts";
 import { ConfigManager } from "../config/ConfigManager.ts";
 import { DEFAULT_MAX_REQUEST_BODY_SIZE } from "../config/AppConfig.ts";
-import { SecureHeadersMiddleware } from "../middleware/SecureHeadersMiddleware.ts";
+import {
+  SecureHeadersMiddleware,
+  staticSecurityHeaders,
+} from "../middleware/SecureHeadersMiddleware.ts";
 import { isAllowedOrigin, allowedOriginsFrom } from "../http/originGuard.ts";
 import { rescueSync } from "../helpers/index.ts";
 import { configureAssets, setAssetVersion, assetVersion } from "../assets/assets.ts";
@@ -237,10 +240,13 @@ export async function _lazyStaticResponse(
     const relative = pathname.slice(trimmedPrefix.length).replace(/^\//, "");
     const file = Bun.file(`${rootDir}/${relative}`);
     if (await file.exists()) {
-      return new Response(
-        file as unknown as BodyInit,
-        options?.headers ? { headers: options.headers } : undefined,
-      );
+      // The same headers Bun's native static routes carry (see Router.compile).
+      // This path returns before the pipeline runs, so without it a file served
+      // lazily — every file under the dev worker — would be the one response in
+      // the app with no security headers on it.
+      return new Response(file as unknown as BodyInit, {
+        headers: { ...staticSecurityHeaders(), ...options?.headers },
+      });
     }
   }
   return undefined;
@@ -260,6 +266,39 @@ export interface WebSocketHandlers {
  */
 export type AppScopeInstaller = () => () => void;
 
+/**
+ * What one provider cost to boot, and what it contributed.
+ *
+ * @see Application.providerReport
+ */
+export interface ProviderReport {
+  /** Provider class name. The array is in boot order. */
+  name: string;
+  /**
+   * Wall-clock milliseconds across all three lifecycle hooks.
+   *
+   * `onBooted` runs concurrently across providers, so these do not sum to the
+   * application's boot time — they overlap, and the report reports that rather
+   * than serialising the boot to produce a tidier number.
+   */
+  durationMs: number;
+  /** Container tokens this provider bound, as names. */
+  bindings: string[];
+}
+
+/**
+ * A container token as a readable name.
+ *
+ * Tokens are class constructors or plain strings; the map keys are neither
+ * sorted nor serialisable as they stand, and a reader wants `CacheManager`, not
+ * `[class CacheManager]`.
+ */
+function _tokenName(token: unknown): string {
+  if (typeof token === "string") return token;
+  if (typeof token === "function") return token.name || "‹anonymous›";
+  return String(token);
+}
+
 const _appScopeInstallers: AppScopeInstaller[] = [];
 
 /**
@@ -318,6 +357,8 @@ export class Application {
   _env: Environment = "web";
   private _booted = false;
   private _bootDurationMs: number | undefined = undefined;
+  /** Per-provider boot cost and container provenance; see {@link providerReport}. */
+  private _providerReport: ProviderReport[] = [];
   private _static?: ReturnType<typeof Bun.serve>;
   private _configMap: Record<string, Record<string, unknown>> | undefined = undefined;
   /** Tracks where config came from, to reject conflicting overrides via useConfig(). */
@@ -609,6 +650,60 @@ export class Application {
     return this._bootDurationMs;
   }
 
+  /**
+   * What each provider cost to boot, and what it put in the container.
+   *
+   * `bootDurationMs` says the app took 240ms and nothing said which provider
+   * spent it; the container lists a hundred bindings and nothing said who bound
+   * them. Both are answered here, in boot order — which is itself the answer to
+   * a third question, since provider order decides who wins a contested binding.
+   *
+   * Empty until `boot()` runs. Populated in every environment: it costs one
+   * `performance.now()` pair and one registry diff per provider at boot, and a
+   * report that only exists in development is one you cannot ask for when a
+   * staging boot is the slow one.
+   *
+   * @category Lifecycle
+   */
+  get providerReport(): readonly ProviderReport[] {
+    return this._providerReport;
+  }
+
+  /**
+   * Time one provider lifecycle hook and attribute anything it bound.
+   *
+   * Accumulates across the three phases, so a provider that binds in
+   * `onRegister` and spends its time in `onBooting` reads as one row.
+   */
+  private _recordProviderWork<T>(provider: ServiceProvider, work: () => T): T {
+    const name = provider.constructor.name;
+    let row = this._providerReport.find((entry) => entry.name === name);
+    if (!row) {
+      row = { name, durationMs: 0, bindings: [] };
+      this._providerReport.push(row);
+    }
+    const before = new Set(this.container.registry.keys());
+    const started = performance.now();
+    const finish = (): T => {
+      row!.durationMs = Math.round((row!.durationMs + performance.now() - started) * 100) / 100;
+      for (const token of this.container.registry.keys()) {
+        if (!before.has(token)) row!.bindings.push(_tokenName(token));
+      }
+      return undefined as T;
+    };
+    const result = work();
+    // An async hook is only finished when its promise is — timing it
+    // synchronously would report every `await` in it as free.
+    if (result instanceof Promise) {
+      return result.then((value: unknown) => {
+        finish();
+        return value;
+      }) as T;
+    }
+    finish();
+    return result;
+  }
+
   /**
    * The runtime environment this application is running in.
    *
@@ -1056,7 +1151,15 @@ export class Application {
     for (const callback of this._bindCallbacks) callback(this.container);
 
     // Phase 1 — synchronous, binds into container.
-    for (const provider of this._activeProviders) provider.onRegister();
+    //
+    // Timed, and the container is diffed around each provider, so the inspector
+    // can answer "who bound `cache`, and what did booting it cost". Provenance
+    // by diff rather than by having the container record a registrar: it keeps
+    // the cost at boot instead of on every binding, and adds no mutable state to
+    // the container for a question only a debugging tool asks.
+    for (const provider of this._activeProviders) {
+      this._recordProviderWork(provider, () => provider.onRegister());
+    }
 
     // Config validation — providers have registered their namespace validators
     // in onRegister; run them before anything boots. In a production-like
@@ -1069,10 +1172,20 @@ export class Application {
     }
 
     // Phase 2 — sequential in registration order.
-    for (const provider of this._activeProviders) await provider.onBooting();
+    for (const provider of this._activeProviders) {
+      await this._recordProviderWork(provider, () => provider.onBooting());
+    }
 
     // Phase 3 — async, all providers have finished booting.
-    await Promise.all(this._activeProviders.map((provider) => provider.onBooted()));
+    //
+    // These run concurrently, so the recorded durations overlap and do not sum
+    // to the phase. That is the truth about this phase and the report says so
+    // rather than serialising the boot to make a tidier number.
+    await Promise.all(
+      this._activeProviders.map((provider) =>
+        this._recordProviderWork(provider, () => provider.onBooted()),
+      ),
+    );
 
     // Ensure config and events are resolved so makeSync() works below.
     await this.container.make("config");

package/src/command/builtin/DoctorCommand.ts

@@ -2,15 +2,18 @@
  * `bun zt doctor` — run every static sanity check against this app and print
  * the findings with their fixes. Exits 1 when anything is broken outright.
  *
- * With `--url`, it also probes the deployed app's WebSocket transport from the outside,
- * through whatever proxy is in front of it. That is the only way to see the failures that
- * leave the app healthy from the inside and inert in the browser.
+ * With `--url`, it also reads the deployed app from the outside, through whatever proxy is
+ * in front of it — the only way to see two classes of failure. The WebSocket transport,
+ * which a proxy can gate or drop while leaving the app healthy from the inside and inert in
+ * the browser. And security headers sent twice, because a header the app sets and the proxy
+ * also sets is invisible from in here: the app's own view is the value it wrote.
  */
 import { Command } from "../Command.ts";
 import type { Application } from "../../application/Application.ts";
 import { runDoctor } from "../../doctor/AppDoctor.ts";
 import type { DoctorReportEntry } from "../../doctor/AppDoctor.ts";
 import { probeTransport } from "../../doctor/TransportProbe.ts";
+import { probeHeaders } from "../../doctor/HeaderProbe.ts";
 
 export class DoctorCommand extends Command {
   static override commandName = "doctor";
@@ -21,7 +24,8 @@ export class DoctorCommand extends Command {
       name: "url",
       type: "string" as const,
       description:
-        "Also probe the deployed app's WebSocket transport at this public URL, as a browser would",
+        "Also read the deployed app at this public URL: handshake its WebSocket transport " +
+        "as a browser would, and report security headers the response carries twice",
     },
   ];
 
@@ -34,9 +38,13 @@ export class DoctorCommand extends Command {
     for (const entry of report) this._print(entry);
 
     const probeFailures = await this._probeTransport(app);
+    const headerFindings = await this._probeHeaders();
 
-    const warns = report.filter((e) => e.result.status === "warn").length;
-    const fails = report.filter((e) => e.result.status === "fail").length + probeFailures;
+    const warns = report.filter((e) => e.result.status === "warn").length + headerFindings.warnings;
+    const fails =
+      report.filter((e) => e.result.status === "fail").length +
+      probeFailures +
+      headerFindings.failures;
     this.newLine();
     // Throw rather than `process.exit(1)` — same exit code from the CLI (the runner
     // converts it), but composable. Exiting here killed any caller running the
@@ -86,6 +94,45 @@ export class DoctorCommand extends Command {
     return failures;
   }
 
+  /**
+   * Report security headers the deployed response carries more than once.
+   *
+   * Only reachable from outside: the app's own view of a header is the value it
+   * wrote, which is correct as far as it goes — the proxy's copy is invisible
+   * from in here. Conflicting values count as failures because a control that
+   * different browsers apply differently is not a control; identical duplicates
+   * are a warning, because they are a conflict waiting for someone to edit one
+   * side.
+   */
+  private async _probeHeaders(): Promise<{ failures: number; warnings: number }> {
+    const url = this.flags["url"] as string | undefined;
+    if (!url) return { failures: 0, warnings: 0 };
+
+    const findings = await probeHeaders(url);
+    this.newLine();
+    this.section("Response headers");
+
+    if (findings.length === 0) {
+      this.line("✓ No duplicated security headers.");
+      return { failures: 0, warnings: 0 };
+    }
+
+    let failures = 0;
+    let warnings = 0;
+    for (const finding of findings) {
+      const line = `${finding.conflicting ? "✗" : "!"} ${finding.header} — ${finding.message}`;
+      if (finding.conflicting) {
+        this.error(line);
+        failures++;
+      } else {
+        this.warn(line);
+        warnings++;
+      }
+      if (finding.fix) this.line(`    fix: ${finding.fix}`);
+    }
+    return { failures, warnings };
+  }
+
   private _print({ check, result }: DoctorReportEntry): void {
     const mark = result.status === "ok" ? "✓" : result.status === "warn" ? "!" : "✗";
     const line = `${mark} ${check.label} — ${result.message}`;

package/src/doctor/HeaderProbe.ts

@@ -0,0 +1,164 @@
+/**
+ * Read a deployed app's security headers from the outside, and report the ones
+ * that arrive twice.
+ *
+ * A header the app sets and the proxy also sets is invisible from inside the
+ * process: the app's own view is the value it wrote, and the app is right about
+ * that. Only a request that has been through the proxy sees both. Deploying
+ * zerotal.dev turned up exactly that — `X-Frame-Options: DENY` from the proxy
+ * and `SAMEORIGIN` from the app, on the same response — and browsers do not
+ * agree on which one wins. A security control that applies inconsistently is
+ * worse than one that is simply absent, because it looks configured.
+ *
+ * ## How a duplicate is visible at all
+ *
+ * `fetch` folds repeated headers into one comma-joined value, so
+ * `X-Frame-Options` sent twice reads back as `"DENY, SAMEORIGIN"`. For headers
+ * whose grammar has no comma in it that is unambiguous evidence of a duplicate.
+ * For `Permissions-Policy` and `Referrer-Policy` it is not — a comma is
+ * legitimate syntax there — so those are deliberately not checked. A probe that
+ * cried wolf on a correct `Permissions-Policy` would be switched off within a
+ * week, and then it would not catch the `X-Frame-Options` either.
+ */
+
+/** One header's finding. */
+export interface HeaderProbeResult {
+  /** The URL that was read. */
+  url: string;
+  /** The header, in the casing it is conventionally written. */
+  header: string;
+  /** The distinct values received, in the order sent. */
+  values: string[];
+  /** False when this needs attention. */
+  ok: boolean;
+  /** Whether the duplicated values disagree — the case browsers handle inconsistently. */
+  conflicting: boolean;
+  message: string;
+  fix?: string;
+}
+
+/**
+ * Headers that take exactly one value, so a comma in the received value means
+ * the header was sent more than once.
+ *
+ * `Permissions-Policy`, `Referrer-Policy` and `Accept-CH` are absent on purpose:
+ * each takes a comma-separated list, so duplication is undetectable this way.
+ */
+const SINGLE_VALUE_HEADERS: Record<string, string> = {
+  "x-frame-options": "X-Frame-Options",
+  "x-content-type-options": "X-Content-Type-Options",
+  "strict-transport-security": "Strict-Transport-Security",
+  "cross-origin-opener-policy": "Cross-Origin-Opener-Policy",
+  "cross-origin-resource-policy": "Cross-Origin-Resource-Policy",
+  "cross-origin-embedder-policy": "Cross-Origin-Embedder-Policy",
+  "x-xss-protection": "X-XSS-Protection",
+};
+
+/**
+ * CSP is its own case: a comma separates *whole policies*, and a browser
+ * enforces every one of them — the effective policy is their intersection. Two
+ * policies that were each written to be sufficient usually intersect into
+ * something that blocks the page.
+ */
+const CSP_HEADERS: Record<string, string> = {
+  "content-security-policy": "Content-Security-Policy",
+  "content-security-policy-report-only": "Content-Security-Policy-Report-Only",
+};
+
+/** Split a folded header value into the values that were actually sent. */
+export function splitFolded(value: string): string[] {
+  return value
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+/**
+ * Inspect a set of response headers for duplicates.
+ *
+ * Exported separately from {@link probeHeaders} so the analysis can be tested
+ * without a network round-trip — the fetch is the only part that needs one.
+ */
+export function analyseHeaders(url: string, headers: Headers): HeaderProbeResult[] {
+  const findings: HeaderProbeResult[] = [];
+
+  for (const [key, label] of Object.entries(SINGLE_VALUE_HEADERS)) {
+    const raw = headers.get(key);
+    if (raw === null) continue;
+    const values = splitFolded(raw);
+    if (values.length < 2) continue;
+
+    const distinct = [...new Set(values.map((value) => value.toLowerCase()))];
+    if (distinct.length > 1) {
+      findings.push({
+        url,
+        header: label,
+        values,
+        ok: false,
+        conflicting: true,
+        message:
+          `sent ${values.length} times with different values (${values.join(" / ")}). ` +
+          `Browsers do not agree on which one applies, so this control is enforced ` +
+          `inconsistently across your visitors.`,
+        fix:
+          `Set ${label} in exactly one place — either the app (config/app.ts → ` +
+          `app.secureHeaders) or the proxy — and remove the other.`,
+      });
+      continue;
+    }
+
+    findings.push({
+      url,
+      header: label,
+      values,
+      ok: false,
+      conflicting: false,
+      message:
+        `sent ${values.length} times with the same value (${values[0]}). Harmless today, ` +
+        `and a conflict the moment either side is changed without the other.`,
+      fix: `Remove the duplicate — keep ${label} in one place.`,
+    });
+  }
+
+  for (const [key, label] of Object.entries(CSP_HEADERS)) {
+    const raw = headers.get(key);
+    if (raw === null) continue;
+    // A comma inside a policy is not valid in the directives apps actually use,
+    // so one here means a second policy was appended.
+    const policies = splitFolded(raw);
+    if (policies.length < 2) continue;
+
+    findings.push({
+      url,
+      header: label,
+      values: policies,
+      ok: false,
+      conflicting: true,
+      message:
+        `${policies.length} separate policies were sent. A browser enforces all of them at ` +
+        `once, so the policy in force is their intersection — usually stricter than either ` +
+        `author intended, and a page that breaks for no visible reason.`,
+      fix: `Send one ${label}, from the app or the proxy but not both.`,
+    });
+  }
+
+  return findings;
+}
+
+/**
+ * Fetch `url` and report every duplicated security header on the response.
+ *
+ * Returns an empty array when the request fails: an unreachable URL is the
+ * transport probe's finding to make, and reporting it twice would be noise.
+ */
+export async function probeHeaders(url: string): Promise<HeaderProbeResult[]> {
+  let response: Response;
+  try {
+    // `redirect: "manual"` on purpose: a redirect's own headers are what the
+    // proxy adds, and following it would report the destination's instead.
+    response = await fetch(url, { method: "GET", redirect: "manual" });
+  } catch {
+    return [];
+  }
+  return analyseHeaders(url, response.headers);
+}

package/src/events/Emitter.ts

@@ -270,6 +270,30 @@ export class Emitter {
     return (this._listeners.get(eventClass)?.length ?? 0) > 0;
   }
 
+  /**
+   * Every event with a listener, and the listeners it has, by name.
+   *
+   * The wiring between an application's events and what reacts to them is
+   * spread across every provider that calls `listen()`, so "what happens when an
+   * order is placed" is a question you answer by searching. This is that map,
+   * and it is what the inspector's Events tab draws.
+   *
+   * Names rather than classes, because the answer is read by a human or crosses
+   * a wire — and a listener class is not serialisable either way.
+   *
+   * @returns One row per event with at least one listener, sorted by name.
+   * @category Subscription
+   */
+  registrations(): Array<{ event: string; listeners: string[] }> {
+    return [...this._listeners.entries()]
+      .filter(([, listeners]) => listeners.length > 0)
+      .map(([eventClass, listeners]) => ({
+        event: (eventClass as { name?: string }).name ?? String(eventClass),
+        listeners: listeners.map((listener) => listener.name),
+      }))
+      .sort((a, b) => a.event.localeCompare(b.event));
+  }
+
   /**
    * Remove every registered listener.
    * @category Subscription

package/src/events/FrameworkEvents.ts

@@ -133,6 +133,34 @@ export const FrameworkEvents = {
     for (const handlers of _byKind.values()) count += handlers.size;
     return count;
   },
+
+  /**
+   * Which events currently have subscribers, and how many each has.
+   *
+   * The bus is the framework's nervous system and has been invisible: "does
+   * anything actually listen to `ModelChanged`" was a question you answered by
+   * reading every package. Sorted by name so two calls are comparable.
+   *
+   * Class- and kind-keyed subscriptions are merged, because a subscriber that
+   * listened by string and one that imported the class are subscribed to the
+   * same event and a reader does not care which door they came through.
+   *
+   * @returns One row per event with at least one live handler.
+   * @category Subscription
+   */
+  subscriptions(): Array<{ event: string; handlers: number }> {
+    const counts = new Map<string, number>();
+    for (const [ctor, handlers] of _byClass) {
+      if (handlers.size)
+        counts.set(_kindOf(ctor), (counts.get(_kindOf(ctor)) ?? 0) + handlers.size);
+    }
+    for (const [kind, handlers] of _byKind) {
+      if (handlers.size) counts.set(kind, (counts.get(kind) ?? 0) + handlers.size);
+    }
+    return [...counts.entries()]
+      .map(([event, handlers]) => ({ event, handlers }))
+      .sort((a, b) => a.event.localeCompare(b.event));
+  },
 };
 
 // ── Framework event types ─────────────────────────────────────────────────────
@@ -218,6 +246,20 @@ export class RequestFailed {
     readonly durationMs: number,
     readonly error: string,
     readonly status: number,
+    /**
+     * The error's class name, when the failure was an `Error`.
+     *
+     * `message` alone cannot tell a `ValidationError` from a `TypeError`, and
+     * which one it was is usually the first thing you want to know.
+     */
+    readonly type?: string,
+    /**
+     * The raw `Error.stack`, for subscribers that render a trace.
+     *
+     * Carried as the unparsed string: the shape differs between runtimes, and
+     * this event should not be the thing that decides how a frame is spelled.
+     */
+    readonly stack?: string,
   ) {}
 }
 

package/src/index.ts

@@ -66,6 +66,7 @@ export type {
   FileRoutingEntry,
   FileRoutingConfig,
   AppScopeInstaller,
+  ProviderReport,
 } from "./application/Application.ts";
 export { ExceptionHandler } from "./application/ExceptionHandler.ts";
 
@@ -161,6 +162,7 @@ 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";
 // 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/middleware/BaseMiddleware.ts

@@ -8,6 +8,7 @@ import type { HttpContext } from "../pipeline/HttpContext.ts";
 // Canonical implementation now lives in support/deepMerge.ts; re-exported here so existing
 // `import { deepMerge } from "./BaseMiddleware.ts"` call sites keep working.
 import { deepMerge } from "../support/deepMerge.ts";
+import type { DeepPartial } from "../support/deepMerge.ts";
 
 export { deepMerge };
 
@@ -44,13 +45,23 @@ 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([...]).
+   *
+   * `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
+   * only falls back to its default when inference finds nothing — so
+   * `Middleware.with({ resolve: (claims) => … })` used to infer `Opts` from the
+   * object literal it was handed, which meant the literal type-checked against
+   * itself. Every callback parameter arrived implicitly `any`, and a misspelled
+   * option was accepted in silence. Blocking inference makes the middleware's
+   * own option type the one that governs.
    */
   static with<
     // 1. Constrain T to be a concrete class (not abstract) that extends BaseMiddleware
     T extends new (...args: any[]) => BaseMiddleware<any>,
     // 2. Dynamically infer the specific options type (U) from that concrete class
     Opts = T extends new (...args: any[]) => BaseMiddleware<infer U> ? U : object,
-  >(this: T, options: Partial<Opts>): new () => InstanceType<T> {
+  >(this: T, options: DeepPartial<NoInfer<Opts>>): new () => InstanceType<T> {
     const configured = class extends (this as any) {
       constructor() {
         super();