Skip to content
quarry Artifact [686ed9b617]
Login

Artifact [686ed9b617]

Artifact 686ed9b6178308a122b5a766592d8e301413d1e3731c1a3ab337b8868c136891:


// 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")
}

// Check is CheckUser on the default policy. Deprecated: name the rule
// you mean. It stays so a caller not yet moved is strict, not open.
func Check(raw string) (*url.URL, error) { return Default.CheckUser(raw) }

// 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()
}