What does the guard promise?
A server that fetches a URL someone else typed can be pointed at places it should never reach: its own loopback interface, a private network range, or a cloud metadata address. Biloh has one home for that decision, lib/security/outbound-url-guard.ts, and every server-side fetch of a supplied URL goes through it.
checkOutboundUrl(url) allows a URL only when all of these hold:
- the scheme is
https:; - the URL carries no user name or password;
- the host is not a local name (
localhost,*.local,*.internal,*.localdomain,home.arpa, or a bare single-label name); - every address the host resolves to is public. Loopback, the RFC 1918 private ranges, link-local and the metadata range (
169.254.0.0/16), carrier-grade NAT, unspecified, multicast and reserved IPv4 are refused, and so are IPv6 loopback, unique-local, link-local, multicast, NAT64 and IPv4-mapped forms of any refused IPv4 address.
An address the guard cannot classify is refused, so an unexpected format never slips through.
How are redirects handled?
safeOutboundFetch(url, init) is the fetch wrapper. It sets redirect: "manual", follows at most three redirects itself, and runs checkOutboundUrl on every hop before the request is made. A public page that answers with a redirect to an internal address is stopped at that hop, and the internal address is never contacted. A refused hop throws OutboundUrlRefusedError with a plain reason.
Can a name change its answer between the check and the connection?
No. The check returns the address it approved, and the connection is made to that address. The default transport, pinnedFetch in lib/security/pinned-transport.ts, hands the socket a lookup that answers the approved address for any name, so DNS is never asked a second time. TLS still presents and verifies the URL's own hostname. A name with a zero TTL that answers a public address for the check and an internal one a moment later cannot reach the internal address.
Where is it applied?
- Webhook endpoints. Creating one (
POST /api/webhooks/endpoints) and changing its URL (PUT /api/webhooks/endpoints/[id], validated by a Zod schema) both answer400with the guard's reason for a refused URL. Delivery (lib/webhooks.ts) fetches throughsafeOutboundFetch, so an address that changes after it was saved is checked again at send time. - Branding assets.
update_branding_kitfetches a logo or image from a supplied URL through the same wrapper. - Mail servers. Registering or editing a mailbox (
register_comms_account,POST /api/comms/mailboxes,PATCHon a mailbox) runs the same address check on the mail host throughresolveCheckedHost, and the mail poller connects only to the checked address.
How is it locked?
tests/unit/security/security-w7-outbound-url-guard.test.tscovers every refused range, the IPv6 and IPv4-mapped forms, local names, credentials in the URL and redirect hops (25 cases).tests/route/security-w7-webhook-ssrf.test.tsdrives the real webhook create, update and delivery paths: an internal URL is refused on create and update, and delivery to a metadata address never calls fetch.tests/unit/security/security-w7-branding-asset-fetch.test.tsproves the branding fetch re-checks a redirect.tests/comms/bug-b286fc28-mail-host-guard.test.tsproves the pinning: when DNS answers a public address and then127.0.0.1, the connection goes to the public address that was checked. It also covers private mail hosts on register, edit and poll.
What does a builder need to know?
Any new server-side fetch of a URL that did not come from Biloh's own configuration should call safeOutboundFetch, never fetch directly, and any new connection to a supplied host name should go through resolveCheckedHost and connect to the address it returns. Both check the DNS answer and pin the connection to the address they approved.