@zerotal/core 1.6.3 → 1.7.2

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();

package/src/middleware/SecureHeadersMiddleware.ts

@@ -94,34 +94,65 @@ export class SecureHeadersMiddleware extends BaseMiddleware<SecureHeadersOptions
   async handle(_ctx: HttpContext, next: NextFn): Promise<Response | void> {
     const response = await next();
     if (!response) return;
+    return withHeaders(response, securityHeaders(this.options));
+  }
+}
 
-    const secure: Record<string, string> = {
-      // Always-on security headers
-      "X-Content-Type-Options": "nosniff",
-      "Referrer-Policy": this.options.referrerPolicy ?? "strict-origin-when-cross-origin",
-    };
+/**
+ * The headers this middleware adds, as a plain object.
+ *
+ * Separated from `handle()` because the middleware is not the only thing that
+ * has to send them. Static files are registered with Bun as native
+ * `Response(Bun.file)` routes and are answered without ever entering JavaScript,
+ * so the pipeline — and therefore this middleware — never runs for them. That
+ * left `/css/app.css` served with no `X-Content-Type-Options: nosniff`, which is
+ * precisely the kind of response sniffing protection exists for, while the
+ * framework advertised the header as automatic. {@link Router.static} calls this
+ * so the same set is attached at registration time and Bun still serves the file
+ * natively.
+ *
+ * @param options - Resolved secure-header options, usually `app.secureHeaders`.
+ * @returns Header name → value. Never includes HSTS unless `secure` is set.
+ */
+export function securityHeaders(options: SecureHeadersOptions): Record<string, string> {
+  const secure: Record<string, string> = {
+    // Always-on security headers
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": options.referrerPolicy ?? "strict-origin-when-cross-origin",
+  };
 
-    const frameOptions = this.options.frameOptions ?? "SAMEORIGIN";
-    if (frameOptions) secure["X-Frame-Options"] = frameOptions;
+  const frameOptions = options.frameOptions ?? "SAMEORIGIN";
+  if (frameOptions) secure["X-Frame-Options"] = frameOptions;
 
-    const permissionsPolicy = this.options.permissionsPolicy ?? DEFAULT_PERMISSIONS_POLICY;
-    if (permissionsPolicy) secure["Permissions-Policy"] = permissionsPolicy;
+  const permissionsPolicy = options.permissionsPolicy ?? DEFAULT_PERMISSIONS_POLICY;
+  if (permissionsPolicy) secure["Permissions-Policy"] = permissionsPolicy;
 
-    if (this.options.contentSecurityPolicy) {
-      secure["Content-Security-Policy"] = this.options.contentSecurityPolicy;
-    }
+  if (options.contentSecurityPolicy) {
+    secure["Content-Security-Policy"] = options.contentSecurityPolicy;
+  }
 
-    // HSTS only over HTTPS — emitting it on HTTP can lock users out
-    if (this.options.secure) {
-      const maxAge = this.options.hstsMaxAge ?? 31_536_000;
-      if (maxAge > 0) {
-        const parts = [`max-age=${maxAge}`];
-        if (this.options.hstsIncludeSubDomains !== false) parts.push("includeSubDomains");
-        if (this.options.hstsPreload) parts.push("preload");
-        secure["Strict-Transport-Security"] = parts.join("; ");
-      }
+  // HSTS only over HTTPS — emitting it on HTTP can lock users out
+  if (options.secure) {
+    const maxAge = options.hstsMaxAge ?? 31_536_000;
+    if (maxAge > 0) {
+      const parts = [`max-age=${maxAge}`];
+      if (options.hstsIncludeSubDomains !== false) parts.push("includeSubDomains");
+      if (options.hstsPreload) parts.push("preload");
+      secure["Strict-Transport-Security"] = parts.join("; ");
     }
-
-    return withHeaders(response, secure);
   }
+
+  return secure;
+}
+
+/**
+ * The security headers a static file should carry, read from `app.secureHeaders`.
+ *
+ * A separate entry point from {@link securityHeaders} so the caller does not
+ * have to reach for the config facade itself, and so the fallback is stated in
+ * one place: an app with no `app.secureHeaders` block still gets the baseline,
+ * which is the whole point of the defaults.
+ */
+export function staticSecurityHeaders(): Record<string, string> {
+  return securityHeaders(config.safe("app.secureHeaders", {} as SecureHeadersOptions));
 }

package/src/provider/StorageProvider.ts

@@ -32,7 +32,10 @@ export class StorageProvider extends ServiceProvider {
   }
 
   override async onBooting(): Promise<void> {
-    const storage = await this.app.container.make("storage");
+    // Named explicitly: `make()` infers its type parameter from the token, and a
+    // plain string token infers nothing — so this used to arrive as `unknown`
+    // and reach `StorageFilesMiddleware.with({ storage })` unchecked.
+    const storage = await this.app.container.make<StorageManager>("storage");
 
     const config = this.app.container.makeSync("config") as ConfigManager;
     const storageCfg = config.get<ReturnType<typeof StorageConfig>>("storage", StorageConfig());

package/src/router/RouteHandler.ts

@@ -172,6 +172,11 @@ export async function dispatchRequest(
             durationMs,
             failure instanceof Error ? failure.message : String(failure),
             response!.status,
+            // The class name and the stack alongside the message. A subscriber
+            // rendering a failure has nothing to show without them, and by the
+            // time the event is emitted the error is the only place they exist.
+            failure instanceof Error ? failure.name : undefined,
+            failure instanceof Error ? failure.stack : undefined,
           ),
         );
       } else {

package/src/router/Router.ts

@@ -30,6 +30,7 @@ import { compileDomain, matchDomain, setRequestSubdomains } from "./domain.ts";
 import type { ProviderHooks } from "./RouteHandler.ts";
 import { tryCurrentApp } from "../application/currentApp.ts";
 import { frameworkLog } from "../logger/frameworkLog.ts";
+import { staticSecurityHeaders } from "../middleware/SecureHeadersMiddleware.ts";
 import {
   markdownExtractTitle,
   markdownPage,
@@ -80,6 +81,40 @@ function _wrapFileHandler(fn: FileHandler, debugName: string): ControllerClass {
 type AnyRouteHandler = RouteHandler<any>;
 
 type RouteHandlerFn = (req: Request, server?: unknown) => Response | Promise<Response>;
+
+/**
+ * Wrap a raw handler so its response carries the security headers, without
+ * touching any the handler set for itself.
+ *
+ * Add-if-absent rather than `withHeaders`, which overwrites: a raw route is the
+ * one place a handler is fully in charge of its own response, and a transport
+ * endpoint that deliberately sets `X-Frame-Options` for its own reasons must
+ * keep it. The response is only reconstructed when something is actually
+ * missing, so a handler that already set everything pays nothing — and
+ * reconstruction is required rather than optional when it happens, because a
+ * `Response.redirect()` has an immutable headers guard that throws on `set`.
+ */
+function _withSecurityDefaults(
+  handler: RouteHandlerFn,
+  defaults: Record<string, string>,
+): RouteHandlerFn {
+  const names = Object.keys(defaults);
+  if (names.length === 0) return handler;
+
+  return async (req, server) => {
+    const response = await handler(req, server);
+    const missing = names.filter((name) => !response.headers.has(name));
+    if (missing.length === 0) return response;
+
+    const merged = new Headers(response.headers);
+    for (const name of missing) merged.set(name, defaults[name]!);
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: merged,
+    });
+  };
+}
 /**
  * A path entry is either a method-keyed map of handlers, or a bare static
  * `Response` (Bun.serve serves the latter at zero JS cost per request).
@@ -1026,14 +1061,19 @@ export class Router {
         continue;
       }
       const basePrefix = prefix.replace(/\/$/, "");
+      // Static files are handed to Bun as native `Response(Bun.file)` routes and
+      // answered without entering JavaScript, so `SecureHeadersMiddleware` — and
+      // the whole pipeline — never runs for them. The headers are therefore
+      // baked in here instead. Anything the dir declared wins: a caller who set
+      // an explicit `X-Frame-Options` for one mount meant it.
+      const headers = { ...staticSecurityHeaders(), ...options?.headers };
       let registered = 0;
       for (const relativePath of files) {
         const urlPath = `${basePrefix}/${relativePath.replace(/\\/g, "/")}`.replace(/\/+/g, "/");
         if (compiled[urlPath]) continue;
-        const headers = options?.headers;
         compiled[urlPath] = new Response(
           Bun.file(`${rootDir}/${relativePath}`) as unknown as BodyInit,
-          headers ? { headers } : undefined,
+          { headers },
         );
         registered++;
       }
@@ -1071,12 +1111,31 @@ export class Router {
 
     // Raw routes bypass the middleware pipeline entirely — added last so they
     // take precedence over any same-path pipeline routes.
+    //
+    // Bypassing the pipeline also bypasses `SecureHeadersMiddleware`, and that is
+    // not what anyone opts out for: `Router.raw()` exists to skip *request*
+    // handling — CSRF on a transport endpoint, session resolution on a relay —
+    // not to opt a response out of the headers the framework advertises as
+    // automatic. This framework's own documentation site serves every `/docs/*`
+    // page from a raw route, and every one of them went out with no
+    // `X-Content-Type-Options: nosniff`.
+    //
+    // Computed once here rather than per request: raw routes include Flow's
+    // action endpoint, which is as hot as anything in the app.
+    const rawDefaults = staticSecurityHeaders();
     for (const [key, handler] of _s().rawRoutes) {
       const spaceIndex = key.indexOf(" ");
       const method = key.slice(0, spaceIndex) as HttpMethod;
       const path = key.slice(spaceIndex + 1);
       const rawMap = (compiled[path] ??= {}) as Record<string, RouteHandlerFn>;
-      rawMap[method] = handler;
+      rawMap[method] = _withSecurityDefaults(handler, rawDefaults);
+      // And `HEAD`, for the same reason the pipeline derives it — a raw route is
+      // still a route, and `curl -I` against one answered 404 while the `GET`
+      // beside it answered 200. This site's own `/docs/*` and `/blog` are raw,
+      // so every link checker and uptime probe pointed at them was told the page
+      // did not exist. Derived from the wrapped handler, so the headers above
+      // ride along.
+      if (method === "GET") rawMap["HEAD"] ??= _headFrom(rawMap[method]!);
     }
 
     return compiled;

package/src/router/routeTypes.ts

@@ -24,6 +24,7 @@
  * the browser bundle.
  */
 import { relative } from "node:path";
+import { Router } from "./Router.ts";
 
 /** Where the generated map is written, relative to the project root. */
 export const ROUTE_TYPES_FILE = "types/routes.generated.ts";
@@ -32,9 +33,11 @@ const HEADER = [
   "// Auto-generated by @zerotal/core — do not edit manually.",
   "// Regenerate with: bun zt route:types",
   "//",
-  "// Every named route and the URL pattern it compiles to. `route()` reads this",
-  "// through declaration merging, so an unknown name or a missing :param is a",
-  "// compile error. Commit this file: editors and CI need it without booting the app.",
+  "// Every named route, the URL pattern it compiles to, and the HTTP method it",
+  "// answers on. `route()` reads ROUTES through declaration merging, so an unknown",
+  "// name or a missing :param is a compile error; `action()` also reads METHODS, so",
+  "// a form cannot submit a route with the wrong verb.",
+  "// Commit this file: editors and CI need it without booting the app.",
   "",
 ];
 
@@ -52,17 +55,28 @@ const HEADER = [
 export function generateRouteTypes(
   namedRoutes: ReadonlyMap<string, string>,
   importSpecifier = "@zerotal/core",
+  methods: ReadonlyMap<string, string> = new Map(),
 ): string {
   const entries = Array.from(namedRoutes.entries()).sort(([a], [b]) => a.localeCompare(b));
+  const key = (name: string) => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));
 
   // Quote the key only when it isn't a bare identifier — `home` stays bare and
   // `posts.show` stays quoted, which is what a formatter would do to this file
   // anyway. Matching it here keeps `format:check` off a file nobody edits.
-  const lines = entries.map(
-    ([name, pattern]) =>
-      `  ${/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name)}: ` +
-      `${JSON.stringify(pattern)},`,
-  );
+  const lines = entries.map(([name, pattern]) => `  ${key(name)}: ${JSON.stringify(pattern)},`);
+
+  // A second table rather than one of `{ url, method }` objects: `ROUTES` is what
+  // `route()` and `RouteRegistry` already read, and widening its value type would
+  // break every app that has generated this file. Two flat maps also stay
+  // tree-shakeable — a bundle that only builds links never pulls the verbs in.
+  const methodLines = entries
+    .filter(([name]) => methods.has(name))
+    .map(([name]) => `  ${key(name)}: ${JSON.stringify(methods.get(name))},`);
+
+  const methodTable =
+    methodLines.length > 0
+      ? ["export const METHODS = {", ...methodLines, "} as const;"]
+      : ["export const METHODS = {} as const;"];
 
   // Empty on one line: an app with no named routes still gets a file a formatter
   // leaves alone (and a registry that types nothing, so `route()` stays on its
@@ -76,11 +90,17 @@ export function generateRouteTypes(
     ...HEADER,
     ...table,
     "",
+    ...methodTable,
+    "",
     "/** The generated route table, as a type. */",
     "export type Routes = typeof ROUTES;",
     "",
+    "/** The HTTP method each named route answers on. */",
+    "export type RouteMethods = typeof METHODS;",
+    "",
     `declare module ${JSON.stringify(importSpecifier)} {`,
     "  interface RouteRegistry extends Routes {}",
+    "  interface RouteMethodRegistry extends RouteMethods {}",
     "}",
     // The file is rewritten on every dev boot; without a trailing newline a
     // formatter in the app would put one back, forever.
@@ -104,15 +124,21 @@ export interface RouteTypesResult {
  * Write (or, with `check`, verify) `types/routes.generated.ts` for a booted app.
  *
  * @param namedRoutes - The router's `namedRoutes` map.
- * @param options - `cwd` (project root, default `process.cwd()`) and `check` (compare only, never write).
+ * @param options - `cwd` (project root, default `process.cwd()`), `check` (compare only, never write), and `methods` (name → HTTP verb).
  * @returns Whether the on-disk file was stale, plus the contents it should have.
  */
 export async function writeRouteTypes(
   namedRoutes: ReadonlyMap<string, string>,
-  options: { cwd?: string; check?: boolean } = {},
+  options: { cwd?: string; check?: boolean; methods?: ReadonlyMap<string, string> } = {},
 ): Promise<RouteTypesResult> {
   const cwd = options.cwd ?? process.cwd();
-  const content = generateRouteTypes(namedRoutes);
+  // Derived here rather than asked of the caller. `zt dev` regenerates this file
+  // on every boot through its own call site, and when only `route:types` passed
+  // the verbs, a dev restart silently rewrote the table empty — which turned a
+  // form POST into a GET and 404'd. A default a caller must remember is a
+  // default that eventually gets forgotten.
+  const methods = options.methods ?? routeMethods();
+  const content = generateRouteTypes(namedRoutes, "@zerotal/core", methods);
   const target = `${cwd}/${ROUTE_TYPES_FILE}`;
 
   const file = Bun.file(target);
@@ -130,3 +156,18 @@ export async function writeRouteTypes(
     count: namedRoutes.size,
   };
 }
+
+/**
+ * Name → HTTP verb for every named route the router knows.
+ *
+ * `RouteDefinition` carries its own `name` beside `method`, so the pair comes
+ * from one record. A path join would be wrong: `GET /login` and `POST /login`
+ * share a path and differ only by name.
+ */
+export function routeMethods(): Map<string, string> {
+  const methods = new Map<string, string>();
+  for (const definition of Router.routes.values()) {
+    if (definition.name) methods.set(definition.name, definition.method);
+  }
+  return methods;
+}

package/src/router/routes.ts

@@ -48,6 +48,31 @@ import type {
 } from "./registry.ts";
 import { buildRouteUrl, unknownRouteError } from "./buildRoute.ts";
 
+/**
+ * Re-exported so a browser bundle can write its own typed wrappers.
+ *
+ * These live in `registry.ts`, which is reachable from the `@zerotal/core` root
+ * — and that root drags the CLI command modules into any bundle that imports it.
+ * A component building a helper around `route()` needs the types without the
+ * server, so they surface here, on the entry that is already browser-safe.
+ */
+export type { RouteArgs, RouteParamValues, RouteQuery, RouteTarget } from "./registry.ts";
+
+/**
+ * `route()` without an import.
+ *
+ * {@link defineRoutes} puts the builder on `globalThis`, and this is the
+ * declaration that lets a call site use it: a page writes `route("posts.show")`
+ * with no import line, typed exactly as the named export is — the same
+ * `RouteBuilder`, so an unknown name or a missing `:param` still fails the build.
+ *
+ * `var` rather than `const`, because only `var` in a `declare global` block
+ * creates a matching property on `globalThis` for the assignment to satisfy.
+ */
+declare global {
+  var route: RouteBuilder;
+}
+
 /**
  * The name → pattern map `route()` resolves against. A plain object is what
  * `types/routes.generated.ts` exports; a `Map` is accepted so a server-side
@@ -73,6 +98,25 @@ let _table: ReadonlyMap<string, string> | null = null;
  */
 export function defineRoutes(table: RouteTable): void {
   _table = table instanceof Map ? table : new Map(Object.entries(table));
+  _installGlobal();
+}
+
+/**
+ * Put `route()` on `globalThis`, so nothing has to import it.
+ *
+ * This is the one function both processes already call — the server from
+ * `Application._installRouteTable()` at boot, a browser entry beside its
+ * generated `ROUTES` — which makes it the only place that can install the global
+ * for both without an app remembering to do it in two files.
+ *
+ * The table is installed first, deliberately: a global that exists but throws
+ * "no route table" is worse than one that appears at the same moment it works.
+ *
+ * `route` stays a named export. Removing it would break every existing import
+ * for no gain, and a test that wants a clean global can still reach for it.
+ */
+function _installGlobal(): void {
+  (globalThis as { route?: typeof route }).route = route;
 }
 
 /**
@@ -147,3 +191,74 @@ export const route: RouteBuilder = Object.assign(
 // compile time, so `import type { RouteName } from "@zerotal/core"` costs a
 // browser bundle nothing — and a second export path for the same names is a
 // second entry in every surface report, forever, for no runtime benefit.
+
+// ── Verb-aware routes ─────────────────────────────────────────────────────────
+
+/**
+ * Augmented by `types/routes.generated.ts` with the HTTP method of every named
+ * route, exactly as {@link RouteRegistry} is augmented with their patterns.
+ */
+export interface RouteMethodRegistry {}
+
+/** A name the generated table knows a verb for. */
+export type MethodedRouteName = Extract<keyof RouteMethodRegistry, string>;
+
+const methodTable = new Map<string, string>();
+
+/**
+ * Register the generated `METHODS` table.
+ *
+ * Called once at boot beside {@link defineRoutes}. Kept separate because the two
+ * tables have different audiences: a page that only builds links needs the
+ * patterns and never the verbs, and a bundler can then drop the verbs entirely.
+ */
+export function defineRouteMethods(table: Readonly<Record<string, string>>): void {
+  methodTable.clear();
+  for (const [name, method] of Object.entries(table)) methodTable.set(name, method);
+}
+
+/** The verb a named route answers on, or undefined when it was never registered. */
+export function routeMethod(name: string): string | undefined {
+  return methodTable.get(name);
+}
+
+/** A resolved endpoint: where to send a request, and how. */
+export interface RouteAction {
+  url: string;
+  method: string;
+}
+
+/**
+ * Resolve a named route to both its URL and its HTTP method.
+ *
+ * The pair is the point. A form that hardcodes a URL can still send the wrong
+ * verb, and the failure — a 404 or a 405 on submit — looks nothing like its
+ * cause. Taking both from one generated record means a route that changes verb
+ * changes it everywhere at once.
+ *
+ * Throws when the name has no registered verb. An earlier version defaulted to
+ * `GET`, and that default cost a real bug: a regenerated table came back empty,
+ * every `action()` reported `GET`, and a file upload submitted as a GET to its
+ * own store route and 404'd. The point of resolving a verb from a table is that
+ * a wrong verb becomes impossible — a silent fallback gives that away for a
+ * failure mode nobody reads, so this is loud instead.
+ *
+ * Use {@link route} for links, which need no verb.
+ *
+ * @example
+ * const submit = action("projects.issues.comments.store", { project: "apollo", issue: 4 });
+ * // → { url: "/projects/apollo/issues/4/comments", method: "POST" }
+ */
+export function action<N extends RouteTarget>(name: N, ...args: RouteArgs<N>): RouteAction {
+  const method = methodTable.get(name as string);
+  if (method === undefined) {
+    throw new Error(
+      `action("${String(name)}"): no HTTP method registered for this route. ` +
+        `On the server this is installed at boot, so an empty table means the route ` +
+        `is not registered. In a browser bundle, call defineRouteMethods(METHODS) ` +
+        `from types/routes.generated.ts at your entry point. ` +
+        `Use route() instead for links, which need no verb.`,
+    );
+  }
+  return { url: route(name, ...args), method };
+}

package/src/security/index.ts

@@ -26,3 +26,9 @@ export type { HashAlgorithm } from "../hash/Hash.ts";
 // signing with no secret to manage, `Url.sign` / `Url.verify` on the http subpath is the
 // higher-level option.
 export { URLSigner } from "../crypt/URLSigner.ts";
+// The redaction walk every recorder needs and each had written for itself. Not a
+// policy — callers bring their own markers and their own sensitivity predicate,
+// because an adapter implementing a published protocol does not get to choose
+// its markers and a debug panel does.
+export { redactGraph } from "./redactGraph.ts";
+export type { RedactGraphOptions } from "./redactGraph.ts";

package/src/security/redactGraph.ts

@@ -0,0 +1,107 @@
+/**
+ * One object-graph redaction walk, shared by everything that records a value it
+ * did not choose.
+ *
+ * Several packages need the same thing: copy a value, replace what a key name
+ * says is a secret, and come back with something `JSON.stringify` survives. Each
+ * had written its own — and each had to solve the same three hazards, which are
+ * the parts that are easy to get subtly wrong:
+ *
+ * - **Cycles.** A model holding a back-reference to its parent is ordinary, and
+ *   `JSON.stringify` throws on it. The ancestor set is released on the way back
+ *   *up*, so a value that legitimately appears twice as a sibling is rendered
+ *   twice rather than reported as a cycle the second time.
+ * - **Depth.** Recording happens on the request path, so a pathological graph
+ *   must not stall it.
+ * - **Values that read better flat than walked.** A `Date`, a `File`, an `Error`
+ *   — `Object.entries` on any of them produces something worse than useless.
+ *
+ * What it deliberately does *not* fix is the vocabulary. Callers bring their own
+ * markers and their own sensitivity predicate, because those are not
+ * interchangeable: a devtools panel's `‹redacted›` is a display choice, while an
+ * adapter implementing a published wire protocol has its markers specified for
+ * it. Sharing the walk does not mean agreeing on the words.
+ */
+
+/** How one caller wants the graph walked. */
+export interface RedactGraphOptions {
+  /** Whether the value under this key should be withheld. */
+  sensitive: (key: string) => boolean;
+  /** What a withheld value is replaced with. */
+  mask: string;
+  /** What a reference back to an ancestor is replaced with. */
+  circular: string;
+  /** What a value at or below the depth limit is replaced with. */
+  tooDeep: string;
+  /**
+   * The depth at which the walk stops. The root is depth 0, so `6` renders five
+   * levels of nesting and replaces the sixth.
+   */
+  maxDepth: number;
+  /**
+   * Render a value instead of walking into it — a `Date` as an ISO string, a
+   * `File` as a summary. Return `undefined` to walk it normally.
+   *
+   * Called for every non-null value, before the cycle and depth checks, so a
+   * flattened value is never reported as either — and so a caller can also name
+   * things that are not objects at all. A function is the case worth having:
+   * `JSON.stringify` drops the key it sits under, and a debugging tool that
+   * silently omits a field is worse than one that says `‹fn›`.
+   */
+  flatten?: (value: unknown) => string | undefined;
+}
+
+/**
+ * Copy `value`, masking every field whose name `options.sensitive` rejects.
+ *
+ * A primitive is returned unchanged — there is no key to judge it by, and
+ * inspecting a string's *contents* for things that look like secrets is a
+ * different, guessier job this does not attempt.
+ *
+ * @param value - Anything. Not modified.
+ * @param options - Markers, limits, and the sensitivity predicate.
+ * @returns A new value, safe to serialise.
+ */
+export function redactGraph(value: unknown, options: RedactGraphOptions): unknown {
+  return _walk(value, options, 0, new WeakSet());
+}
+
+function _walk(
+  value: unknown,
+  options: RedactGraphOptions,
+  depth: number,
+  seen: WeakSet<object>,
+): unknown {
+  if (value === null) return null;
+
+  const flat = options.flatten?.(value);
+  if (flat !== undefined) return flat;
+  if (typeof value !== "object") return value;
+
+  const object = value as object;
+  if (seen.has(object)) return options.circular;
+  if (depth >= options.maxDepth) return options.tooDeep;
+
+  seen.add(object);
+  try {
+    if (Array.isArray(object)) {
+      return object.map((item) => _walk(item, options, depth + 1, seen));
+    }
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(object as Record<string, unknown>)) {
+      // A boolean is never a secret. It has two possible values, so masking one
+      // conceals nothing a reader could not guess — while destroying the answer
+      // they came for. Names are matched by substring, so this is not
+      // hypothetical: `cors.credentials` contains "credential" and came back as
+      // `‹redacted›` on the DevTools Config tab, hiding whether credentialed
+      // CORS was on. That is a security setting a reader is checking *because*
+      // it matters.
+      const maskable = typeof item !== "boolean";
+      out[key] =
+        maskable && options.sensitive(key) ? options.mask : _walk(item, options, depth + 1, seen);
+    }
+    return out;
+  } finally {
+    seen.delete(object);
+  }
+}