fix(security): block SSRF to private/internal/metadata addresses (closes #41)

[syswave-dev]

Closes #41.

Problem

The URL-fetch endpoints (GET /api, MCP read_url) performed server-side fetches of any user-supplied URL with no address validation, allowing SSRF against internal and cloud-metadata endpoints (e.g. http://100.100.100.200/latest/user-data, http://169.254.169.254/).

Fix

A new guard (lib/ssrf.js) that, by default, denies requests whose resolved address falls in a private, loopback, link-local, CGNAT, or cloud-metadata range:

• Resolves the host and checks every returned address (IPv4 + IPv6), failing closed on resolution errors, empty results, and non-http(s) schemes.
• Blocks the same private/metadata ranges reached via IPv6 transition addressing (NAT64 64:ff9b::/96, 6to4 2002::/16, IPv4-compatible/-mapped) by matching the embedded IPv4, so legitimate public destinations still resolve on NAT64 hosts.
• Re-validates every redirect hop (redirect: 'manual'), so a public URL cannot 302 into an internal one.
• Wired into all three user-controlled fetch paths: the main web fetch (also covers the Reddit/HN web fallback), Reddit short-link redirect resolution, and the Playwright sidecar dispatch (validated Node-side before the browser resolves DNS itself).
• Blocked requests return HTTP 403 at /api (and an isError result at MCP read_url), checked before the cache lookup so a previously-cached internal response cannot be served.

Opt-out for self-hosters

Default-deny. Self-hosters who intentionally fetch internal hosts can allowlist specific CIDRs and/or hostnames via PULLMD_ALLOWED_HOSTS (e.g. 10.0.5.0/24,wiki.internal). There is no global kill-switch.

Known residuals (documented)

• DNS rebinding: the guard resolves-and-checks but does not pin the socket to the checked IP; full mitigation (a connection-pinning dispatcher) is a possible follow-up.
• Playwright internal navigation: once an allowed page loads, client-side redirects/fetches inside the headless browser are not Node-guarded; container egress rules are the second layer.
• Outbound HTTP proxy: if egress is routed through a proxy, the proxy's egress rules are authoritative (the guard validates the intended target's resolved IPs but cannot pin past the proxy).

Testing

• New unit tests for the guard (IP ranges incl. NAT64/6to4, redirect-hop re-validation, allowlist parsing, scheme rejection).
• New endpoint tests: blocked URLs return 403 at /api and isError at MCP read_url.
• Full suite: 794/794 passing. Verified end-to-end against a running server: the reported payload returns 403; normal public URLs are unaffected.

Version bumped to 3.3.0 with a CHANGELOG Security entry and PULLMD_ALLOWED_HOSTS documented in .env.example and the help page.

🤖 Generated with Claude Code

https://claude.ai/code/session_013pFhk7BB4SZ8dNBLQbsiQL