nish/net/outbound

The policy for a program that fetches URLs it did not choose: a webhook sender, a link previewer, an importer that takes a URL from a form. Without one, such a program is a proxy into its own network for whoever supplies the URL (server-side request forgery): a URL naming 127.0.0.1, 169.254.169.254 or a name that resolves to either reaches services that trust the program's address.

import {
  OutboundPolicy,
  outboundAddressAllowed,
  outboundAddressPublic,
  outboundAddressText,
  outboundFilter,
  outboundHostAllowed,
} from "nish/net/outbound";
import { OutboundPolicy } from "nish/net/outbound";
import { HttpOptions } from "nish/net/fetch";

const options = new HttpOptions();
options.outbound = new OutboundPolicy();
The check is on the address, after the lookup

A name is never judged by its text: nish/net/fetch resolves it, drops every address outboundAddressAllowed refuses, and connects only to the bytes it kept, with no second lookup, so a name whose answer changes between a check and a connect (DNS rebinding) cannot move the connection. Every redirect hop is dialled the same way, so a public URL that redirects inward is refused at the hop.

Public

Public is the IANA special-purpose registries read strictly (RFC 6890, and the registries at iana.org/assignments/iana-ipv4-special-registry and iana-ipv6-special-registry). An IPv4 address is public unless it is in 0/8, 10/8, 100.64/10, 127/8, 169.254/16, 172.16/12, 192.0.0/24, 192.0.2/24, 192.88.99/24, 192.168/16, 198.18/15, 198.51.100/24, 203.0.113/24, 224/4 or 240/4 (the broadcast address included), or is 168.63.129.16, a cloud host's metadata and DNS service. An IPv6 address is public only in 2000::/3, and then not in 2001::/23 (Teredo included), 2001:db8::/32 or 3fff::/20; 2002::/16 (6to4) and 64:ff9b::/96 (NAT64) are judged by the IPv4 address they carry, as is ::ffff:0:0/96, the form every IPv4 address takes in nish:net. Everything else, ::1, fc00::/7 and fe80::/10 among it, is refused.

permit lets a trusted prefix through anyway (an internal API the program is meant to reach), and allowHost narrows the names a URL may carry. The policy also caps a fetch's redirects, total time and body, and the client uses the stricter of these and its own options.

Private helpers share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e), which is why each one carries the module's name.

Written from RFC 6890, RFC 4291, RFC 6052, RFC 3056, RFC 4380 and the IANA special-purpose address registries, not ported from another implementation.

Functions

outboundAddressAllowed

Whether policy lets a connection go to the sixteen address bytes at addr[off]: a prefix it permits, or else a public address.

const outboundAddressAllowed: (
  policy: OutboundPolicy,
  addr: u8[],
  off: i32,
) => boolean
policyOutboundPolicyrequired

The policy whose permits are checked first.

addru8[]required

The array holding the address; an IPv4 one in its ::ffff: form, as nish writes it.

offi32required

Where the address's sixteen bytes start in addr.

returnsboolean

True when a connection may go there. An IPv4 address carried by NAT64 or 6to4 is judged as that address, by a permit too.

outboundAddressPublic

Whether the sixteen address bytes at addr[off] are public, as the module comment defines it. Panics when sixteen bytes do not fit there.

const outboundAddressPublic: (
  addr: u8[],
  off: i32,
) => boolean
addru8[]required

The array holding the address; an IPv4 one in its ::ffff: form, as nish writes it.

offi32required

Where the address's sixteen bytes start in addr.

returnsboolean

True for a public address. An IPv4 one carried by NAT64 or 6to4 is judged as that IPv4 address.

outboundAddressText

The sixteen address bytes at addr[off] as text, for an error to name.

const outboundAddressText: (addr: u8[], off: i32) => string
addru8[]required

The array holding the address.

offi32required

Where the address's sixteen bytes start in addr.

returnsstring

Dotted decimal for an IPv4 address in its ::ffff: form, otherwise all eight lower-case hex groups with no :: shortening.

outboundFilter

Keeps the addresses of count DNS_ADDRESS_BYTES records in addresses that policy allows, moved to the front in their order, and answers how many. Refused records are left behind them, so the caller can name one.

const outboundFilter: (
  policy: OutboundPolicy,
  addresses: u8[],
  count: i32,
) => i32
policyOutboundPolicyrequired

The policy each address is checked against, as outboundAddressAllowed checks it.

addressesu8[]required

The records, each sixteen address bytes and a two-byte port, reordered in place.

counti32required

How many records addresses holds from its start; one that does not fit panics.

returnsi32

How many records were kept, now addresses' first ones; 0 when every one was refused.

outboundHostAllowed

Whether policy lets a URL name host, as the URL parser gives it (lower-cased, an IPv6 literal without its brackets). Any host when the policy names none.

const outboundHostAllowed: (
  policy: OutboundPolicy,
  host: string,
) => boolean
policyOutboundPolicyrequired

The policy whose allowHost names are checked.

hoststringrequired

The URL's host; its case and one trailing dot do not matter.

returnsboolean

True when the host is one the policy names, or under a .-led name it allows, or the policy names none.

Classes

OutboundPolicy

What a client that fetches untrusted URLs may reach. A new policy refuses every address that is not public, allows any host name, and caps a fetch at 5 redirects, 30 seconds and an 8 MiB body.

class OutboundPolicy
Member
new OutboundPolicy() Makes the default policy the class describes: public addresses only, any host name, and the default limits.
maxBodyBytes: i64 A fetch's body is cut off past this, or past the client's own cap if lower.
maxRedirects: i32 At most this many redirects, or the client's own limit if lower.
permitted: u8[] OUTBOUND_PERMIT_BYTES per prefix permit let through.
totalTimeoutMs: i32 A whole fetch ends after this, or the client's own budget if lower; 0 or less for the client's alone.
allowHost(name: string): void Adds name to the hosts a URL may name; once any is added, a URL (or a redirect) naming another is refused before it is looked up. Case and one trailing dot do not matter. A leading dot (.example.com) allows the name and every name under it. An address literal matches only itself, as the URL writes it (::1 or [::1], 127.0.0.1), never as a suffix.
permit(cidr: string): boolean Lets the addresses in cidr through though they are not public: 10.1.2.0/24, fd00:1::/64, or one address alone. False, with nothing added, when cidr is not an address and a prefix length that fits it.