# Every outbound URL is checked before the server fetches it

> 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.

URL: https://biloh.com.au/docs/engineering-notes/every-outbound-url-is-checked-before-the-fetch
Category: Engineering notes | Audience: builder | Updated: 2026-11-12

**At a glance**

- **Who it's for:** Engineers building on Biloh
- **Tools it uses:** [`update_branding_kit`](https://biloh.com.au/connect#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.
