fbi-proxy 1.9.1 → 1.10.0

package/ts/cli.ts

@@ -6,19 +6,70 @@ import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { getFbiProxyBinary } from "./buildFbiProxy";
 import { $ } from "./dSpawn";
+import {
+  configFromEnv,
+  defaultConfigPath,
+  helpfulSetupMessage,
+  readConfigOrNull,
+  writeConfig,
+} from "./auth/authConfig";
+import { spawnFbiAuth, type FbiAuthHandle } from "./auth/spawnFbiAuth";
+import { isTty, readlinePrompter, runWizard } from "./auth/setupWizard";
+import {
+  defaultCaddyfilePath,
+  writeCaddyfile,
+  type CaddyfileOpts,
+} from "./auth/caddyfileGen";
+import {
+  caddyNotFoundMessage,
+  resolveCaddyBinary,
+  spawnCaddy,
+  type CaddyHandle,
+} from "./auth/spawnCaddy";
 
-// Save original cwd before changing (user might have local build there)
 const originalCwd = process.cwd();
-process.chdir(path.resolve(import.meta.dir, "..")); // Change to project root directory
+process.chdir(path.resolve(import.meta.dir, ".."));
 
-// Parse command line arguments with yargs
-await yargs(hideBin(process.argv))
+const argv = await yargs(hideBin(process.argv))
   .option("dev", {
-    alias: "d",
     type: "boolean",
     default: false,
     description: "Run in development mode",
   })
+  .option("with-auth", {
+    type: "boolean",
+    default: false,
+    description:
+      "Start the fbi-auth gateway alongside the proxy (Phase 1: Google OAuth)",
+  })
+  .option("with-caddy", {
+    type: "boolean",
+    default: false,
+    description:
+      "Auto-generate a Caddyfile and spawn Caddy alongside the proxy",
+  })
+  .option("domain", {
+    type: "string",
+    default: "fbi.com",
+    description: "Domain to gate (default: fbi.com)",
+  })
+  .option("reconfigure", {
+    type: "boolean",
+    default: false,
+    description:
+      "Run the interactive fbi-auth setup wizard to (re)write auth.json (requires a TTY)",
+  })
+  .option("acme-email", {
+    type: "string",
+    description:
+      "Optional ACME account email for the generated Caddyfile (Let's Encrypt notifications)",
+  })
+  .option("tls-mode", {
+    type: "string",
+    choices: ["auto", "internal"] as const,
+    description:
+      "TLS strategy for --with-caddy. 'auto' uses ACME (Let's Encrypt); 'internal' uses Caddy's local CA. Defaults to 'internal' for fbi.com, 'auto' otherwise.",
+  })
   .help().argv;
 
 console.log("Preparing Binaries");
@@ -32,7 +83,7 @@ const proxyProcess = await hotMemo(async () => {
   const p = $.opt({
     env: {
       ...process.env,
-      FBI_PROXY_PORT, // Rust proxy server port
+      FBI_PROXY_PORT,
     },
   })`${proxy}`.process;
 
@@ -43,12 +94,37 @@ const proxyProcess = await hotMemo(async () => {
   return p;
 });
 
-console.log("All services started successfully!");
 console.log(`Proxy server PID: ${proxyProcess.pid}`);
 console.log(`Proxy server running on port: ${FBI_PROXY_PORT}`);
 
+let authHandle: FbiAuthHandle | undefined;
+if (argv["with-auth"]) {
+  authHandle = await startFbiAuth({
+    domain: argv.domain,
+    reconfigure: argv.reconfigure,
+  });
+}
+
+let caddyHandle: CaddyHandle | undefined;
+if (argv["with-caddy"]) {
+  caddyHandle =
+    (await startCaddy({
+      domain: argv.domain,
+      fbiProxyPort: Number(FBI_PROXY_PORT),
+      fbiAuthPort: authHandle?.port,
+      withAuth: Boolean(argv["with-auth"]),
+      acmeEmail: argv["acme-email"],
+      tlsMode:
+        (argv["tls-mode"] as "auto" | "internal" | undefined) ?? undefined,
+    })) ?? undefined;
+}
+
+console.log("All services started successfully!");
+
 const exit = () => {
   console.log("Shutting down...");
+  caddyHandle?.kill();
+  authHandle?.kill();
   proxyProcess?.kill?.();
   process.exit(0);
 };
@@ -58,3 +134,110 @@ process.on("uncaughtException", (err) => {
   console.error("Uncaught exception:", err);
   exit();
 });
+
+async function startFbiAuth(opts: {
+  domain: string;
+  reconfigure: boolean;
+}): Promise<FbiAuthHandle | undefined> {
+  const configPath = defaultConfigPath();
+  let cfg = await readConfigOrNull(configPath);
+
+  if (opts.reconfigure) {
+    if (!isTty()) {
+      console.error(
+        "[fbi-auth] --reconfigure requires a TTY (interactive terminal).",
+      );
+      return undefined;
+    }
+    const prompter = readlinePrompter();
+    cfg = await runWizard(prompter, { domain: opts.domain, existing: cfg });
+    console.log(`[fbi-auth] writing config from wizard → ${configPath}`);
+    await writeConfig(cfg, configPath);
+  } else if (!cfg) {
+    if (isTty()) {
+      const prompter = readlinePrompter();
+      cfg = await runWizard(prompter, { domain: opts.domain, existing: null });
+      console.log(`[fbi-auth] writing config from wizard → ${configPath}`);
+      await writeConfig(cfg, configPath);
+    } else {
+      const fromEnv = configFromEnv(opts.domain);
+      if (fromEnv) {
+        console.log(`[fbi-auth] writing config from env vars → ${configPath}`);
+        await writeConfig(fromEnv, configPath);
+        cfg = fromEnv;
+      } else {
+        console.error(helpfulSetupMessage(opts.domain, configPath));
+        console.error(
+          "[fbi-auth] not started — --with-auth requires a config, env vars, or a TTY for the wizard.",
+        );
+        return undefined;
+      }
+    }
+  }
+
+  console.log(
+    `[fbi-auth] starting (domain=${cfg.domain}, provider=${cfg.provider})`,
+  );
+  const handle = await spawnFbiAuth({ configPath });
+  console.log(
+    `[fbi-auth] PID ${handle.pid} listening on 127.0.0.1:${handle.port}`,
+  );
+  return handle;
+}
+
+async function startCaddy(opts: {
+  domain: string;
+  fbiProxyPort: number;
+  fbiAuthPort: number | undefined;
+  withAuth: boolean;
+  acmeEmail?: string;
+  tlsMode?: "auto" | "internal";
+}): Promise<CaddyHandle | null> {
+  // Verify Caddy is present before generating anything, so the error message
+  // is the first thing the user sees instead of a stray Caddyfile on disk.
+  const binary = await resolveCaddyBinary();
+  if (!binary) {
+    console.error(caddyNotFoundMessage());
+    return null;
+  }
+
+  if (opts.withAuth && opts.fbiAuthPort === undefined) {
+    console.error(
+      "[caddy] --with-auth was requested but fbi-auth failed to start; refusing to spawn Caddy with a broken forward_auth target.",
+    );
+    return null;
+  }
+
+  const domain = opts.domain.startsWith(".")
+    ? opts.domain.slice(1)
+    : opts.domain;
+  const tlsMode: "auto" | "internal" =
+    opts.tlsMode ?? (domain === "fbi.com" ? "internal" : "auto");
+
+  const caddyOpts: CaddyfileOpts = {
+    domain,
+    fbiProxyPort: opts.fbiProxyPort,
+    tlsMode,
+    acmeEmail: opts.acmeEmail,
+    withAuth: opts.withAuth,
+    ...(opts.withAuth && opts.fbiAuthPort !== undefined
+      ? {
+          ssoHost: `sso.${domain}`,
+          fbiAuthPort: opts.fbiAuthPort,
+        }
+      : {}),
+  };
+
+  const caddyfilePath = defaultCaddyfilePath();
+  const { path: writtenPath } = await writeCaddyfile(caddyOpts, caddyfilePath);
+  console.log(`[caddy] wrote Caddyfile → ${writtenPath}`);
+  console.log(
+    `[caddy] domain=${domain} tlsMode=${tlsMode} withAuth=${opts.withAuth}`,
+  );
+
+  const handle = await spawnCaddy({ caddyfilePath: writtenPath, binary });
+  if (handle) {
+    console.log(`[caddy] PID ${handle.pid}`);
+  }
+  return handle;
+}

package/ts/dSpawn.ts

@@ -15,10 +15,7 @@ type DRunProc = Promise<{
   process: ChildProcess;
 };
 
-const dSpawn = ({
-  cwd = process.cwd(),
-  env = process.env as Record<string, string>,
-} = {}) =>
+const dSpawn = ({ cwd = process.cwd(), env = process.env as Record<string, string> } = {}) =>
   tsaComposer(
     // slot is un dividable
     (slot: string | { raw: string }) =>
@@ -64,11 +61,9 @@ const dSpawn = ({
         });
 
         // Main promise that resolves with combined result (also lazy)
-        const mainPromise = Promise.all([
-          outPromise,
-          errPromise,
-          codePromise,
-        ]).then(([out, err, code]) => ({ out, err, code }));
+        const mainPromise = Promise.all([outPromise, errPromise, codePromise]).then(
+          ([out, err, code]) => ({ out, err, code }),
+        );
 
         // Create the proxy object that combines Promise with additional properties
         const result = new Proxy(mainPromise, {

package/ts/getProxyFilename.ts

@@ -1,11 +1,13 @@
 export function getFbiProxyFilename() {
-    return {
-        "darwin-arm64": "fbi-proxy-darwin",
-        "darwin-x64": "fbi-proxy-darwin",
-        "linux-arm64": "fbi-proxy-linux-arm64",
-        "linux-x64": "fbi-proxy-linux-x64",
-        "linux-x86_64": "fbi-proxy-linux-x64",
-        "win32-arm64": "fbi-proxy-windows-arm64.exe",
-        "win32-x64": "fbi-proxy-windows-x64.exe",
-    }[process.platform + "-" + process.arch] || "fbi-proxy-linux-x64";
+  return (
+    {
+      "darwin-arm64": "fbi-proxy-darwin",
+      "darwin-x64": "fbi-proxy-darwin",
+      "linux-arm64": "fbi-proxy-linux-arm64",
+      "linux-x64": "fbi-proxy-linux-x64",
+      "linux-x86_64": "fbi-proxy-linux-x64",
+      "win32-arm64": "fbi-proxy-windows-arm64.exe",
+      "win32-x64": "fbi-proxy-windows-x64.exe",
+    }[process.platform + "-" + process.arch] || "fbi-proxy-linux-x64"
+  );
 }

package/ts/routes.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it } from "vitest";
+import { parseRoutesYaml, validateRoute, type RouteConfig } from "./routes.ts";
+
+const defaultYaml = `
+version: 1
+routes:
+  - name: port-as-host
+    match: "{port:int}.{domain}"
+    target: "127.0.0.1:{port}"
+
+  - name: host-double-dash-port
+    match: "{host}--{port:int}.{domain}"
+    target: "{host}:{port}"
+    headers:
+      Host: "{host}"
+
+  - name: subdomain-hoisting
+    match: "{prefix}.{host}.{domain}"
+    target: "{host}:80"
+    headers:
+      Host: "{prefix}"
+
+  - name: direct-forward
+    match: "{host}.{domain}"
+    target: "{host}:80"
+    headers:
+      Host: "{host}"
+`;
+
+describe("parseRoutesYaml", () => {
+  it("parses the default 4-rule config", () => {
+    const f = parseRoutesYaml(defaultYaml);
+    expect(f.version).toBe(1);
+    expect(f.routes).toHaveLength(4);
+    expect(f.routes[0]).toEqual({
+      name: "port-as-host",
+      match: "{port:int}.{domain}",
+      target: "127.0.0.1:{port}",
+      headers: undefined,
+    });
+    expect(f.routes[1].headers).toEqual({ Host: "{host}" });
+  });
+
+  it("defaults missing version to 1", () => {
+    const f = parseRoutesYaml(
+      `routes:\n  - name: x\n    match: "{a}"\n    target: "b"\n`,
+    );
+    expect(f.version).toBe(1);
+  });
+
+  it("rejects unsupported version", () => {
+    expect(() => parseRoutesYaml(`version: 2\nroutes: []\n`)).toThrow(
+      /unsupported version/,
+    );
+  });
+
+  it("rejects non-mapping top-level", () => {
+    expect(() => parseRoutesYaml(`- a\n- b\n`)).toThrow(/mapping/);
+  });
+
+  it("rejects missing routes field", () => {
+    expect(() => parseRoutesYaml(`version: 1\n`)).toThrow(
+      /`routes` must be a list/,
+    );
+  });
+
+  it("rejects entry missing name", () => {
+    expect(() =>
+      parseRoutesYaml(
+        `version: 1\nroutes:\n  - match: "{a}"\n    target: "b"\n`,
+      ),
+    ).toThrow(/missing a string `name`/);
+  });
+
+  it("rejects entry missing match", () => {
+    expect(() =>
+      parseRoutesYaml(`version: 1\nroutes:\n  - name: x\n    target: "b"\n`),
+    ).toThrow(/missing a string `match`/);
+  });
+
+  it("rejects non-string header value", () => {
+    expect(() =>
+      parseRoutesYaml(
+        `version: 1\nroutes:\n  - name: x\n    match: "{a}"\n    target: "b"\n    headers:\n      Host: 123\n`,
+      ),
+    ).toThrow(/must be a string/);
+  });
+});
+
+describe("validateRoute", () => {
+  const good: RouteConfig = {
+    name: "ok",
+    match: "{port:int}.{domain}",
+    target: "127.0.0.1:{port}",
+    headers: { Host: "{domain}" },
+  };
+
+  it("accepts a valid route", () => {
+    expect(validateRoute(good)).toEqual({ valid: true });
+  });
+
+  it("rejects empty name", () => {
+    expect(validateRoute({ ...good, name: "" })).toEqual({
+      valid: false,
+      reason: "route name is required",
+    });
+  });
+
+  it("rejects unbalanced braces in match", () => {
+    expect(validateRoute({ ...good, match: "{port" })).toMatchObject({
+      valid: false,
+      reason: /unbalanced braces in `match`/,
+    });
+  });
+
+  it("rejects unknown placeholder kind", () => {
+    const result = validateRoute({ ...good, match: "{port:zzz}.{domain}" });
+    expect(result.valid).toBe(false);
+    if (!result.valid)
+      expect(result.reason).toMatch(/unknown placeholder kind ':zzz'/);
+  });
+
+  it("rejects undeclared placeholder in target", () => {
+    const result = validateRoute({
+      ...good,
+      match: "{a}.{b}",
+      target: "{c}",
+    });
+    expect(result.valid).toBe(false);
+    if (!result.valid) expect(result.reason).toMatch(/'{c}' used in `target`/);
+  });
+
+  it("rejects undeclared placeholder in header", () => {
+    const result = validateRoute({
+      ...good,
+      match: "{a}.{b}",
+      target: "x",
+      headers: { Host: "{nope}" },
+    });
+    expect(result.valid).toBe(false);
+    if (!result.valid)
+      expect(result.reason).toMatch(/'{nope}' used in header 'Host'/);
+  });
+
+  it("rejects duplicate placeholder in match", () => {
+    const result = validateRoute({ ...good, match: "{a}.{a}", target: "x" });
+    expect(result.valid).toBe(false);
+    if (!result.valid) expect(result.reason).toMatch(/'{a}' declared twice/);
+  });
+
+  it("rejects invalid placeholder name", () => {
+    const result = validateRoute({ ...good, match: "{1foo}", target: "x" });
+    expect(result.valid).toBe(false);
+    if (!result.valid)
+      expect(result.reason).toMatch(/invalid placeholder name/);
+  });
+
+  it("validates all four default rules", () => {
+    const f = parseRoutesYaml(defaultYaml);
+    for (const r of f.routes) {
+      expect(validateRoute(r)).toEqual({ valid: true });
+    }
+  });
+
+  it("accepts {name:multi} for DNS-passthrough patterns", () => {
+    const dnsRoute: RouteConfig = {
+      name: "dns-passthrough",
+      match: "{upstream:multi}.{domain}",
+      target: "{upstream}:80",
+    };
+    expect(validateRoute(dnsRoute)).toEqual({ valid: true });
+  });
+
+  it("rejects {name:wrong} but accepts {name:multi}", () => {
+    expect(
+      validateRoute({ ...good, match: "{x:wrong}.{domain}", target: "x" }),
+    ).toMatchObject({ valid: false });
+    expect(
+      validateRoute({ ...good, match: "{x:multi}.{domain}", target: "{x}" }),
+    ).toEqual({ valid: true });
+  });
+});

package/ts/routes.ts

@@ -0,0 +1,238 @@
+/**
+ * Route configuration types for fbi-proxy's rule-based router.
+ *
+ * The matching engine itself lives in `rs/routes.rs` (Rust). This
+ * TypeScript module mirrors the public configuration shape so that
+ * CLI / wizard code can author, parse, and validate `routes.yaml`
+ * documents without invoking the Rust binary.
+ *
+ * See `docs/routing.md` for the user-facing reference.
+ */
+
+import YAML from "yaml";
+
+/** A placeholder declared in a route's `match` pattern. */
+export type Placeholder = {
+  name: string;
+  kind: "any" | "int" | "slug" | "multi";
+};
+
+/** A single route entry in `routes.yaml`. */
+export type RouteConfig = {
+  /** Human-readable name (also used as a debug label). */
+  name: string;
+  /**
+   * Pattern matched against the (port-stripped, lowercased) Host header.
+   * Placeholders: `{name}` (any segment), `{name:int}`, `{name:slug}`,
+   * `{name:multi}` (one or more dot-segments — for DNS-passthrough).
+   */
+  match: string;
+  /**
+   * Target template. Expanded with placeholder captures from `match`.
+   * E.g. `"127.0.0.1:{port}"`.
+   */
+  target: string;
+  /**
+   * Optional header templates. `Host` is treated specially by the
+   * proxy (it rewrites the outgoing Host header); other entries are
+   * added to the upstream request as-is.
+   */
+  headers?: Record<string, string>;
+};
+
+/** Top-level shape of `routes.yaml`. */
+export type RoutesFile = {
+  version: 1;
+  routes: RouteConfig[];
+};
+
+/** Result type for `validateRoute`. */
+export type ValidationResult =
+  | { valid: true }
+  | { valid: false; reason: string };
+
+/**
+ * Parse a YAML string into a `RoutesFile`. Throws on syntactically
+ * invalid YAML or on missing required fields. Does NOT compile the
+ * `match` patterns — call into the Rust engine for that.
+ */
+export function parseRoutesYaml(yaml: string): RoutesFile {
+  const raw = YAML.parse(yaml);
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("routes.yaml must be a YAML mapping at the top level");
+  }
+  const obj = raw as Record<string, unknown>;
+  const version = (obj.version ?? 1) as number;
+  if (version !== 1) {
+    throw new Error(`routes.yaml: unsupported version ${version} (expected 1)`);
+  }
+  if (!Array.isArray(obj.routes)) {
+    throw new Error("routes.yaml: `routes` must be a list");
+  }
+  const routes: RouteConfig[] = [];
+  for (let i = 0; i < obj.routes.length; i++) {
+    const entry = obj.routes[i];
+    if (entry == null || typeof entry !== "object") {
+      throw new Error(`routes.yaml: entry #${i} must be a mapping`);
+    }
+    const e = entry as Record<string, unknown>;
+    if (typeof e.name !== "string" || e.name.length === 0) {
+      throw new Error(`routes.yaml: entry #${i} is missing a string \`name\``);
+    }
+    if (typeof e.match !== "string" || e.match.length === 0) {
+      throw new Error(
+        `routes.yaml: entry '${e.name}' is missing a string \`match\``,
+      );
+    }
+    if (typeof e.target !== "string" || e.target.length === 0) {
+      throw new Error(
+        `routes.yaml: entry '${e.name}' is missing a string \`target\``,
+      );
+    }
+    let headers: Record<string, string> | undefined;
+    if (e.headers != null) {
+      if (typeof e.headers !== "object" || Array.isArray(e.headers)) {
+        throw new Error(
+          `routes.yaml: entry '${e.name}': \`headers\` must be a mapping`,
+        );
+      }
+      headers = {};
+      for (const [hk, hv] of Object.entries(
+        e.headers as Record<string, unknown>,
+      )) {
+        if (typeof hv !== "string") {
+          throw new Error(
+            `routes.yaml: entry '${e.name}': header '${hk}' must be a string`,
+          );
+        }
+        headers[hk] = hv;
+      }
+    }
+    routes.push({
+      name: e.name,
+      match: e.match,
+      target: e.target,
+      headers,
+    });
+  }
+  return { version: 1, routes };
+}
+
+const PLACEHOLDER_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const VALID_KINDS = new Set(["", "int", "slug", "multi"]);
+
+/** Find all `{name[:kind]}` placeholders in `s`. */
+function placeholdersIn(s: string): Placeholder[] {
+  const out: Placeholder[] = [];
+  const re = /\{([^}]*)\}/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(s)) !== null) {
+    const spec = m[1];
+    const idx = spec.indexOf(":");
+    const name = idx === -1 ? spec : spec.slice(0, idx);
+    const rawKind = idx === -1 ? "" : spec.slice(idx + 1);
+    let kind: Placeholder["kind"];
+    if (rawKind === "" || rawKind === "any") kind = "any";
+    else if (rawKind === "int") kind = "int";
+    else if (rawKind === "slug") kind = "slug";
+    else if (rawKind === "multi") kind = "multi";
+    else kind = "any"; // validation pass will reject if not in VALID_KINDS
+    out.push({ name, kind });
+  }
+  return out;
+}
+
+function bracesBalanced(s: string): boolean {
+  let depth = 0;
+  for (const c of s) {
+    if (c === "{") depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth < 0) return false;
+    }
+  }
+  return depth === 0;
+}
+
+/**
+ * Validate a single route entry. Returns `{valid: true}` or
+ * `{valid: false, reason}`. This is the same set of checks the Rust
+ * compiler runs at startup, kept in sync for editor-time validation.
+ */
+export function validateRoute(r: RouteConfig): ValidationResult {
+  if (!r.name) return { valid: false, reason: "route name is required" };
+  if (!r.match) return { valid: false, reason: "route `match` is required" };
+  if (!r.target) return { valid: false, reason: "route `target` is required" };
+
+  if (!bracesBalanced(r.match))
+    return { valid: false, reason: "unbalanced braces in `match`" };
+  if (!bracesBalanced(r.target))
+    return { valid: false, reason: "unbalanced braces in `target`" };
+
+  // Verify placeholder names + kinds in match
+  const declared = new Set<string>();
+  const matchPhs = placeholdersIn(r.match);
+  // Re-scan match raw to catch unknown kinds (placeholdersIn coerces them).
+  const rawMatchRe = /\{([^}]*)\}/g;
+  let mm: RegExpExecArray | null;
+  while ((mm = rawMatchRe.exec(r.match)) !== null) {
+    const spec = mm[1];
+    const idx = spec.indexOf(":");
+    const name = idx === -1 ? spec : spec.slice(0, idx);
+    const kind = idx === -1 ? "" : spec.slice(idx + 1);
+    if (!PLACEHOLDER_NAME_RE.test(name))
+      return {
+        valid: false,
+        reason: `invalid placeholder name '{${spec}}' in \`match\``,
+      };
+    if (!VALID_KINDS.has(kind))
+      return {
+        valid: false,
+        reason: `unknown placeholder kind ':${kind}' for '{${name}}' (expected int|slug|multi)`,
+      };
+    if (declared.has(name))
+      return {
+        valid: false,
+        reason: `placeholder '{${name}}' declared twice in \`match\``,
+      };
+    declared.add(name);
+  }
+  void matchPhs;
+
+  // Verify target / headers reference only declared placeholders
+  for (const ph of placeholdersIn(r.target)) {
+    if (!PLACEHOLDER_NAME_RE.test(ph.name))
+      return {
+        valid: false,
+        reason: `invalid placeholder name '{${ph.name}}' in \`target\``,
+      };
+    if (!declared.has(ph.name))
+      return {
+        valid: false,
+        reason: `placeholder '{${ph.name}}' used in \`target\` but not declared in \`match\``,
+      };
+  }
+  if (r.headers) {
+    for (const [hk, hv] of Object.entries(r.headers)) {
+      if (!bracesBalanced(hv))
+        return {
+          valid: false,
+          reason: `unbalanced braces in header '${hk}'`,
+        };
+      for (const ph of placeholdersIn(hv)) {
+        if (!PLACEHOLDER_NAME_RE.test(ph.name))
+          return {
+            valid: false,
+            reason: `invalid placeholder name '{${ph.name}}' in header '${hk}'`,
+          };
+        if (!declared.has(ph.name))
+          return {
+            valid: false,
+            reason: `placeholder '{${ph.name}}' used in header '${hk}' but not declared in \`match\``,
+          };
+      }
+    }
+  }
+
+  return { valid: true };
+}