talon-agent 5.14.0 → 5.18.2

package/src/core/backup/upload.ts

@@ -12,6 +12,13 @@
  * `failed` with its reason and the run carries on — the next run retries
  * it. The manifest keeps the per-target state alongside the parts, so a
  * snapshot restored onto a new machine still knows where its copies are.
+ *
+ * Plaintext never leaves the box: before any target is contacted, every
+ * part's own bytes (not the manifest's say-so) must carry the encryption
+ * header. A snapshot taken without `backup.encryption` stays local, and
+ * each target records why. Parts marked `localOnly` (login sessions, by
+ * default) are never offered to a target at all; the manifest still lists
+ * them, so a restore from the remote copy knows what it is missing.
  */
 
 import { bus } from "../bus/index.js";
@@ -21,6 +28,7 @@ import {
   deleteBackupRemote,
   recordBackupRemote,
 } from "../../storage/backup/index.js";
+import { isEncryptedFile } from "./archive/crypt.js";
 import {
   partPath,
   reindexSnapshot,
@@ -28,7 +36,7 @@ import {
   writeManifest,
 } from "./store.js";
 import type { BackupTarget } from "./targets.js";
-import type { Manifest, RemoteState } from "./types.js";
+import type { Manifest, RemoteState, SnapshotPart } from "./types.js";
 
 function recordState(id: string, targetId: string, state: RemoteState): void {
   recordBackupRemote({
@@ -41,14 +49,20 @@ function recordState(id: string, targetId: string, state: RemoteState): void {
   });
 }
 
+/** The parts a remote target may receive: everything not marked local-only. */
+function remoteParts(manifest: Manifest): SnapshotPart[] {
+  return manifest.parts.filter((part) => part.localOnly !== true);
+}
+
 /** Push every part, then the manifest. Throws with the target's own words. */
 async function sendSnapshot(
   target: BackupTarget,
   manifest: Manifest,
   home: string,
 ): Promise<{ state: RemoteState; deduplicated: boolean }> {
-  let deduplicated = manifest.parts.length > 0;
-  for (const part of manifest.parts) {
+  const parts = remoteParts(manifest);
+  let deduplicated = parts.length > 0;
+  for (const part of parts) {
     const result = await target.upload(
       manifest.id,
       { ...part, path: partPath(manifest.id, part.name, home) },
@@ -63,6 +77,39 @@ async function sendSnapshot(
   };
 }
 
+/** The refusal every target records for an unencrypted snapshot. */
+export const PLAINTEXT_REFUSAL =
+  "remote backup targets require backup.encryption";
+
+/** The first part whose file is not encrypted (or is missing), if any. */
+async function firstPlaintextPart(
+  manifest: Manifest,
+  home: string,
+): Promise<string | undefined> {
+  for (const part of remoteParts(manifest)) {
+    const encrypted = await isEncryptedFile(
+      partPath(manifest.id, part.name, home),
+    ).catch(() => false);
+    if (!encrypted) return part.name;
+  }
+  return undefined;
+}
+
+/** Mark every target failed without contacting any of them. */
+function refuseAll(
+  manifest: Manifest,
+  targets: readonly BackupTarget[],
+  partName: string,
+): void {
+  const error = `${PLAINTEXT_REFUSAL} (part ${partName} is not encrypted; the snapshot stays local)`;
+  for (const target of targets) {
+    const state: RemoteState = { status: "failed", error };
+    manifest.remote[target.id] = state;
+    recordState(manifest.id, target.id, state);
+  }
+  logWarn("backup", `Not uploading ${manifest.id}: ${error}`);
+}
+
 /**
  * Upload one snapshot to every target. Returns the manifest with its
  * `remote` map filled in; it is rewritten on disk and reindexed so the
@@ -74,6 +121,22 @@ export async function uploadSnapshot(
   home: string = dirs.root,
 ): Promise<Manifest> {
   if (targets.length === 0) return manifest;
+  const plaintext = await firstPlaintextPart(manifest, home);
+  if (plaintext !== undefined) {
+    refuseAll(manifest, targets, plaintext);
+  } else {
+    await uploadToAll(manifest, targets, home);
+  }
+  await writeManifest(manifest, home);
+  reindexSnapshot(manifest);
+  return manifest;
+}
+
+async function uploadToAll(
+  manifest: Manifest,
+  targets: readonly BackupTarget[],
+  home: string,
+): Promise<void> {
   await Promise.all(
     targets.map(async (target) => {
       if (!target.ready) {
@@ -116,9 +179,6 @@ export async function uploadSnapshot(
       }
     }),
   );
-  await writeManifest(manifest, home);
-  reindexSnapshot(manifest);
-  return manifest;
 }
 
 /**

package/src/core/config/index.ts

@@ -175,6 +175,25 @@ const nativeConfigSchema = z
      * (~/.talon/keys/bridge-token) — the network never gets an open bridge.
      */
     token: z.string().optional(),
+    /**
+     * Start the bridge on a network-reachable `host` even though `token`
+     * looks weak (under ~128 bits by a length × alphabet estimate, e.g.
+     * `hunter2`). Off by default: a weak token on a non-loopback bind
+     * refuses to start, with instructions to generate a strong one. With
+     * this set the bridge starts and logs a security warning every time.
+     * Loopback binds only ever warn.
+     */
+    allowWeakToken: z.boolean().optional(),
+    /**
+     * Maximum lifetime of one authenticated event stream (`GET /events`),
+     * in ms. When set, each stream is closed after roughly this long
+     * (±10% jitter) and the client reconnects, presenting its token again.
+     * Unset (default) = streams live until the client leaves. The companion
+     * and talon-node both reconnect on their own, but with their own
+     * backoff, and a device command sent in that gap is dropped, so this is
+     * opt-in. Minimum 60000.
+     */
+    sseMaxLifetimeMs: z.number().int().min(60_000).optional(),
     /**
      * Origins allowed to call the bridge from a BROWSER. Native clients
      * (Electron main, Flutter, curl, talon-node) send no Origin header and
@@ -202,6 +221,29 @@ const nativeConfigSchema = z
       .string()
       .regex(/^https?:\/\/\S+$/, "native.publicUrl must be an http(s) URL")
       .optional(),
+    /**
+     * Accept the shared `token` from remote (non-loopback, or proxied)
+     * clients. Every device now gets its own credential when it pairs, and
+     * devices still holding the shared token trade it for one in-band on
+     * their next connect; the daemon log and `talon mesh` list the ones
+     * that have not. Once none remain, set this to false and rotate
+     * `token` — it then only works for same-machine clients (the desktop
+     * app and CLI, via the 0600 discovery file). Default true for this
+     * release; the default flips to false in a later one.
+     */
+    legacySharedToken: z.boolean().optional(),
+    /**
+     * Scopes a companion's per-device credential carries — at pairing and
+     * on the in-band upgrade. Default ["device", "client"]: the mesh plus
+     * the chat UI. Adding "operator" lets every paired phone change config,
+     * toggle plugins and read logs; prefer granting it to one device with
+     * `talon mesh scopes <device> device,client,operator`. Nodes always get
+     * ["device"].
+     */
+    companionScopes: z
+      .array(z.enum(["device", "client", "operator"]))
+      .min(1)
+      .optional(),
   })
   .strict();
 
@@ -407,6 +449,19 @@ const configSchema = z.object({
   apiHash: z.string().optional(),
   adminUserId: z.number().int().optional(),
   allowedUsers: z.array(z.number().int()).optional(), // Whitelist of user IDs allowed to DM the bot
+  /**
+   * Telegram groups the bot serves. When unset, groups are admitted by the
+   * admin's membership (legacy, warned at startup). Only the operator's own
+   * messages get the full tool set in any group.
+   */
+  allowedGroups: z.array(z.number().int()).optional(),
+  /**
+   * Further operator identities, beyond `adminUserId`: messages from these
+   * senders get the full tool set; everyone else is guest-scoped. Forms:
+   * Telegram user id ("123"), WhatsApp "wa_dm_<number>", "discord:<userId>",
+   * "teams:<userId>". Discord `adminUserIds` are included automatically.
+   */
+  operatorIds: z.array(z.string()).optional(),
   // Denylist of user IDs dropped in silence — no warning reply, no admin
   // notification. For spam and prompt-injection senders, where the warning
   // itself is the reward: it confirms a live bot is reading.
@@ -539,12 +594,16 @@ const configSchema = z.object({
    *
    *   - `workspaceInclude` — the workspace is mostly bulk that can be
    *     refetched; this is the subset that IS the agent.
+   *   - `includeSessions` — backend session transcripts (Claude Code
+   *     projects for the workspace, Codex/OpenCode/Kilo/Antigravity
+   *     stores for enabled backends) and data/traces, in their own part.
    *   - `extraPaths` — absolute or `~/…` paths outside ~/.talon worth
    *     carrying along (a Claude Code memory directory, say).
    *   - `checkpointBeforeUpdate` — pinned checkpoint before `/update`,
    *     so a bad update is one restore away from undone.
    *   - `notifyChatId` — where failures are reported; falls back to the
    *     admin chat.
+   *   - `encryption` / `loginSessions` — see docs/backup-security.md.
    */
   backup: z
     .object({
@@ -568,6 +627,17 @@ const configSchema = z.object({
         .max(1000)
         .default(DEFAULT_BACKUP_SETTINGS.keepRemote),
       includePalace: z.boolean().default(DEFAULT_BACKUP_SETTINGS.includePalace),
+      /**
+       * WhatsApp auth + the userbot's Telegram login. "local" (default)
+       * keeps them in local snapshots only; "remote" also uploads them
+       * (encrypted); "off" leaves them out entirely.
+       */
+      loginSessions: z
+        .enum(["off", "local", "remote"])
+        .default(DEFAULT_BACKUP_SETTINGS.loginSessions),
+      includeSessions: z
+        .boolean()
+        .default(DEFAULT_BACKUP_SETTINGS.includeSessions),
       workspaceInclude: z
         .array(z.string().min(1))
         .default([...DEFAULT_BACKUP_SETTINGS.workspaceInclude]),
@@ -578,10 +648,31 @@ const configSchema = z.object({
         .boolean()
         .default(DEFAULT_BACKUP_SETTINGS.checkpointBeforeUpdate),
       notifyChatId: z.string().optional(),
+      /**
+       * Encrypt every part (AES-256-GCM, scrypt-derived key). The
+       * passphrase comes from TALON_BACKUP_PASSPHRASE or this file —
+       * never inline, since config.json is itself inside the backup.
+       * Without a passphrase, remote targets refuse the upload.
+       */
+      encryption: z
+        .object({ passphraseFile: z.string().trim().min(1).optional() })
+        .strict()
+        .optional(),
     })
     .strict()
     .optional(),
   braveApiKey: z.string().optional(),
+  /**
+   * `fetch_url` refuses hosts that resolve to loopback, private (RFC 1918,
+   * CGNAT, ULA), link-local (incl. the 169.254.169.254 metadata endpoint)
+   * or reserved addresses, re-checking every redirect hop. Set
+   * `allowPrivateNetworks: true` only on a host where the agent should
+   * read local services (a home lab, a dev server).
+   */
+  fetchUrl: z
+    .object({ allowPrivateNetworks: z.boolean().default(false) })
+    .strict()
+    .optional(),
   /**
    * Codex-specific OpenAI API key. Prefer this, CODEX_API_KEY, or
    * TALON_CODEX_KEY when the Codex backend should use API-key billing
@@ -641,18 +732,24 @@ const configSchema = z.object({
   disabledToolTags: z.array(z.string()).optional(),
 
   /**
-   * Conversation-only tool surface for DMs from anyone who isn't an
-   * operator. The admin's Telegram DM and any `operatorChats` keep
-   * everything; other DMs (Telegram user ids, `wa_dm_*`) get reply/react/
+   * Conversation-only ("guest") tool surface for anyone who isn't an
+   * operator (`adminUserId`, `operatorIds`, `operatorChats`): reply/react/
    * history/stickers plus the `guestPlugins` servers — no shell, files,
-   * mail, devices, cron, memory, agents or cross-chat sends. Groups are
-   * unaffected. Off by default. See core/mcp-hub/guest-scope.ts.
+   * mail, devices, cron, memory, agents or cross-chat sends. Always applied
+   * to non-operator senders in groups; applied to non-operator DMs unless
+   * `enabled: false` (legacy opt-out). See core/mcp-hub/guest-scope.ts.
    */
   guestDmScope: z
     .object({
-      enabled: z.boolean().default(false),
+      enabled: z.boolean().default(true),
       operatorChats: z.array(z.string()).default([]),
       guestPlugins: z.array(z.string()).optional(),
+      /**
+       * Groups the operator is a member of give EVERY member the full
+       * surface (shell, files, mail, devices…). Off by default; only for
+       * groups whose members the operator trusts with the host.
+       */
+      operatorGroups: z.boolean().default(false),
     })
     .optional(),
 
@@ -1016,9 +1113,11 @@ export function loadConfig(): TalonConfig {
     ? parsed.frontend
     : [parsed.frontend];
   for (const fe of frontends) {
-    if (fe === "telegram" && !parsed.botToken) {
+    if (fe === "telegram" && (!parsed.botToken || !parsed.adminUserId)) {
       throw new Error(
-        `Telegram frontend requires "botToken" in ${CONFIG_FILE}. Run "talon setup" to configure.`,
+        parsed.botToken
+          ? TELEGRAM_ADMIN_REQUIRED
+          : `Telegram frontend requires "botToken" in ${CONFIG_FILE}. Run "talon setup" to configure.`,
       );
     }
     if (fe === "teams" && !parsed.teamsWebhookUrl) {
@@ -1045,6 +1144,39 @@ export function loadConfig(): TalonConfig {
   };
 }
 
+/**
+ * Why a Telegram frontend without `adminUserId` refuses to start: the admin
+ * is who may run operator commands and who the DM allowlist defaults to, so
+ * without one the bot would have no owner at all.
+ */
+export const TELEGRAM_ADMIN_REQUIRED =
+  `Telegram frontend requires "adminUserId" (your numeric Telegram user id) in ${CONFIG_FILE}. ` +
+  `It decides who may run admin commands and, unless "allowedUsers" lists more people, who may DM the bot. ` +
+  `Find your id by messaging @userinfobot, then run "talon setup" or add "adminUserId": <id> to the config.`;
+
+/**
+ * Only the `backup` block, validated — without writing a default config
+ * or checking frontend requirements. `talon backup restore` on a fresh
+ * host has no real config yet (it is inside the snapshot), and the
+ * default one would fail on its empty botToken before anything restored.
+ */
+export function loadBackupConfig(): TalonConfig["backup"] {
+  const fileConfig = loadConfigFile();
+  const result = configSchema.shape.backup.safeParse(fileConfig.backup);
+  if (!result.success) {
+    const issues = formatSchemaIssues(result.error).map(
+      (line) => `backup.${line}`,
+    );
+    throw new ConfigFileError(
+      `Invalid backup config in ${CONFIG_FILE}:\n` +
+        issues.map((line) => `  - ${line}`).join("\n"),
+      CONFIG_FILE,
+      issues,
+    );
+  }
+  return result.data;
+}
+
 /**
  * Rebuild the system prompt with plugin additions.
  * Called after plugins are loaded to inject their prompt contributions.

package/src/core/daemon/control.ts

@@ -15,6 +15,10 @@
 import { spawn } from "node:child_process";
 import { dirname, resolve } from "node:path";
 import { isBunRuntime } from "../../util/runtime.js";
+import {
+  gatewayAuthHeaders,
+  readGatewayToken,
+} from "../engine/gateway-auth.js";
 import {
   readPidRecord,
   writePidRecord,
@@ -157,6 +161,11 @@ async function requestShutdown(port: number): Promise<boolean> {
   try {
     const resp = await fetch(`http://127.0.0.1:${port}/shutdown`, {
       method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...gatewayAuthHeaders(readGatewayToken()),
+      },
+      body: "{}",
       signal: AbortSignal.timeout(2000),
     });
     if (!resp.ok) return false;

package/src/core/daemon/discovery.ts

@@ -17,6 +17,10 @@
  */
 
 import { readPidRecord, isProcessAlive } from "./pidfile.js";
+import {
+  gatewayAuthHeaders,
+  readGatewayToken,
+} from "../engine/gateway-auth.js";
 
 export type DaemonHealth = {
   app?: string;
@@ -78,7 +82,10 @@ export async function probeHealth(
   timeoutMs = 800,
 ): Promise<DaemonHealth | null> {
   try {
+    // The token is optional here: identity fields answer without it, the
+    // live counters `talon status` shows need it.
     const resp = await fetch(`http://127.0.0.1:${port}/health`, {
+      headers: gatewayAuthHeaders(readGatewayToken()),
       signal: AbortSignal.timeout(timeoutMs),
     });
     if (!resp.ok) return null;

package/src/core/engine/backend-router/headroom.ts

@@ -26,6 +26,7 @@
 import type { PlanUsage } from "../../agent-runtime/capabilities.js";
 import type { TalonConfig } from "../../config/index.js";
 import {
+  acquireBackendInstance,
   getPooledBackend,
   listAvailableBackends,
 } from "../backend-controller/index.js";
@@ -191,12 +192,35 @@ function unknownHeadroom(
   return { id, label, headroom: 1, source: "none", fetchedAt: now };
 }
 
-/** Ask a pooled backend for its plan windows. Rejects like the backend does. */
+/**
+ * Ask a backend for its plan windows. Rejects like the backend does.
+ *
+ * A pooled instance is used as-is. An idle backend (no chat bound to it) is
+ * booted transiently for the read and released again: its quota is just as
+ * real when nothing is routed to it, and reporting "not running" there made
+ * `/usage` hide exactly the headroom the router needs to pick a backend that
+ * is *not* currently in use. The read is the backend's own cached one, so at
+ * most one boot per cache window.
+ */
 async function readPlanUsage(id: string): Promise<PlanUsage | undefined> {
-  const backend = getPooledBackend(id);
-  const read = backend?.usage?.getPlanUsage;
-  if (!read || !backend?.usage) return undefined;
-  return read.call(backend.usage);
+  const pooled = getPooledBackend(id);
+  if (pooled?.usage?.getPlanUsage) {
+    return pooled.usage.getPlanUsage.call(pooled.usage);
+  }
+  if (pooled) return undefined; // pooled, but reports no plan windows
+  let acquired;
+  try {
+    acquired = await acquireBackendInstance(id);
+  } catch {
+    return undefined; // can't boot it (not configured, no auth) — stay quiet
+  }
+  try {
+    const read = acquired.backend.usage?.getPlanUsage;
+    if (!read || !acquired.backend.usage) return undefined;
+    return await read.call(acquired.backend.usage);
+  } finally {
+    await acquired.release().catch(() => {});
+  }
 }
 
 /**

package/src/core/engine/backend-router/usage.ts

@@ -34,9 +34,13 @@ export interface BackendUsageSnapshot {
 /** The reason a backend has no plan windows to show. */
 function noteFor(id: string, headroom: BackendHeadroom): string {
   const backend = getPooledBackend(id);
-  if (!backend) return "not running";
-  if (!backend.usage?.getPlanUsage) return "no plan limits on this backend";
+  // An idle backend is booted transiently for the plan read (see
+  // headroom.ts), so reaching here without windows means it really has none
+  // to report — not that it is "not running".
+  if (backend && !backend.usage?.getPlanUsage)
+    return "no plan limits on this backend";
   if (headroom.source === "ledger") return "tracked against a local budget";
+  if (headroom.source === "none") return "no usage information available";
   return "no usage information available";
 }
 

package/src/core/engine/gateway-actions/fetch-url/guard.ts

@@ -0,0 +1,201 @@
+/**
+ * SSRF guard for `fetch_url`.
+ *
+ * The URL comes from the model, and the model reads untrusted pages, so
+ * "fetch this" can be steered at anything the daemon's host can reach:
+ * the cloud metadata endpoint (169.254.169.254 hands out instance
+ * credentials), the loopback gateway, a router admin page on the LAN.
+ * So before every request — the first one and each redirect hop — the
+ * host is resolved and EVERY address it resolves to must be public.
+ * Redirects are followed by hand (never by fetch) so a public page
+ * cannot bounce the request into a private one.
+ *
+ * Residual risk, stated plainly: fetch resolves the name again after we
+ * checked it, so a DNS-rebinding server with a zero TTL can still race
+ * us. Pinning the checked address would need a custom connector, which
+ * Bun (one of the two runtimes) does not honour. The guard closes the
+ * direct, redirect and static-DNS paths; rebinding needs a hostile DNS
+ * server and a lucky race.
+ *
+ * Operators who run Talon next to services they WANT it to read (a home
+ * lab, a local dev server) can opt out with
+ * `fetchUrl.allowPrivateNetworks: true`.
+ */
+
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+/** Resolves a host name to every address it maps to. Injected in tests. */
+export type Resolver = (host: string) => Promise<string[]>;
+
+const defaultResolver: Resolver = async (host) =>
+  (await lookup(host, { all: true, verbatim: true })).map((r) => r.address);
+
+export class BlockedUrlError extends Error {}
+
+const MAX_REDIRECTS = 5;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+// ── Address classification ──────────────────────────────────────────────────
+
+/** Non-public IPv4 ranges: [network, prefix length]. */
+const BLOCKED_V4: ReadonlyArray<[string, number]> = [
+  ["0.0.0.0", 8], // "this network"
+  ["10.0.0.0", 8], // RFC 1918
+  ["100.64.0.0", 10], // CGNAT (also Tailscale)
+  ["127.0.0.0", 8], // loopback
+  ["169.254.0.0", 16], // link-local, cloud metadata
+  ["172.16.0.0", 12], // RFC 1918
+  ["192.0.0.0", 24], // IETF protocol assignments
+  ["192.0.2.0", 24], // TEST-NET-1
+  ["192.88.99.0", 24], // 6to4 relay anycast
+  ["192.168.0.0", 16], // RFC 1918
+  ["198.18.0.0", 15], // benchmarking
+  ["198.51.100.0", 24], // TEST-NET-2
+  ["203.0.113.0", 24], // TEST-NET-3
+  ["224.0.0.0", 4], // multicast
+  ["240.0.0.0", 4], // reserved + broadcast
+];
+
+/** Non-public IPv6 ranges (IPv4-mapped/compatible are unwrapped first). */
+const BLOCKED_V6: ReadonlyArray<[string, number]> = [
+  ["::", 128], // unspecified
+  ["::1", 128], // loopback
+  ["64:ff9b::", 96], // NAT64 — reaches whatever IPv4 it embeds
+  ["64:ff9b:1::", 48], // local-use NAT64
+  ["100::", 64], // discard
+  ["2001::", 32], // Teredo
+  ["2001:db8::", 32], // documentation
+  ["2002::", 16], // 6to4 — embeds an IPv4 address
+  ["fc00::", 7], // unique local
+  ["fe80::", 10], // link-local
+  ["fec0::", 10], // site-local (deprecated)
+  ["ff00::", 8], // multicast
+];
+
+function v4ToInt(ip: string): number {
+  return ip
+    .split(".")
+    .reduce((acc, octet) => ((acc << 8) | Number(octet)) >>> 0, 0);
+}
+
+function v6ToBigInt(ip: string): bigint {
+  let text = ip.toLowerCase().split("%")[0];
+  // A trailing dotted quad (::ffff:1.2.3.4) becomes two hextets.
+  const dotted = text.match(/(\d+\.\d+\.\d+\.\d+)$/);
+  if (dotted) {
+    const n = v4ToInt(dotted[1]);
+    text =
+      text.slice(0, -dotted[1].length) +
+      `${(n >>> 16).toString(16)}:${(n & 0xffff).toString(16)}`;
+  }
+  const [head, tail] = text.includes("::") ? text.split("::") : [text, null];
+  const headParts = head ? head.split(":") : [];
+  const tailParts = tail ? tail.split(":") : [];
+  const fill = tail === null ? 0 : 8 - headParts.length - tailParts.length;
+  const parts = [...headParts, ...Array(fill).fill("0"), ...tailParts];
+  return parts.reduce(
+    (acc, part) => (acc << 16n) | BigInt(parseInt(part || "0", 16)),
+    0n,
+  );
+}
+
+function inV4(ip: number, [net, bits]: [string, number]): boolean {
+  if (bits === 0) return true;
+  const mask = (~0 << (32 - bits)) >>> 0;
+  return (ip & mask) === (v4ToInt(net) & mask);
+}
+
+function inV6(ip: bigint, [net, bits]: [string, number]): boolean {
+  const shift = BigInt(128 - bits);
+  return ip >> shift === v6ToBigInt(net) >> shift;
+}
+
+/** True when `ip` is loopback, private, link-local, reserved or otherwise non-public. */
+export function isBlockedAddress(ip: string): boolean {
+  const family = isIP(ip.split("%")[0]);
+  if (family === 4) {
+    const n = v4ToInt(ip);
+    return BLOCKED_V4.some((range) => inV4(n, range));
+  }
+  if (family !== 6) return true; // not an address at all: refuse
+  const n = v6ToBigInt(ip);
+  // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d) addresses
+  // reach the embedded IPv4 host — judge that instead.
+  const high = n >> 32n;
+  if (high === 0xffffn || (high === 0n && n > 1n)) {
+    const v4 = Number(n & 0xffffffffn);
+    return BLOCKED_V4.some((range) => inV4(v4, range));
+  }
+  return BLOCKED_V6.some((range) => inV6(n, range));
+}
+
+// ── URL checks ──────────────────────────────────────────────────────────────
+
+/**
+ * Throw unless `url` is http(s) and its host resolves only to public
+ * addresses. A literal IP is judged directly; a name is resolved.
+ */
+export async function assertPublicUrl(
+  url: URL,
+  resolve: Resolver = defaultResolver,
+): Promise<void> {
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new BlockedUrlError("URL must use http or https protocol");
+  }
+  const host = url.hostname.replace(/^\[|\]$/g, "");
+  let addresses: string[];
+  if (isIP(host)) {
+    addresses = [host];
+  } else {
+    try {
+      addresses = await resolve(host);
+    } catch (err) {
+      throw new BlockedUrlError(
+        `Cannot resolve ${host}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+  if (addresses.length === 0) {
+    throw new BlockedUrlError(`Cannot resolve ${host}`);
+  }
+  const blocked = addresses.find(isBlockedAddress);
+  if (blocked) {
+    throw new BlockedUrlError(
+      `Refusing to fetch ${host}: it resolves to a private, loopback or link-local address (${blocked}). ` +
+        `Set fetchUrl.allowPrivateNetworks in config.json to allow local addresses.`,
+    );
+  }
+}
+
+export type GuardedFetchOptions = {
+  allowPrivateNetworks?: boolean;
+  resolve?: Resolver;
+  maxRedirects?: number;
+};
+
+/**
+ * `fetch` with the guard applied to the first request and to every
+ * redirect hop. Returns the final (non-redirect) response.
+ */
+export async function guardedFetch(
+  input: string,
+  init: RequestInit,
+  options: GuardedFetchOptions = {},
+): Promise<Response> {
+  const maxRedirects = options.maxRedirects ?? MAX_REDIRECTS;
+  let url = new URL(input);
+  for (let hop = 0; ; hop++) {
+    if (!options.allowPrivateNetworks) {
+      await assertPublicUrl(url, options.resolve);
+    }
+    const resp = await fetch(url, { ...init, redirect: "manual" });
+    const location = resp.headers.get("location");
+    if (!REDIRECT_STATUSES.has(resp.status) || !location) return resp;
+    if (hop >= maxRedirects) {
+      throw new BlockedUrlError(`Too many redirects (max ${maxRedirects})`);
+    }
+    await resp.body?.cancel().catch(() => {});
+    url = new URL(location, url);
+  }
+}