Gateway: wide-area Bonjour via clawdis.internal

src/cli/dns-cli.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it, vi } from "vitest";
+
+const { buildProgram } = await import("./program.js");
+
+describe("dns cli", () => {
+  it("prints setup info (no apply)", async () => {
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const program = buildProgram();
+    await program.parseAsync(["dns", "setup"], { from: "user" });
+    expect(log).toHaveBeenCalledWith(expect.stringContaining("Domain:"));
+  });
+});

src/cli/dns-cli.ts

@@ -0,0 +1,169 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import type { Command } from "commander";
+
+import { loadConfig } from "../config/config.js";
+import {
+  pickPrimaryTailnetIPv4,
+  pickPrimaryTailnetIPv6,
+} from "../infra/tailnet.js";
+import {
+  getWideAreaZonePath,
+  WIDE_AREA_DISCOVERY_DOMAIN,
+} from "../infra/widearea-dns.js";
+
+type RunOpts = { allowFailure?: boolean; inherit?: boolean };
+
+function run(cmd: string, args: string[], opts?: RunOpts): string {
+  const res = spawnSync(cmd, args, {
+    encoding: "utf-8",
+    stdio: opts?.inherit ? "inherit" : "pipe",
+  });
+  if (res.error) throw res.error;
+  if (!opts?.allowFailure && res.status !== 0) {
+    const errText =
+      typeof res.stderr === "string" && res.stderr.trim()
+        ? res.stderr.trim()
+        : `exit ${res.status ?? "unknown"}`;
+    throw new Error(`${cmd} ${args.join(" ")} failed: ${errText}`);
+  }
+  return typeof res.stdout === "string" ? res.stdout : "";
+}
+
+function detectBrewPrefix(): string {
+  const out = run("brew", ["--prefix"]);
+  const prefix = out.trim();
+  if (!prefix) throw new Error("failed to resolve Homebrew prefix");
+  return prefix;
+}
+
+function ensureImportLine(corefilePath: string, importGlob: string): boolean {
+  const existing = fs.readFileSync(corefilePath, "utf-8");
+  if (existing.includes(importGlob)) return false;
+  const next = `${existing.replace(/\s*$/, "")}\n\nimport ${importGlob}\n`;
+  fs.writeFileSync(corefilePath, next, "utf-8");
+  return true;
+}
+
+export function registerDnsCli(program: Command) {
+  const dns = program
+    .command("dns")
+    .description("DNS helpers for wide-area discovery (Tailscale + CoreDNS)");
+
+  dns
+    .command("setup")
+    .description(
+      "Set up CoreDNS to serve clawdis.internal for unicast DNS-SD (Wide-Area Bonjour)",
+    )
+    .option(
+      "--apply",
+      "Install/update CoreDNS config and (re)start the service (requires sudo)",
+      false,
+    )
+    .action(async (opts) => {
+      const cfg = loadConfig();
+      const tailnetIPv4 = pickPrimaryTailnetIPv4();
+      const tailnetIPv6 = pickPrimaryTailnetIPv6();
+      const zonePath = getWideAreaZonePath();
+
+      console.log(`Domain: ${WIDE_AREA_DISCOVERY_DOMAIN}`);
+      console.log(`Zone file (gateway-owned): ${zonePath}`);
+      console.log(
+        `Detected tailnet IP: ${tailnetIPv4 ?? "—"}${tailnetIPv6 ? ` (v6 ${tailnetIPv6})` : ""}`,
+      );
+      console.log("");
+      console.log("Recommended ~/.clawdis/clawdis.json:");
+      console.log(
+        JSON.stringify(
+          {
+            bridge: { bind: "tailnet" },
+            discovery: { wideArea: { enabled: true } },
+          },
+          null,
+          2,
+        ),
+      );
+      console.log("");
+      console.log("Tailscale admin (DNS → Nameservers):");
+      console.log(
+        `- Add nameserver: ${tailnetIPv4 ?? "<this machine's tailnet IPv4>"}`,
+      );
+      console.log(`- Restrict to domain (Split DNS): clawdis.internal`);
+
+      if (!opts.apply) {
+        console.log("");
+        console.log("Run with --apply to install CoreDNS and configure it.");
+        return;
+      }
+
+      if (process.platform !== "darwin") {
+        throw new Error("dns setup is currently supported on macOS only");
+      }
+      if (!tailnetIPv4 && !tailnetIPv6) {
+        throw new Error(
+          "no tailnet IP detected; ensure Tailscale is running on this machine",
+        );
+      }
+
+      const prefix = detectBrewPrefix();
+      const etcDir = path.join(prefix, "etc", "coredns");
+      const corefilePath = path.join(etcDir, "Corefile");
+      const confDir = path.join(etcDir, "conf.d");
+      const importGlob = path.join(confDir, "*.server");
+      const serverPath = path.join(confDir, "clawdis.internal.server");
+
+      run("brew", ["list", "coredns"], { allowFailure: true });
+      run("brew", ["install", "coredns"], {
+        inherit: true,
+        allowFailure: true,
+      });
+
+      await fs.promises.mkdir(confDir, { recursive: true });
+
+      if (fs.existsSync(corefilePath)) {
+        ensureImportLine(corefilePath, importGlob);
+      }
+
+      const bindArgs = [tailnetIPv4, tailnetIPv6].filter((v): v is string =>
+        Boolean(v?.trim()),
+      );
+
+      const server = [
+        `${WIDE_AREA_DISCOVERY_DOMAIN.replace(/\.$/, "")}:53 {`,
+        `  bind ${bindArgs.join(" ")}`,
+        `  file ${zonePath} {`,
+        `    reload 10s`,
+        `  }`,
+        `  errors`,
+        `  log`,
+        `}`,
+        ``,
+      ].join("\n");
+      fs.writeFileSync(serverPath, server, "utf-8");
+
+      // Ensure the gateway can write its zone file path.
+      await fs.promises.mkdir(path.dirname(zonePath), { recursive: true });
+      if (!fs.existsSync(zonePath)) {
+        fs.writeFileSync(
+          zonePath,
+          `; created by clawdis dns setup\n$ORIGIN ${WIDE_AREA_DISCOVERY_DOMAIN}\n$TTL 60\n`,
+          "utf-8",
+        );
+      }
+
+      console.log("");
+      console.log("Starting CoreDNS (sudo)…");
+      run("sudo", ["brew", "services", "restart", "coredns"], {
+        inherit: true,
+      });
+
+      if (cfg.discovery?.wideArea?.enabled !== true) {
+        console.log("");
+        console.log(
+          "Note: enable discovery.wideArea.enabled in ~/.clawdis/clawdis.json on the gateway and restart the gateway so it writes the DNS-SD zone.",
+        );
+      }
+    });
+}

src/cli/program.ts

@@ -29,6 +29,7 @@ import { VERSION } from "../version.js";
 import { startWebChatServer } from "../webchat/server.js";
 import { registerCronCli } from "./cron-cli.js";
 import { createDefaultDeps } from "./deps.js";
+import { registerDnsCli } from "./dns-cli.js";
 import { registerGatewayCli } from "./gateway-cli.js";
 import { registerNodesCli } from "./nodes-cli.js";
 import { forceFreePort } from "./ports.js";
@@ -248,6 +249,7 @@ Examples:
   registerGatewayCli(program);
   registerNodesCli(program);
   registerCronCli(program);
+  registerDnsCli(program);
 
   program
     .command("status")

src/config/config.ts

@@ -75,6 +75,29 @@ export type GroupChatConfig = {
   historyLimit?: number;
 };
 
+export type BridgeBindMode = "auto" | "lan" | "tailnet" | "loopback";
+
+export type BridgeConfig = {
+  enabled?: boolean;
+  port?: number;
+  /**
+   * Bind address policy for the Iris bridge server.
+   * - auto: prefer tailnet IP when present, else LAN (0.0.0.0)
+   * - lan:  0.0.0.0 (reachable on local network + any forwarded interfaces)
+   * - tailnet: bind only to the Tailscale interface IP (100.64.0.0/10)
+   * - loopback: 127.0.0.1
+   */
+  bind?: BridgeBindMode;
+};
+
+export type WideAreaDiscoveryConfig = {
+  enabled?: boolean;
+};
+
+export type DiscoveryConfig = {
+  wideArea?: WideAreaDiscoveryConfig;
+};
+
 export type ClawdisConfig = {
   identity?: {
     name?: string;
@@ -120,6 +143,8 @@ export type ClawdisConfig = {
   telegram?: TelegramConfig;
   webchat?: WebChatConfig;
   cron?: CronConfig;
+  bridge?: BridgeConfig;
+  discovery?: DiscoveryConfig;
 };
 
 // New branding path (preferred)
@@ -259,6 +284,29 @@ const ClawdisSchema = z.object({
       webhookPath: z.string().optional(),
     })
     .optional(),
+  bridge: z
+    .object({
+      enabled: z.boolean().optional(),
+      port: z.number().int().positive().optional(),
+      bind: z
+        .union([
+          z.literal("auto"),
+          z.literal("lan"),
+          z.literal("tailnet"),
+          z.literal("loopback"),
+        ])
+        .optional(),
+    })
+    .optional(),
+  discovery: z
+    .object({
+      wideArea: z
+        .object({
+          enabled: z.boolean().optional(),
+        })
+        .optional(),
+    })
+    .optional(),
 });
 
 function escapeRegExp(text: string): string {

src/gateway/server.ts

@@ -61,11 +61,19 @@ import {
   updateSystemPresence,
   upsertPresence,
 } from "../infra/system-presence.js";
+import {
+  pickPrimaryTailnetIPv4,
+  pickPrimaryTailnetIPv6,
+} from "../infra/tailnet.js";
 import {
   defaultVoiceWakeTriggers,
   loadVoiceWakeConfig,
   setVoiceWakeTriggers,
 } from "../infra/voicewake.js";
+import {
+  WIDE_AREA_DISCOVERY_DOMAIN,
+  writeWideAreaBridgeZone,
+} from "../infra/widearea-dns.js";
 import { logError, logInfo, logWarn } from "../logger.js";
 import {
   getChildLogger,
@@ -715,12 +723,51 @@ export async function startGatewayServer(
     }
   };
 
-  const bridgeHost = process.env.CLAWDIS_BRIDGE_HOST ?? "0.0.0.0";
-  const bridgePort =
-    process.env.CLAWDIS_BRIDGE_PORT !== undefined
-      ? Number.parseInt(process.env.CLAWDIS_BRIDGE_PORT, 10)
-      : 18790;
-  const bridgeEnabled = process.env.CLAWDIS_BRIDGE_ENABLED !== "0";
+  const wideAreaDiscoveryEnabled =
+    cfgAtStart.discovery?.wideArea?.enabled === true;
+
+  const bridgeEnabled = (() => {
+    if (cfgAtStart.bridge?.enabled !== undefined)
+      return cfgAtStart.bridge.enabled === true;
+    return process.env.CLAWDIS_BRIDGE_ENABLED !== "0";
+  })();
+
+  const bridgePort = (() => {
+    if (
+      typeof cfgAtStart.bridge?.port === "number" &&
+      cfgAtStart.bridge.port > 0
+    ) {
+      return cfgAtStart.bridge.port;
+    }
+    if (process.env.CLAWDIS_BRIDGE_PORT !== undefined) {
+      const parsed = Number.parseInt(process.env.CLAWDIS_BRIDGE_PORT, 10);
+      return Number.isFinite(parsed) && parsed > 0 ? parsed : 18790;
+    }
+    return 18790;
+  })();
+
+  const bridgeHost = (() => {
+    // Back-compat: allow an env var override when no bind policy is configured.
+    if (cfgAtStart.bridge?.bind === undefined) {
+      const env = process.env.CLAWDIS_BRIDGE_HOST?.trim();
+      if (env) return env;
+    }
+
+    const bind =
+      cfgAtStart.bridge?.bind ?? (wideAreaDiscoveryEnabled ? "tailnet" : "lan");
+    if (bind === "loopback") return "127.0.0.1";
+    if (bind === "lan") return "0.0.0.0";
+
+    const tailnetIPv4 = pickPrimaryTailnetIPv4();
+    const tailnetIPv6 = pickPrimaryTailnetIPv6();
+    if (bind === "tailnet") {
+      return tailnetIPv4 ?? tailnetIPv6 ?? null;
+    }
+    if (bind === "auto") {
+      return tailnetIPv4 ?? tailnetIPv6 ?? "0.0.0.0";
+    }
+    return "0.0.0.0";
+  })();
 
   const bridgeSubscribe = (nodeId: string, sessionKey: string) => {
     const normalizedNodeId = nodeId.trim();
@@ -1241,7 +1288,7 @@ export async function startGatewayServer(
 
   const machineDisplayName = await getMachineDisplayName();
 
-  if (bridgeEnabled && bridgePort > 0) {
+  if (bridgeEnabled && bridgePort > 0 && bridgeHost) {
     try {
       const started = await startNodeBridgeServer({
         host: bridgeHost,
@@ -1334,6 +1381,10 @@ export async function startGatewayServer(
     } catch (err) {
       logWarn(`gateway: bridge failed to start: ${String(err)}`);
     }
+  } else if (bridgeEnabled && bridgePort > 0 && !bridgeHost) {
+    logWarn(
+      "gateway: bridge bind policy requested tailnet IP, but no tailnet interface was found; refusing to start bridge",
+    );
   }
 
   try {
@@ -1345,8 +1396,11 @@ export async function startGatewayServer(
         : undefined;
 
     const tailnetDnsEnv = process.env.CLAWDIS_TAILNET_DNS?.trim();
-    const tailnetDns =
-      tailnetDnsEnv && tailnetDnsEnv.length > 0 ? tailnetDnsEnv : undefined;
+    const tailnetDns = wideAreaDiscoveryEnabled
+      ? WIDE_AREA_DISCOVERY_DOMAIN
+      : tailnetDnsEnv && tailnetDnsEnv.length > 0
+        ? tailnetDnsEnv
+        : undefined;
 
     const bonjour = await startGatewayBonjourAdvertiser({
       instanceName: formatBonjourInstanceName(machineDisplayName),
@@ -1360,6 +1414,30 @@ export async function startGatewayServer(
     logWarn(`gateway: bonjour advertising failed: ${String(err)}`);
   }
 
+  if (wideAreaDiscoveryEnabled && bridge?.port) {
+    const tailnetIPv4 = pickPrimaryTailnetIPv4();
+    if (!tailnetIPv4) {
+      logWarn(
+        "gateway: discovery.wideArea.enabled is true, but no Tailscale IPv4 address was found; skipping unicast DNS-SD zone update",
+      );
+    } else {
+      try {
+        const tailnetIPv6 = pickPrimaryTailnetIPv6();
+        const result = await writeWideAreaBridgeZone({
+          bridgePort: bridge.port,
+          displayName: formatBonjourInstanceName(machineDisplayName),
+          tailnetIPv4,
+          tailnetIPv6: tailnetIPv6 ?? undefined,
+        });
+        defaultRuntime.log(
+          `discovery: wide-area DNS-SD ${result.changed ? "updated" : "unchanged"} (${WIDE_AREA_DISCOVERY_DOMAIN} → ${result.zonePath})`,
+        );
+      } catch (err) {
+        logWarn(`gateway: wide-area discovery update failed: ${String(err)}`);
+      }
+    }
+  }
+
   broadcastHealthUpdate = (snap: HealthSummary) => {
     broadcast("health", snap, {
       stateVersion: { presence: presenceVersion, health: healthVersion },

src/infra/tailnet.test.ts

@@ -0,0 +1,33 @@
+import os from "node:os";
+
+import { describe, expect, it, vi } from "vitest";
+
+import { listTailnetAddresses } from "./tailnet.js";
+
+describe("tailnet address detection", () => {
+  it("detects tailscale IPv4 and IPv6 addresses", () => {
+    vi.spyOn(os, "networkInterfaces").mockReturnValue({
+      lo0: [
+        { address: "127.0.0.1", family: "IPv4", internal: true, netmask: "" },
+      ] as unknown as os.NetworkInterfaceInfo[],
+      utun9: [
+        {
+          address: "100.123.224.76",
+          family: "IPv4",
+          internal: false,
+          netmask: "",
+        },
+        {
+          address: "fd7a:115c:a1e0::8801:e04c",
+          family: "IPv6",
+          internal: false,
+          netmask: "",
+        },
+      ] as unknown as os.NetworkInterfaceInfo[],
+    });
+
+    const out = listTailnetAddresses();
+    expect(out.ipv4).toEqual(["100.123.224.76"]);
+    expect(out.ipv6).toEqual(["fd7a:115c:a1e0::8801:e04c"]);
+  });
+});

src/infra/tailnet.ts

@@ -0,0 +1,52 @@
+import os from "node:os";
+
+export type TailnetAddresses = {
+  ipv4: string[];
+  ipv6: string[];
+};
+
+function isTailnetIPv4(address: string): boolean {
+  const parts = address.split(".");
+  if (parts.length !== 4) return false;
+  const octets = parts.map((p) => Number.parseInt(p, 10));
+  if (octets.some((n) => !Number.isFinite(n) || n < 0 || n > 255)) return false;
+
+  // Tailscale IPv4 range: 100.64.0.0/10
+  // https://tailscale.com/kb/1015/100.x-addresses
+  const [a, b] = octets;
+  return a === 100 && b >= 64 && b <= 127;
+}
+
+function isTailnetIPv6(address: string): boolean {
+  // Tailscale IPv6 ULA prefix: fd7a:115c:a1e0::/48
+  // (stable across tailnets; nodes get per-device suffixes)
+  const normalized = address.trim().toLowerCase();
+  return normalized.startsWith("fd7a:115c:a1e0:");
+}
+
+export function listTailnetAddresses(): TailnetAddresses {
+  const ipv4: string[] = [];
+  const ipv6: string[] = [];
+
+  const ifaces = os.networkInterfaces();
+  for (const entries of Object.values(ifaces)) {
+    if (!entries) continue;
+    for (const e of entries) {
+      if (!e || e.internal) continue;
+      const address = e.address?.trim();
+      if (!address) continue;
+      if (isTailnetIPv4(address)) ipv4.push(address);
+      if (isTailnetIPv6(address)) ipv6.push(address);
+    }
+  }
+
+  return { ipv4: [...new Set(ipv4)], ipv6: [...new Set(ipv6)] };
+}
+
+export function pickPrimaryTailnetIPv4(): string | undefined {
+  return listTailnetAddresses().ipv4[0];
+}
+
+export function pickPrimaryTailnetIPv6(): string | undefined {
+  return listTailnetAddresses().ipv6[0];
+}

src/infra/widearea-dns.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  renderWideAreaBridgeZoneText,
+  WIDE_AREA_DISCOVERY_DOMAIN,
+} from "./widearea-dns.js";
+
+describe("wide-area DNS-SD zone rendering", () => {
+  it("renders a clawdis.internal zone with bridge PTR/SRV/TXT records", () => {
+    const txt = renderWideAreaBridgeZoneText({
+      serial: 2025121701,
+      bridgePort: 18790,
+      displayName: "Mac Studio (Clawdis)",
+      tailnetIPv4: "100.123.224.76",
+      tailnetIPv6: "fd7a:115c:a1e0::8801:e04c",
+      hostLabel: "studio-london",
+      instanceLabel: "studio-london",
+    });
+
+    expect(txt).toContain(`$ORIGIN ${WIDE_AREA_DISCOVERY_DOMAIN}`);
+    expect(txt).toContain(`studio-london IN A 100.123.224.76`);
+    expect(txt).toContain(`studio-london IN AAAA fd7a:115c:a1e0::8801:e04c`);
+    expect(txt).toContain(
+      `_clawdis-bridge._tcp IN PTR studio-london._clawdis-bridge._tcp`,
+    );
+    expect(txt).toContain(
+      `studio-london._clawdis-bridge._tcp IN SRV 0 0 18790 studio-london`,
+    );
+    expect(txt).toContain(`displayName=Mac Studio (Clawdis)`);
+  });
+});

src/infra/widearea-dns.ts

@@ -0,0 +1,163 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { CONFIG_DIR, ensureDir } from "../utils.js";
+
+export const WIDE_AREA_DISCOVERY_DOMAIN = "clawdis.internal.";
+export const WIDE_AREA_ZONE_FILENAME = "clawdis.internal.db";
+
+export function getWideAreaZonePath(): string {
+  return path.join(CONFIG_DIR, "dns", WIDE_AREA_ZONE_FILENAME);
+}
+
+function dnsLabel(raw: string, fallback: string): string {
+  const normalized = raw
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+/, "")
+    .replace(/-+$/, "");
+  const out = normalized.length > 0 ? normalized : fallback;
+  return out.length <= 63 ? out : out.slice(0, 63);
+}
+
+function txtQuote(value: string): string {
+  const escaped = value
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replaceAll("\n", "\\n");
+  return `"${escaped}"`;
+}
+
+function formatYyyyMmDd(date: Date): string {
+  const y = date.getUTCFullYear();
+  const m = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(date.getUTCDate()).padStart(2, "0");
+  return `${y}${m}${d}`;
+}
+
+function nextSerial(existingSerial: number | null, now: Date): number {
+  const today = formatYyyyMmDd(now);
+  const base = Number.parseInt(`${today}01`, 10);
+  if (!existingSerial || !Number.isFinite(existingSerial)) return base;
+  const existing = String(existingSerial);
+  if (existing.startsWith(today)) return existingSerial + 1;
+  return base;
+}
+
+function extractSerial(zoneText: string): number | null {
+  const match = zoneText.match(/^\s*@\s+IN\s+SOA\s+\S+\s+\S+\s+(\d+)\s+/m);
+  if (!match) return null;
+  const parsed = Number.parseInt(match[1], 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function extractContentHash(zoneText: string): string | null {
+  const match = zoneText.match(/^\s*;\s*clawdis-content-hash:\s*(\S+)\s*$/m);
+  return match?.[1] ?? null;
+}
+
+function computeContentHash(body: string): string {
+  // Cheap stable hash; avoids importing crypto (and keeps deterministic across runtimes).
+  let h = 2166136261;
+  for (let i = 0; i < body.length; i++) {
+    h ^= body.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+export type WideAreaBridgeZoneOpts = {
+  bridgePort: number;
+  displayName: string;
+  tailnetIPv4: string;
+  tailnetIPv6?: string;
+  instanceLabel?: string;
+  hostLabel?: string;
+};
+
+function renderZone(opts: WideAreaBridgeZoneOpts & { serial: number }): string {
+  const hostname = os.hostname().split(".")[0] ?? "clawdis";
+  const hostLabel = dnsLabel(opts.hostLabel ?? hostname, "clawdis");
+  const instanceLabel = dnsLabel(
+    opts.instanceLabel ?? `${hostname}-bridge`,
+    "clawdis-bridge",
+  );
+
+  const txt = [
+    `displayName=${opts.displayName.trim() || hostname}`,
+    `transport=bridge`,
+    `bridgePort=${opts.bridgePort}`,
+  ];
+
+  const records: string[] = [];
+
+  records.push(`$ORIGIN ${WIDE_AREA_DISCOVERY_DOMAIN}`);
+  records.push(`$TTL 60`);
+  const soaLine = `@ IN SOA ns1 hostmaster ${opts.serial} 7200 3600 1209600 60`;
+  records.push(soaLine);
+  records.push(`@ IN NS ns1`);
+  records.push(`ns1 IN A ${opts.tailnetIPv4}`);
+  records.push(`${hostLabel} IN A ${opts.tailnetIPv4}`);
+  if (opts.tailnetIPv6) {
+    records.push(`${hostLabel} IN AAAA ${opts.tailnetIPv6}`);
+  }
+
+  records.push(
+    `_clawdis-bridge._tcp IN PTR ${instanceLabel}._clawdis-bridge._tcp`,
+  );
+  records.push(
+    `${instanceLabel}._clawdis-bridge._tcp IN SRV 0 0 ${opts.bridgePort} ${hostLabel}`,
+  );
+  records.push(
+    `${instanceLabel}._clawdis-bridge._tcp IN TXT ${txt.map(txtQuote).join(" ")}`,
+  );
+
+  const contentBody = `${records.join("\n")}\n`;
+  const hashBody = `${records
+    .map((line) =>
+      line === soaLine
+        ? `@ IN SOA ns1 hostmaster SERIAL 7200 3600 1209600 60`
+        : line,
+    )
+    .join("\n")}\n`;
+  const contentHash = computeContentHash(hashBody);
+
+  return `; clawdis-content-hash: ${contentHash}\n${contentBody}`;
+}
+
+export function renderWideAreaBridgeZoneText(
+  opts: WideAreaBridgeZoneOpts & { serial: number },
+): string {
+  return renderZone(opts);
+}
+
+export async function writeWideAreaBridgeZone(
+  opts: WideAreaBridgeZoneOpts,
+): Promise<{ zonePath: string; changed: boolean }> {
+  const zonePath = getWideAreaZonePath();
+  await ensureDir(path.dirname(zonePath));
+
+  const existing = (() => {
+    try {
+      return fs.readFileSync(zonePath, "utf-8");
+    } catch {
+      return null;
+    }
+  })();
+
+  const nextNoSerial = renderWideAreaBridgeZoneText({ ...opts, serial: 0 });
+  const nextHash = extractContentHash(nextNoSerial);
+  const existingHash = existing ? extractContentHash(existing) : null;
+
+  if (existing && nextHash && existingHash === nextHash) {
+    return { zonePath, changed: false };
+  }
+
+  const existingSerial = existing ? extractSerial(existing) : null;
+  const serial = nextSerial(existingSerial, new Date());
+  const next = renderWideAreaBridgeZoneText({ ...opts, serial });
+  fs.writeFileSync(zonePath, next, "utf-8");
+  return { zonePath, changed: true };
+}