fedipod 0.8.0

package/lib/remote.mjs

@@ -0,0 +1,303 @@
+// remote.mjs — authenticated I/O against the remote pod, via CSS
+// client-credentials + DPoP (vendor/idp-grant.cjs, extracted from
+// data-kitchen's "remember this IdP" machinery — plain Node, no Electron).
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as $rdf from 'rdflib';
+
+const LDP = $rdf.Namespace('http://www.w3.org/ns/ldp#');
+const DC = $rdf.Namespace('http://purl.org/dc/terms/');
+const POSIX = $rdf.Namespace('http://www.w3.org/ns/posix/stat#');
+const RDF = $rdf.Namespace('http://www.w3.org/1999/02/22-rdf-syntax-ns#');
+const ACL = $rdf.Namespace('http://www.w3.org/ns/auth/acl#');
+const FOAF = $rdf.Namespace('http://xmlns.com/foaf/0.1/');
+const AS = $rdf.Namespace('https://www.w3.org/ns/activitystreams#');
+
+const require = createRequire(import.meta.url);
+const vendorDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../vendor');
+const { mintCredential, discoverTokenEndpoint, createGrantSession, revokeCredentialViaAccount } =
+  require(path.join(vendorDir, 'idp-grant.cjs'));
+
+export { mintCredential, discoverTokenEndpoint, revokeCredentialViaAccount };
+
+// A pod that answers 429 or 503 is asking to be left alone; Retry-After says
+// for how long. Every request to this pod goes through one cooldown, so a
+// server under strain gets silence rather than each timer discovering the
+// refusal separately. Requests during the window fail fast — no socket is
+// opened — and the callers' existing retry paths take it from there.
+// The parser is shared with the outbound path; see lib/safefetch.mjs.
+import { retryAfterMs, readCapped } from './safefetch.mjs';
+
+// The inbox is public-Append, so the listing's size is in other people's
+// hands; reading it whole must still have a ceiling.
+const LISTING_MAX_BYTES = 10 * 1024 * 1024;
+
+// A pod's ability to BE a pod. Not data, and never ours to remove: delete one
+// of these and the pod does not degrade, it stops — and it cannot be repaired
+// by the tool that broke it, because that tool can no longer authenticate. A
+// pod was crippled exactly this way.
+//
+// Here rather than in any one script, because every DELETE this project sends
+// goes through RemotePod.delete — so this is the one place that cannot be
+// routed around. A DENY-list, not an allow-prefix: the next script will have a
+// different prefix and the same list of things it must never touch.
+const PROTECTED = [
+  [/\/profile(\/|$)/, 'the WebID document — nothing could authenticate as this pod again'],
+  [/\/settings(\/|$)/, "the pod's own settings"],
+  [/\/\.well-known(\/|$)/, 'discovery — the handle would stop resolving'],
+  [/\.acl$/, 'an access-control document — what it governs becomes unreachable'],
+  [/\.meta$/, 'a resource description the server itself reads'],
+  // The single-active-agent lock. It is on the pod precisely because the
+  // private half need not be — a lease only one machine can reach coordinates
+  // nothing — so it survives moving the state off, and nothing ever deletes it:
+  // release() writes an expiry, it does not remove the document. Two agents
+  // both believing they hold it is silent, destructive, duplicated inbox
+  // draining.
+  [/\/lease\.json$/, 'the lease — two agents would drain the same inbox'],
+];
+
+export function protectedFromDeletion(url) {
+  let p;
+  try { p = new URL(url).pathname; } catch { throw new Error(`refusing to DELETE an unparsable URL: ${url}`); }
+  if (p === '/' || p === '') throw new Error(`refusing to DELETE the pod root: ${url}`);
+  for (const [re, why] of PROTECTED) {
+    if (re.test(p)) {
+      throw new Error(`refusing to DELETE ${url} — ${why}. Deny-list: lib/remote.mjs.`);
+    }
+  }
+}
+
+export class RemotePod {
+  constructor(credential, { log = () => {}, home = null, session = null } = {}) {
+    // An injected session replaces the credential-backed one, and everything
+    // below it — the cooldown, the deny-list, the url map — is unchanged. That
+    // is how the agent runs inside a pod server: same class, no token to mint.
+    this.session = session || createGrantSession(credential, home ? {
+      backoffFile: path.join(home, 'backoff.json'),
+      tokenFile: path.join(home, 'token.json'),
+    } : {});
+    this.webId = credential.webId;
+    this.pausedUntil = 0;
+    this.probeCount = 0;
+    this.log = log;
+    // A fronted identity advertises ids on a shared domain but writes to the
+    // pod. run-agent installs the fronted→pod mapping here, so every request
+    // built from an advertised id lands on the pod — one choke point, and
+    // publisher/social/intake stay unaware. Unset → identity, byte-for-byte
+    // the unfronted behaviour.
+    this.toPod = null;
+  }
+
+  // Install the advertised→pod url map for a fronted identity (urls.toPod).
+  setUrlMap(fn) { this.toPod = typeof fn === 'function' ? fn : null; }
+
+  async warmup() { return this.session.warmup(); }
+
+  // What we have asked of this pod, for /status and for answering an operator.
+  stats() {
+    return {
+      ...this.session.stats(),
+      probes: this.probeCount,
+      pausedFor: Math.max(0, Math.round((this.pausedUntil - Date.now()) / 1000)),
+    };
+  }
+
+  // A deliberately CREDENTIAL-FREE request: it asks what a stranger would see,
+  // so it cannot go through session.fetch without answering a different
+  // question. It still belongs to this pod, though — it opens a socket to it
+  // and takes one of its workers — so it observes the same Retry-After window
+  // and is counted. Ten of these ride on every profile save, and none of them
+  // used to appear in /status, which made podRequests under-report by design.
+  async probe(url, init = {}) {
+    const left = this.pausedUntil - Date.now();
+    if (left > 0) {
+      throw new Error(`pod asked us to back off — ${Math.ceil(left / 1000)}s left of its Retry-After`);
+    }
+    this.probeCount++;
+    const res = await fetch(url, init);
+    if (res.status === 429 || res.status === 503) {
+      const ms = retryAfterMs(res) ?? 60_000;
+      this.pausedUntil = Date.now() + ms;
+      this.log(`pod returned ${res.status} to an unauthenticated probe — pausing for ${Math.round(ms / 1000)}s`);
+    }
+    return res;
+  }
+
+  async fetch(url, init) {
+    const left = this.pausedUntil - Date.now();
+    if (left > 0) {
+      throw new Error(`pod asked us to back off — ${Math.ceil(left / 1000)}s left of its Retry-After`);
+    }
+    // Fronted identity: an advertised id maps to its pod location here, so the
+    // request lands on the pod. A no-op for a pod-native id or an unfronted
+    // identity (toPod unset).
+    if (this.toPod) url = this.toPod(url);
+    const res = await this.session.fetch(url, init);
+    if (res.status === 429 || res.status === 503) {
+      const ms = retryAfterMs(res) ?? 60_000;   // no header: our own cooldown
+      this.pausedUntil = Date.now() + ms;
+      this.log(`pod returned ${res.status} — pausing all requests for ${Math.round(ms / 1000)}s`);
+    }
+    return res;
+  }
+
+  // Everything below goes through this.fetch, never session.fetch directly:
+  // that is the only place the Retry-After cooldown is both OBSERVED and ARMED.
+  // Writing straight to the session meant a pod could answer 429 to every PUT
+  // and DELETE we sent without any of them ever being recorded as a refusal,
+  // and meant a cooldown armed by a read did not stop a publish burst.
+  async put(url, body, contentType) {
+    const res = await this.fetch(url, {
+      method: 'PUT', headers: { 'content-type': contentType }, body,
+    });
+    if (res.status >= 400) throw new Error(`PUT ${url} → ${res.status}`);
+    return res;
+  }
+
+  async putJson(url, obj, contentType = 'application/activity+json') {
+    return this.put(url, JSON.stringify(obj), contentType);
+  }
+
+  // A read that FAILED is not a document that is ABSENT. Returning null for
+  // both let a 429 read as "no replies yet", and the caller then rewrote the
+  // collection from empty — erasing every reply already recorded. Only a real
+  // 404/410 is absence; anything else throws and the caller retries later.
+  async getJson(url) {
+    const res = await this.fetch(url, { headers: { accept: '*/*' } });
+    if (res.status === 404 || res.status === 410) return null;
+    if (res.status >= 400) throw new Error(`GET ${url} → ${res.status}`);
+    return res.json().catch(() => null);
+  }
+
+  async delete(url) {
+    protectedFromDeletion(url);
+    const res = await this.fetch(url, { method: 'DELETE' });
+    return res.status < 400 || res.status === 404;
+  }
+
+  // Child documents of an LDP container (URLs under it, excluding aux docs).
+  // Revalidated: the inbox is polled every two minutes and is usually
+  // unchanged, so ask conditionally and let the server answer 304.
+  async listContainer(url) {
+    this._listCache ||= new Map();
+    const known = this._listCache.get(url);
+    const res = await this.fetch(url, {
+      headers: { accept: 'text/turtle', ...(known?.etag ? { 'if-none-match': known.etag } : {}) },
+    });
+    if (res.status === 304 && known) return known.children;
+    if (res.status >= 400) return [];
+    // rdflib, not a regex: a container listing is RDF, and the gap between
+    // "any angle-bracketed thing in the document" and "what this container
+    // actually contains" is where quiet bugs live. claude/plans/no-regex-rdf.md
+    //
+    // CSS puts dc:modified and posix:size on every child of the same listing,
+    // so age and weight cost nothing extra — which is what lets the drain work
+    // oldest-first and lets a backlog be measured without reading any of it.
+    let body;
+    try {
+      body = await readCapped(res, LISTING_MAX_BYTES);
+    } catch (e) {
+      this.log(`listing at ${url}: ${e.message} — using the last known listing`);
+      return known?.children ?? [];
+    }
+    const g = $rdf.graph();
+    $rdf.parse(body, g, url, 'text/turtle');
+    const here = $rdf.sym(url);
+    const seen = new Set();
+    const list = [];
+    for (const child of g.each(here, LDP('contains'), null, here)) {
+      const u = child.value;
+      // `.receipt.json` is a verification receipt a gateway wrote beside an
+      // inbox item — read with the item, never enumerated as an item itself.
+      if (!u.startsWith(url) || u === url || /\.(acl|meta|receipt\.json)$/.test(u) || seen.has(u)) continue;
+      seen.add(u);
+      list.push({
+        url: u,
+        size: Number(g.any(child, POSIX('size'), null, here)?.value || 0),
+        modified: g.any(child, DC('modified'), null, here)?.value || null,
+      });
+    }
+    // Oldest first. An LDP listing is a set, so without this the drain works
+    // in whatever order the graph happened to parse — a mention from last week
+    // after one from today, and no way to make progress predictable.
+    list.sort((a, b) => String(a.modified || '').localeCompare(String(b.modified || '')));
+    this._listCache.set(url, { etag: res.headers.get('etag'), children: list });
+    return list;
+  }
+
+  // WAC doc granting the public `publicModes` on target, owner full control.
+  // An empty publicModes list yields an owner-only document.
+  //
+  // Built and serialised by rdflib, like every other document this project
+  // writes — see claude/plans/no-regex-rdf.md. This was the last site still
+  // assembling Turtle from template literals, and it is the highest-consequence
+  // RDF here: an ACL that comes out malformed, or naming the wrong subject,
+  // either locks the owner out or leaves the private trees world-readable.
+  // $rdf.sym() also throws on an illegal IRI, so a pod URL with something odd
+  // in it fails here rather than silently producing a document that means
+  // something else.
+  aclDoc(targetUrl, publicModes, { appendAgents = [] } = {}) {
+    const url = targetUrl + '.acl';
+    const doc = $rdf.sym(url);
+    const target = $rdf.sym(targetUrl);
+    const g = $rdf.graph();
+    const authorize = (subject, agentPred, agent, modes) => {
+      g.add(subject, RDF('type'), ACL('Authorization'), doc);
+      g.add(subject, agentPred, agent, doc);
+      g.add(subject, ACL('accessTo'), target, doc);
+      g.add(subject, ACL('default'), target, doc);
+      for (const m of modes) g.add(subject, ACL('mode'), ACL(m), doc);
+    };
+    if (publicModes.length) {
+      authorize($rdf.sym(url + '#public'), ACL('agentClass'), FOAF('Agent'), publicModes);
+    }
+    // Named agents granted Append but not public: this is how the inbox is
+    // locked to a gateway — public loses Append, the gateway's WebID keeps it.
+    appendAgents.forEach((webId, i) =>
+      authorize($rdf.sym(url + `#gw${i}`), ACL('agent'), $rdf.sym(webId), ['Append']));
+    authorize($rdf.sym(url + '#owner'), ACL('agent'), $rdf.sym(this.webId),
+      ['Read', 'Write', 'Control']);
+    return $rdf.serialize(doc, g, url, 'text/turtle');
+  }
+
+  async setAcl(targetUrl, publicModes, opts = {}) {
+    return this.put(targetUrl + '.acl', this.aclDoc(targetUrl, publicModes, opts), 'text/turtle');
+  }
+
+  // The WebID profile advertises the actor as an account:
+  //   <webId> foaf:account <actor> .
+  //   <actor> a foaf:OnlineAccount, as:Person|as:Group ; foaf:accountName "@handle@host" .
+  // Read–check–write through rdflib. Returns false when the profile already
+  // says all of it. The parsed graph must mention the WebID before anything is
+  // written back — an empty or foreign body must never become the new profile.
+  async linkAccountInProfile({ actorUrl, accountName, kind = 'person' }) {
+    const docUrl = this.webId.split('#')[0];
+    const res = await this.fetch(docUrl, { headers: { accept: 'text/turtle' } });
+    if (res.status >= 400) throw new Error(`GET ${docUrl} → ${res.status}`);
+    const g = $rdf.graph();
+    $rdf.parse(await res.text(), g, docUrl, 'text/turtle');
+    const doc = $rdf.sym(docUrl);
+    const me = $rdf.sym(this.webId);
+    if (!g.statementsMatching(me, null, null, doc).length) {
+      throw new Error(`profile at ${docUrl} does not mention ${this.webId} — not rewriting it`);
+    }
+    const actor = $rdf.sym(actorUrl);
+    const wanted = [
+      [me, FOAF('account'), actor],
+      [actor, RDF('type'), FOAF('OnlineAccount')],
+      [actor, RDF('type'), kind === 'group' ? AS('Group') : AS('Person')],
+      [actor, FOAF('accountName'), $rdf.literal(accountName)],
+    ];
+    const missing = wanted.filter(([s, p, o]) => !g.holds(s, p, o, doc));
+    // A handle change leaves the old accountName behind; ours is replaced.
+    const stale = g.statementsMatching(actor, FOAF('accountName'), null, doc)
+      .filter(st => st.object.value !== accountName);
+    if (!missing.length && !stale.length) return false;
+    for (const st of stale) g.remove(st);
+    for (const [s, p, o] of missing) g.add(s, p, o, doc);
+    await this.put(docUrl, $rdf.serialize(doc, g, docUrl, 'text/turtle'), 'text/turtle');
+    return true;
+  }
+}

package/lib/safefetch.mjs

@@ -0,0 +1,235 @@
+// safefetch.mjs — SSRF guard for every outbound request. The pod inbox is
+// public-Append, so ANY fediverse user can hand this agent URLs that it will
+// dereference (verify-by-deref) or deliver to. Without a filter those URLs
+// can name the machine's own services, the LAN, or cloud metadata.
+//
+// Policy: http/https only; the host must resolve exclusively to public
+// addresses; redirects are followed by hand so every hop is re-checked;
+// responses are size-capped. AP_ALLOW_PRIVATE_TARGETS=1 disables the address
+// check for local federation testing.
+
+import { USER_AGENT } from './ua.mjs';
+import dns from 'node:dns/promises';
+import net from 'node:net';
+
+const MAX_REDIRECTS = 3;
+const MAX_BYTES = 5 * 1024 * 1024;
+
+// ONE default, read from ONE place. It was 15s in publisher, 20s in intake and
+// other values again in the vendor grant, so "the timeout" meant four things
+// and AP_HTTP_TIMEOUT_MS moved some of them and not others.
+export const HTTP_TIMEOUT_MS = Number(process.env.AP_HTTP_TIMEOUT_MS) || 20_000;
+
+// Said once, loudly: with the flag on there is NO address check and NO pinning.
+if (process.env.AP_ALLOW_PRIVATE_TARGETS === '1') {
+  console.warn('safefetch: AP_ALLOW_PRIVATE_TARGETS=1 — SSRF protection is OFF. '
+    + 'Local federation testing only; never set this on a networked deployment.');
+}
+
+// A server answering 429 or 503 is asking to be left alone, and Retry-After
+// says for how long. Here rather than in remote.mjs because BOTH directions
+// need it: the pod has honoured it since the incident, and the outbound path
+// — the one that talks to other people's servers — did not.
+const COOLDOWN_DEFAULT_MS = 60_000;
+const COOLDOWN_MAX_MS = 30 * 60_000;
+
+// null when the server sent NO Retry-After. The caller decides what absence
+// means: the pod path falls back to its own 60s cooldown, and the delivery
+// queue keeps its exponential ladder — which is why this cannot just return a
+// default. Doing so collapsed the ladder to a flat 60s for every 503 without
+// the header, which is most of them.
+export function retryAfterMs(res, max = COOLDOWN_MAX_MS) {
+  const raw = res?.headers?.get?.('retry-after');
+  if (!raw) return null;
+  const secs = Number(raw);
+  if (Number.isFinite(secs)) return Math.min(Math.max(secs, 1) * 1000, max);
+  const when = Date.parse(raw);                       // HTTP-date form
+  if (Number.isFinite(when)) return Math.min(Math.max(when - Date.now(), 1000), max);
+  return null;
+}
+
+function isPrivateV4(ip) {
+  const [a, b] = ip.split('.').map(Number);
+  return a === 0 || a === 10 || a === 127
+    || (a === 169 && b === 254)                 // link-local + cloud metadata
+    || (a === 172 && b >= 16 && b <= 31)
+    || (a === 192 && b === 168)
+    || (a === 100 && b >= 64 && b <= 127)       // CGNAT
+    || (a === 192 && b === 0)                   // 192.0.0.0/24 special-use
+    || a >= 224;                                // multicast + reserved
+}
+
+function isPrivateV6(ip) {
+  const a = ip.toLowerCase();
+  if (a === '::' || a === '::1') return true;
+  if (/^fe[89ab]/.test(a)) return true;              // fe80::/10 link-local, all four nibbles
+  if (a.startsWith('fc') || a.startsWith('fd')) return true;                           // ULA
+  if (a.startsWith('fec0')) return true;             // deprecated site-local, still routed by some
+  if (a.startsWith('ff')) return true;               // multicast
+  // A v4-mapped address, in EITHER spelling. The dotted form was the only one
+  // matched, and it is the one that never arrives: the WHATWG URL parser
+  // normalises an IPv6 literal to compressed hex, so `[::ffff:127.0.0.1]` is
+  // handed to us as `::ffff:7f00:1` and walked straight past this filter — and
+  // with it every one of 127/8, 10/8, 172.16/12, 192.168/16 and 169.254/16.
+  // Canonicalise to the quad first, then classify once.
+  const dotted = a.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (dotted) return isPrivateV4(dotted[1]);
+  const hex = a.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (hex) {
+    const [hi, lo] = [parseInt(hex[1], 16), parseInt(hex[2], 16)];
+    return isPrivateV4(`${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`);
+  }
+  return false;
+}
+
+export function isPrivateAddress(ip) {
+  return net.isIPv4(ip) ? isPrivateV4(ip) : net.isIPv6(ip) ? isPrivateV6(ip) : true;
+}
+
+// Is this host the machine we are running on? Not a security check — the
+// operator typed this URL — but the one distinction that decides whether
+// plaintext is harmless. Loopback traffic never reaches a network interface,
+// so `http://localhost:8000/` crosses nothing and TLS would add nothing to it.
+// A LAN address is a different matter entirely: 192.168.1.50 is a real wire,
+// shared with every other device on it.
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+export function isLoopbackHost(host) {
+  const h = String(host || '').toLowerCase().replace(/^\[|\]$/g, '');
+  if (LOOPBACK_HOSTS.has(h) || h === '[::1]') return true;
+  if (h.endsWith('.localhost')) return true;           // RFC 6761 reserves the whole label
+  return /^127\./.test(h);
+}
+
+/**
+ * Refuse a pod, issuer or private-root address that would carry secrets in
+ * clear over a real network. Returns a reason string, or null when acceptable.
+ *
+ * The pod URL is where the account password is exchanged for a credential and
+ * where that credential is used from then on; the issuer is where the password
+ * itself is posted. Nothing checked the scheme, so a typed `http://` sent both
+ * in plaintext with no warning. Loopback is exempt because it cannot leak, and
+ * because a pod on this machine is a documented, ordinary way to run this.
+ */
+export function insecureUrlReason(url, what = 'address') {
+  if (!url) return null;
+  let u;
+  try { u = new URL(url); } catch { return `"${url}" is not a ${what}`; }
+  if (u.protocol === 'https:') return null;
+  if (u.protocol !== 'http:') return `the ${what} must be http(s), not ${u.protocol}`;
+  if (isLoopbackHost(u.hostname)) return null;         // never crosses a wire
+  return `refusing an unencrypted ${what}: ${u.origin} would send your password, `
+    + 'your credential and everything after it in clear over the network. '
+    + 'Use https:// — or a loopback address if the pod is on this machine.';
+}
+
+// Throws when the URL must not be requested; otherwise returns the
+// validated address to pin the connection to ({address, family}), or null
+// when the URL already names a literal IP.
+export async function assertPublicUrl(url) {
+  if (process.env.AP_ALLOW_PRIVATE_TARGETS === '1') return null;
+  let u;
+  try { u = new URL(url); } catch { throw new Error(`unparsable URL: ${url}`); }
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') throw new Error(`blocked scheme: ${u.protocol}`);
+  const host = u.hostname.replace(/^\[|\]$/g, '');
+  if (net.isIP(host)) {
+    if (isPrivateAddress(host)) throw new Error(`blocked private address: ${host}`);
+    return null;
+  }
+  let addrs;
+  try { addrs = await dns.lookup(host, { all: true }); }
+  catch (e) { throw new Error(`DNS lookup failed for ${host}: ${e.message}`); }
+  if (!addrs.length) throw new Error(`no addresses for ${host}`);
+  // ALL addresses must be public — a name resolving to both public and
+  // private answers is a rebinding attempt.
+  for (const a of addrs) {
+    if (isPrivateAddress(a.address)) throw new Error(`blocked private address: ${host} → ${a.address}`);
+  }
+  return { address: addrs[0].address, family: addrs[0].family };
+}
+
+// Validating a hostname and then handing that NAME to fetch leaves a
+// rebinding window: the resolver can answer publicly for our check and
+// privately for the connection. Pinning the dispatcher's lookup to the
+// address we validated closes it, while TLS/SNI still see the real
+// hostname (so certificates verify normally).
+// Declared in package.json since 2026-08-03. It had been arriving as a
+// four-level transitive dependency of rdflib's, which meant the rebinding
+// protection below rested on a package nothing had asked for — and the catch
+// swallowed its absence, so losing it would have been silent. Say so instead:
+// the address check still runs, but the connection is no longer pinned to the
+// address that passed it.
+let Agent = null;
+try { ({ Agent } = await import('undici')); }
+catch {
+  console.warn('safefetch: undici is not available — addresses are still checked, '
+    + 'but connections are NOT pinned to the checked address, so a name that '
+    + 'resolves differently on the second lookup is not caught');
+}
+
+function pinnedDispatcher(address, family) {
+  if (!Agent) return undefined;
+  // The connect layer calls lookup either callback-style (err, address,
+  // family) or, with options.all, expecting an array of records.
+  const lookup = (_host, opts, cb) => (opts && opts.all
+    ? cb(null, [{ address, family }])
+    : cb(null, address, family));
+  return new Agent({ connect: { lookup } });
+}
+
+/** Resolve + validate, returning a dispatcher pinned to the checked address. */
+export async function pinnedFor(url) {
+  if (process.env.AP_ALLOW_PRIVATE_TARGETS === '1') return undefined;
+  const addr = await assertPublicUrl(url);
+  return addr ? pinnedDispatcher(addr.address, addr.family) : undefined;
+}
+
+/** Read a response body with a hard byte budget (streams are unbounded). */
+export async function readCapped(res, max = MAX_BYTES) {
+  const len = Number(res.headers?.get?.('content-length') || 0);
+  if (len > max) throw new Error(`response too large (${len} bytes)`);
+  if (!res.body) return await res.text();
+  const reader = res.body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.length;
+    if (total > max) { await reader.cancel(); throw new Error(`response exceeded ${max} bytes`); }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks.map(Buffer.from)).toString('utf8');
+}
+
+/**
+ * fetch() with the address policy applied to the initial URL and to every
+ * redirect hop, the connection pinned to the validated address, and a
+ * response size cap.
+ * @param {string} url
+ * @param {object} [init]         passed through to fetch
+ * @param {function} [fetchImpl]  the actual fetch (e.g. a signing fetch);
+ *                                receives (url, init) with the dispatcher set
+ */
+export async function safeFetch(url, init = {}, fetchImpl = fetch) {
+  let current = url;
+  const withUa = { ...init, headers: { 'user-agent': USER_AGENT, ...(init.headers || {}) } };
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const dispatcher = await pinnedFor(current);
+    const res = await fetchImpl(current, {
+      ...withUa,
+      signal: init.signal || AbortSignal.timeout(HTTP_TIMEOUT_MS),
+      ...(dispatcher ? { dispatcher } : {}),
+      redirect: 'manual',
+    });
+    if (res.status >= 300 && res.status < 400) {
+      const loc = res.headers.get('location');
+      if (!loc) return res;
+      current = new URL(loc, current).href;
+      continue;
+    }
+    const len = Number(res.headers?.get?.('content-length') || 0);
+    if (len > MAX_BYTES) throw new Error(`response too large (${len} bytes) from ${current}`);
+    return res;
+  }
+  throw new Error(`too many redirects from ${url}`);
+}