Engineering notesView as Markdown ↗

Every outbound URL is checked before the server fetches it

In plain terms

When your business asks Biloh to send updates to another system, Biloh checks the address is a real public website before it sends anything, and checks again at every forward. It will not reach inside its own network or anyone else's.

When Biloh's server calls a URL that a business, a user or an agent supplied — a webhook endpoint, a branding asset — one guard decides first: https only, no credentials in the URL, and every address the host resolves to must be public. Redirects are followed by hand and every hop is checked again.

At a glance

Who it's for:
Engineers building on Biloh
Tools it uses:
update_branding_kit

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 answer 400 with the guard's reason for a refused URL. Delivery (lib/webhooks.ts) fetches through safeOutboundFetch, so an address that changes after it was saved is checked again at send time.
  • Branding assets. update_branding_kit fetches 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, PATCH on a mailbox) runs the same address check on the mail host through resolveCheckedHost, and the mail poller connects only to the checked address.

How is it locked?

  • tests/unit/security/security-w7-outbound-url-guard.test.ts covers 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.ts drives 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.ts proves the branding fetch re-checks a redirect.
  • tests/comms/bug-b286fc28-mail-host-guard.test.ts proves the pinning: when DNS answers a public address and then 127.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.

Under the hood

Tools this page uses, in the order used:

Source files this page is checked against:

  • lib/security/outbound-url-guard.ts
  • lib/webhooks.ts
  • app/api/webhooks/endpoints/route.ts
  • app/api/webhooks/endpoints/[id]/route.ts
  • lib/mcp/tools/marketing/branding-kit.ts
  • lib/security/pinned-transport.ts
  • lib/comms/register-account.ts
  • lib/comms/poll-imap.ts

Raw markdown: /docs-md/engineering-notes/every-outbound-url-is-checked-before-the-fetch

Last updated 2026-11-12