// Package outbound holds the one rule for URLs quarry sends something to
// on its own initiative: a webhook's payload, a mirror's or chat
// bridge's credentials, a runner's token and the private tree it
// fetches back.
//
// There are two questions, and they have two entry points because their
// answers differ.
//
// CheckOperator is for an address the site operator configured (a
// runner's forge URL): https anywhere, plain http only to this machine.
//
// CheckUser is for an address somebody who can merely create a
// repository asked the server to call. Everything CheckOperator refuses,
// and also any address that resolves to loopback, private, link-local,
// shared, unspecified or multicast space: a forge's own listeners and
// its cloud metadata service live there, and a delivery's status code
// would tell the caller what answered. The check is by resolved address,
// never by the string, and a name with ANY refused address is refused.
//
// A check at configuration time is not enough, because a name can
// answer differently when it is used. Policy.NewClient is the one HTTP
// client for destinations a user chose: its dialer refuses the same
// address classes at connect time, on the address actually dialled.
// Requests made by a child process (git, zit) cannot be hooked that way;
// they get the check at configuration and again before each run.
package outbound
import (
"context"
"errors"
"fmt"
"log"
"net"
"net/http"
"net/netip"
"net/url"
"strconv"
"strings"
"sync"
"sync/atomic"
"syscall"
"time"
)
// CheckOperator parses raw and refuses anything but https, or http to a
// loopback host. It does not resolve: the operator chose this address.
func CheckOperator(raw string) (*url.URL, error) {
u, err := url.Parse(strings.TrimSpace(raw))
if err != nil || u.Host == "" {
return nil, errors.New("not a url with a host")
}
switch u.Scheme {
case "https":
return u, nil
case "http":
if Loopback(u.Hostname()) {
return u, nil
}
return nil, errors.New("must be https; plain http is allowed only to this machine (localhost, 127.0.0.0/8, ::1)")
}
return nil, errors.New("must be an https url")
}
// Loopback says whether host names this machine. "localhost" by name,
// or an address in 127.0.0.0/8 or ::1. A name that merely starts like
// one ("127.evil.example") is a name, and names other than localhost
// are resolved by somebody else.
func Loopback(host string) bool {
if strings.EqualFold(host, "localhost") {
return true
}
ip := net.ParseIP(host)
return ip != nil && ip.IsLoopback()
}
// Policy is a rule for which addresses a user-supplied destination may
// reach, and the resolver it asks.
type Policy struct {
// Resolve answers a host name with its addresses; nil is the
// system resolver. Injectable so a test can make a name answer
// differently the second time.
Resolve func(ctx context.Context, host string) ([]net.IPAddr, error)
allow atomic.Pointer[[]netip.Prefix]
allowPrivate atomic.Bool
base *Policy
// Connect makes one connection to an address that has been vetted
// (an IP and port); nil dials for real. A test injects one so the
// address class is what is tested and no packet leaves the machine.
Connect func(ctx context.Context, network, addr string) (net.Conn, error)
}
// Default is the policy for webhooks, mirrors, buckets and every other
// destination a user names. Nothing private is allowed until the
// operator lists it (ParseAllowance, Allow).
var Default = &Policy{}
// Bridges is Default plus the older blanket switch for chat bridges and
// Fossil remotes (--allow-private-bridges): AllowAllPrivate widens only
// this policy, never Default.
var Bridges = &Policy{base: Default}
// Allow replaces the addresses this policy admits although they are in
// a refused class. An empty list is the default: nothing.
func (p *Policy) Allow(prefixes []netip.Prefix) {
cp := append([]netip.Prefix(nil), prefixes...)
p.allow.Store(&cp)
}
// Allowed is the list Allow last set.
func (p *Policy) Allowed() []netip.Prefix {
if l := p.allow.Load(); l != nil {
return append([]netip.Prefix(nil), *l...)
}
return nil
}
// Allowing is p, or when all is true a child of p that also admits every
// refused class: for one bridge an operator or a test opened up, without
// widening p.
func (p *Policy) Allowing(all bool) *Policy {
if !all {
return p
}
c := &Policy{base: p}
c.allowPrivate.Store(true)
return c
}
// AllowAllPrivate admits every refused class on this policy.
func (p *Policy) AllowAllPrivate(on bool) { p.allowPrivate.Store(on) }
func (p *Policy) allowed(a netip.Addr) bool {
if p.allowPrivate.Load() {
return true
}
if l := p.allow.Load(); l != nil {
for _, pre := range *l {
if pre.Contains(a) {
return true
}
}
}
return p.base != nil && p.base.allowed(a)
}
// ParseAllowance reads the operator's list: comma-separated IPs, CIDRs
// and host names. A name is resolved once, here, to the addresses it has
// now; restart to refresh. A dial-time check only sees addresses, so a
// name cannot be matched any other way without reopening rebinding.
func ParseAllowance(ctx context.Context, list string, resolve func(context.Context, string) ([]net.IPAddr, error)) ([]netip.Prefix, error) {
if resolve == nil {
resolve = lookup
}
var out []netip.Prefix
for _, item := range strings.Split(list, ",") {
item = strings.TrimSpace(item)
if item == "" {
continue
}
if pre, err := netip.ParsePrefix(item); err == nil {
out = append(out, pre.Masked())
continue
}
if a, err := netip.ParseAddr(item); err == nil {
out = append(out, netip.PrefixFrom(a.Unmap(), a.Unmap().BitLen()))
continue
}
ips, err := resolve(ctx, item)
if err != nil || len(ips) == 0 {
return nil, fmt.Errorf("allowed host %q does not resolve", item)
}
for _, ip := range ips {
if a, ok := netip.AddrFromSlice(ip.IP); ok {
a = a.Unmap()
out = append(out, netip.PrefixFrom(a, a.BitLen()))
}
}
}
return out, nil
}
func lookup(ctx context.Context, host string) ([]net.IPAddr, error) {
return net.DefaultResolver.LookupIPAddr(ctx, host)
}
func mustPrefixes(cidrs ...string) []netip.Prefix {
out := make([]netip.Prefix, len(cidrs))
for i, c := range cidrs {
out[i] = netip.MustParsePrefix(c)
}
return out
}
// refused are the classes a user-supplied destination may not reach.
// IPv4-mapped IPv6 is unmapped before the test; the IPv4-compatible
// form (::a.b.c.d) is inside ::/96.
var refused = mustPrefixes(
"0.0.0.0/8", // this network, unspecified
"10.0.0.0/8", // RFC 1918
"100.64.0.0/10", // carrier-grade NAT
"127.0.0.0/8", // loopback
"169.254.0.0/16", // link-local, cloud metadata
"172.16.0.0/12", // RFC 1918
"192.0.0.0/24", // IETF protocol assignments
"192.0.2.0/24", // documentation
"198.51.100.0/24", // documentation
"203.0.113.0/24", // documentation
"192.168.0.0/16", // RFC 1918
"198.18.0.0/15", // benchmarking
"224.0.0.0/4", // multicast
"240.0.0.0/4", // reserved, and the broadcast address
"::/96", // unspecified, loopback, IPv4-compatible
"fc00::/7", // RFC 4193 unique local
"fe80::/10", // link-local
"fec0::/10", // site-local, deprecated
"ff00::/8", // multicast
"64:ff9b:1::/48", // local-use NAT64
"::ffff:0:0:0/96", // IPv4-translated (SIIT)
"100::/64", // discard-only
"2001::/32", // Teredo
"2001:10::/28", // ORCHID
"2001:20::/28", // ORCHIDv2
"2001:db8::/32", // documentation
)
// Reserved says whether a destination at ip is in a class a user may
// not name. An IPv6 address that carries an IPv4 one (NAT64 well-known
// prefix, 6to4) is judged by the address inside, since a gateway
// delivers it there.
func Reserved(ip netip.Addr) bool {
ip = ip.Unmap().WithZone("") // Prefix.Contains is false for a zoned address
if in, ok := embedded(ip); ok && Reserved(in) {
return true
}
for _, pre := range refused {
if pre.Contains(ip) {
return true
}
}
return false
}
func embedded(ip netip.Addr) (netip.Addr, bool) {
if !ip.Is6() {
return netip.Addr{}, false
}
b := ip.As16()
switch {
case b[0] == 0x00 && b[1] == 0x64 && b[2] == 0xff && b[3] == 0x9b && allZero(b[4:12]):
return netip.AddrFrom4([4]byte(b[12:16])), true
case b[0] == 0x20 && b[1] == 0x02:
return netip.AddrFrom4([4]byte(b[2:6])), true
}
return netip.Addr{}, false
}
func allZero(b []byte) bool {
for _, c := range b {
if c != 0 {
return false
}
}
return true
}
// legacyIPv4 reads a host the way inet_aton does: one to four parts,
// each decimal, octal (leading 0) or hex (0x). A system resolver, curl
// or git may read "2130706433" or "0x7f.1" as 127.0.0.1 where Go does
// not, so such a host is judged as the address it would be and then
// refused as a spelling nobody should rely on.
func legacyIPv4(host string) (netip.Addr, bool) {
if host == "" || strings.Trim(host, "0123456789.xXabcdefABCDEF") != "" {
return netip.Addr{}, false
}
parts := strings.Split(host, ".")
if len(parts) > 4 {
return netip.Addr{}, false
}
var vals []uint64
for _, s := range parts {
if s == "" {
return netip.Addr{}, false
}
base := 10
switch {
case strings.HasPrefix(s, "0x") || strings.HasPrefix(s, "0X"):
base, s = 16, s[2:]
case len(s) > 1 && s[0] == '0':
base, s = 8, s[1:]
}
v, err := strconv.ParseUint(s, base, 32)
if err != nil {
return netip.Addr{}, false
}
vals = append(vals, v)
}
var n uint64
for i, v := range vals[:len(vals)-1] {
if v > 255 {
return netip.Addr{}, false
}
n |= v << (24 - 8*uint(i))
}
last := vals[len(vals)-1]
if last >= 1<<(8*uint(5-len(vals))) {
return netip.Addr{}, false
}
n |= last
return netip.AddrFrom4([4]byte{byte(n >> 24), byte(n >> 16), byte(n >> 8), byte(n)}), true
}
// Why a destination was refused. The code leads the error text, so a
// stored error can be told apart without reading its words: a name that
// does not resolve may be a DNS outage and worth retrying, an address
// the forge will not call is not.
const (
KindAddress = "address-refused"
KindUnresolved = "name-unresolved"
KindForm = "address-form-refused"
)
// Refusal is the error for a destination the policy will not reach. It
// names a host, never the URL, and never the address a name resolved to
// (that would let a caller map internal DNS); that goes to the log.
type Refusal struct{ Kind, Host, Why string }
func (r *Refusal) Error() string { return r.Kind + ": " + r.Host + ": " + r.Why }
// Addrs resolves host and returns its addresses, or a *Refusal if there
// are none or ANY is in a refused class the policy does not allow.
func (p *Policy) Addrs(ctx context.Context, host string) ([]net.IPAddr, error) {
if host == "" {
return nil, &Refusal{Kind: KindForm, Host: "(none)", Why: "no host"}
}
if a, err := netip.ParseAddr(host); err == nil {
if a.Zone() != "" {
return nil, &Refusal{Kind: KindForm, Host: host, Why: "an address with a zone is not a destination"}
}
return p.vet(host, []net.IPAddr{{IP: net.IP(a.AsSlice())}})
}
if _, ok := legacyIPv4(host); ok {
return nil, &Refusal{Kind: KindForm, Host: host,
Why: "an address written in an unusual form; write it as four numbers separated by dots"}
}
ips, err := p.Resolver()(ctx, host)
if err != nil || len(ips) == 0 {
return nil, &Refusal{Kind: KindUnresolved, Host: host, Why: "the name does not resolve"}
}
return p.vet(host, ips)
}
// Resolver is the policy's lookup: its own, its base's, or the system's.
func (p *Policy) Resolver() func(context.Context, string) ([]net.IPAddr, error) {
for q := p; q != nil; q = q.base {
if q.Resolve != nil {
return q.Resolve
}
}
return lookup
}
func (p *Policy) vet(host string, ips []net.IPAddr) ([]net.IPAddr, error) {
for _, ip := range ips {
a, ok := netip.AddrFromSlice(ip.IP)
if !ok {
return nil, &Refusal{Kind: KindForm, Host: host, Why: "an unreadable address"}
}
a = a.Unmap()
if Reserved(a) && !p.allowed(a) {
log.Printf("outbound: refused %s: it is, or resolves to, %s", host, a)
return nil, &Refusal{Kind: KindAddress, Host: host,
Why: "the host is, or resolves to, an address the forge will not call; the site operator can allow it with --allow-outbound"}
}
}
return ips, nil
}
// CheckUser is the rule for an address a user asked the server to call:
// https, or http only to a loopback address the operator allowed; no
// user name or password; and a host whose every address is public or
// allowed. It resolves the host, so call it where a lookup is fine.
func (p *Policy) CheckUser(raw string) (*url.URL, error) {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
return p.CheckUserContext(ctx, raw)
}
// CheckUserContext is CheckUser with the caller's context.
func (p *Policy) CheckUserContext(ctx context.Context, raw string) (*url.URL, error) {
u, err := url.Parse(strings.TrimSpace(raw))
if err != nil || u.Host == "" || u.Hostname() == "" {
return nil, errors.New("not a url with a host")
}
if u.Scheme != "https" && u.Scheme != "http" {
return nil, errors.New("must be an https url")
}
if u.User != nil || strings.Contains(u.Host, "@") {
return nil, errors.New("must not carry a user name or password")
}
if port := u.Port(); port != "" {
if n, err := strconv.Atoi(port); err != nil || n < 1 || n > 65535 {
return nil, errors.New("the port is not a port")
}
}
ips, err := p.Addrs(ctx, u.Hostname())
if err != nil {
return nil, err
}
if u.Scheme == "http" {
for _, ip := range ips {
if !ip.IP.IsLoopback() {
return nil, errors.New("must be https; plain http is allowed only to a loopback address the site operator allowed")
}
}
}
return u, nil
}
// CheckUser is Default.CheckUser.
func CheckUser(raw string) (*url.URL, error) { return Default.CheckUser(raw) }
// control runs on every connection attempt with the address actually
// being dialled, after any resolution, so a name that answered public to
// the check and private to the dial is refused here.
func (p *Policy) control(network, address string, _ syscall.RawConn) error {
ap, err := netip.ParseAddrPort(address)
if err != nil {
return &Refusal{Kind: KindForm, Host: "(unparsed)", Why: "the connection's address is not an address"}
}
a := ap.Addr().Unmap()
if Reserved(a) && !p.allowed(a) {
log.Printf("outbound: refused a connection to %s", a)
return &Refusal{Kind: KindAddress, Host: "(connect)", Why: "the connection's address is one the forge will not call"}
}
return nil
}
// NewClient is the one HTTP client for requests to a destination a user
// chose. Its dialer resolves once through the policy, dials only the
// addresses it vetted, and refuses again in a Control hook on the
// address really dialled. It ignores proxy settings (a proxy would be
// dialled instead of the destination, defeating the guard) and does not
// follow redirects: a 3xx is returned as the response. Timeout is the
// client's, 0 for none.
func (p *Policy) NewClient(timeout time.Duration) *http.Client {
tr := http.DefaultTransport.(*http.Transport).Clone()
tr.Proxy = nil
tr.DialContext = p.DialContext
return &http.Client{
Timeout: timeout,
Transport: tr,
CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },
}
}
// DialContext connects to addr (host:port) the way NewClient does: the
// host is resolved once through the policy, only the addresses that
// passed are dialled, and the Control hook judges each one again. For a
// caller that must make its own connection to a host somebody else
// named.
func (p *Policy) DialContext(ctx context.Context, network, addr string) (net.Conn, error) {
host, port, err := net.SplitHostPort(addr)
if err != nil {
return nil, err
}
ips, err := p.Addrs(ctx, host)
if err != nil {
return nil, err
}
d := &net.Dialer{Timeout: 15 * time.Second, KeepAlive: 30 * time.Second, Control: p.control}
connect := d.DialContext
for q := p; q != nil; q = q.base {
if q.Connect != nil {
connect = q.Connect
break
}
}
var errs []error
for _, ip := range ips {
conn, err := connect(ctx, network, net.JoinHostPort(ip.IP.String(), port))
if err == nil {
return conn, nil
}
errs = append(errs, err)
if ctx.Err() != nil {
break
}
}
return nil, errors.Join(errs...)
}
// NewClient is Default.NewClient.
func NewClient(timeout time.Duration) *http.Client { return Default.NewClient(timeout) }
var (
sharedOnce sync.Once
sharedClient *http.Client
)
// Client is one shared guarded client with no timeout of its own, for a
// caller that bounds each request with a context.
func Client() *http.Client {
sharedOnce.Do(func() { sharedClient = Default.NewClient(0) })
return sharedClient
}
// Name is raw as an error may show it: scheme and host, never the path,
// query or credentials, any of which can be a secret.
func Name(raw string) string {
u, err := url.Parse(strings.TrimSpace(raw))
if err != nil || u.Host == "" {
return "the address"
}
return u.Scheme + "://" + u.Hostname()
}
// ErrText is err as text with no full URL in it. net/http wraps a
// failure as `Post "https://host/path?token=…": …`; a URL may hold a
// credential in its query, and this text lands in stored delivery
// records. It names the operation and the scheme and host, then the
// cause.
func ErrText(err error) string {
var ue *url.Error
if errors.As(err, &ue) {
where := ""
if u, perr := url.Parse(ue.URL); perr == nil && u.Host != "" {
where = " " + u.Scheme + "://" + u.Host
}
return ue.Op + where + ": " + ue.Err.Error()
}
return err.Error()
}