Security: SSRF denylist at the capture URL seams

[Seanathon]

SSRF denylist at the capture URL seams

Server-side capture could be steered at internal addresses — cloud metadata (169.254.169.254), localhost admin panels, RFC1918 — by any user-supplied URL. This is pre-existing and app-wide, reachable from every create path (POST /api/v1/items, POST /share, assign-driven capture, refetch) plus archival snapshots. (Tracked in the post-batch backlog ticket and the board-oss-capture-ssrf memory.)

Stacked on dev-capture-archive-compose (PR #2) because the guard also covers that branch's snapshot seam. Retarget to main once #2 merges. Diff here is the SSRF work only.

What it does

Adds capture/net-guard.ts → assertCapturableUrl(url), called at the two seams every server user-URL fetch routes through:

• dispatchCapture — covers url-screenshot (page.goto) + url-readable (captureLibrary → fetch/renderPageText), i.e. create / /share / assign / refetch. Buffer (manual-upload) sources have no URL and fall through.
• the snapshot capture() — archival, before Chrome even launches.

browser.ts / add.ts are intentionally out of scope: they're operator-run CLIs (operator supplies the URL) or downstream of the guarded adapters.

The guard:

• scheme allowlist (http/https only);
• range checks via net.BlockList (zero dep): 0/8, 10/8, 127/8, 169.254/16, 172.16/12, 192.168/16, 100.64/10, IPv6 ::1/::/fe80::/10/fc00::/7, and IPv4-mapped IPv6 (::ffff:127.0.0.1);
• numeric-encoded IPv4 (decimal 2130706433, hex 0x7f000001);
• localhost-family hostnames (localhost, *.local, *.internal, *.localhost, metadata.google.internal);
• DNS-resolve-and-recheck — the real evil.com → 10.0.0.5 vector (injectable for tests).

Fail-closed / fail-clean: a blocked URL throws BlockedUrlError → the item's existing capture-error path marks it error, no worker/server crash.

Tests

Table-driven on bypass forms (the discriminator, not just "127.0.0.1 blocked"): userinfo (example.com@127.0.0.1), [::1], [::ffff:127.0.0.1], 0.0.0.0, numeric encodings, non-http schemes, invalid URLs, and a DNS-resolves-to-private case — plus allowed cases (public literal, public hostname, and a resolution-failure that's allowed so the real fetch surfaces the error). Two seam tests prove dispatchCapture blocks before the adapter runs and that buffer sources pass through.

npm test → 508 pass / 0 fail. Zero new dependencies (node:net / node:dns).

Residuals (documented, not closed)

• DNS-rebinding TOCTOU — puppeteer/fetch re-resolve at connect time, so a host that resolves public for the guard but private for the real fetch isn't caught. Closing it needs connection-time IP pinning those clients don't expose.
• Octal-per-octet / mixed numeric IPv4 encodings (0177.0.0.1) that net.isIP rejects.
• Exotic IPv6 forms net.isIP rejects.

These are denylist gaps, not regressions — the guard is a large net improvement over no check on a self-hosted box.