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();
outboundAddressAllowed
Whether policy lets a connection go to the sixteen address bytes at addr[off]: a prefix it permits, or else a public address.
outboundAddressPublic
Whether the sixteen address bytes at addr[off] are public, as the module comment defines it.
outboundAddressText
The sixteen address bytes at addr[off] as text, for an error to name.
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.
outboundHostAllowed
Whether policy lets a URL name host, as the URL parser gives it (lower-cased, an IPv6 literal without its brackets).
OutboundPolicy
What a client that fetches untrusted URLs may reach.
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
policyOutboundPolicyrequiredThe policy whose permits are checked first.
addru8[]requiredThe array holding the address; an IPv4 one in its ::ffff: form, as nish
offi32requiredWhere the address's sixteen bytes start in addr.
returnsbooleanTrue 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[]requiredThe array holding the address; an IPv4 one in its ::ffff: form, as nish
offi32requiredWhere the address's sixteen bytes start in addr.
returnsbooleanTrue 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[]requiredThe array holding the address.
offi32requiredWhere the address's sixteen bytes start in addr.
returnsstringDotted 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
policyOutboundPolicyrequiredThe policy each address is checked against, as outboundAddressAllowed checks it.
addressesu8[]requiredThe records, each sixteen address bytes and a two-byte port, reordered in place.
counti32requiredHow many records addresses holds from its start; one that does not fit panics.
returnsi32How 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
policyOutboundPolicyrequiredThe policy whose allowHost names are checked.
hoststringrequiredThe URL's host; its case and one trailing dot do not matter.
returnsbooleanTrue 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. |

