remote

package
v0.8.0-alpha Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

Documentation

Overview

Package remote holds what remote access is built on: deciding who a request really comes from (and whether forwarded headers may be believed), HTTPS certificates, and the numbers behind the Remote Access settings page.

Index

Constants

View Source
const (
	SubjectHomeOnly = "Home network only"
	SubjectYes      = "Reachable from away: yes"
	SubjectNotYet   = "Reachable from away: not yet"
	SubjectNo       = "Reachable from away: no"
)

The subjects. docs/REMOTE.md lists each one, which a test checks.

View Source
const (
	// DefaultPerAddress is how many one address can hold (an IPv6 /64 counts as one address).
	DefaultPerAddress = 128
)

Each open connection costs a descriptor and some memory, so a stranger holding open as many as they can is a way to stop the server for everyone.

View Source
const PlainAwayWarning = "" /* 216-byte string literal not displayed */

PlainAwayWarning is said wherever it matters while unencrypted connections from away are allowed: the status card, the dashboard and the apps.

Variables

Subjects are all of them, for the docs test.

Functions

func Ago

func Ago(t, now time.Time) string

Ago says how long ago something was, the way the settings page does.

func HomeSubnets

func HomeSubnets() []netip.Prefix

HomeSubnets returns homeSubnetsOf for this machine, looked up at most once a minute (and only ever for clients with global IPv6 addresses).

func LimitKey

func LimitKey(a netip.Addr) string

LimitKey is the unit a limit applies to: one IPv4 address, or one IPv6 /64 (a single home or server is usually given a whole /64, so counting single IPv6 addresses would limit nobody).

func LocalAddress

func LocalAddress(host string) bool

LocalAddress says what someone typed names something at home or on their VPN.

func LocalName

func LocalName(host string) bool

LocalName says a host name is one only a local network can resolve: a computer's own name, or one under a suffix nobody can register. A name anyone can register can point anywhere.

func ParseNets

func ParseNets(text string) ([]netip.Prefix, error)

ParseNets reads a list of addresses and networks (separated by commas, spaces or new lines). A network wider than /8 (IPv4) or /32 (IPv6) is refused: trusting that much of the internet is never what anyone means.

func SecureHint

func SecureHint(r *http.Request) bool

SecureHint: the connection is encrypted, or a header claims a proxy in front of this server encrypts it. The header is only good enough for choices that can harm nobody but whoever forged it, such as marking a cookie Secure.

func Throttle

func Throttle(ctx context.Context, w http.ResponseWriter, bitsPerSec int64) http.ResponseWriter

Throttle limits what one response sends, in bits per second. Players read ahead, so the first seconds' worth goes out at once and only after that does the limit bite.

func ValidDomain

func ValidDomain(d string) bool

ValidDomain checks a name Let's Encrypt could issue for.

func WithP2P

func WithP2P(ctx context.Context, c P2PConn) context.Context

WithP2P marks a connection's context as peer-to-peer.

Types

type CertInfo

type CertInfo struct {
	Names      []string `json:"names"`
	Issuer     string   `json:"issuer"`
	NotAfter   int64    `json:"notAfter"`
	DaysLeft   int      `json:"daysLeft"`
	SelfSigned bool     `json:"selfSigned"`
}

CertInfo describes the certificate in use.

type Client

type Client struct {
	IP    netip.Addr // the client's address as far as it can be known
	Peer  netip.Addr // who opened the connection to this server
	Where Where
	// Proxied: a trusted proxy passed this request on and named the client.
	Proxied bool
	// Unverified: the request carries forwarded headers but did not come from
	// a trusted proxy. They are ignored, and it counts as coming from the
	// internet, which is the safe direction for everything that uses this.
	Unverified bool
	// Secure: the connection from the browser is encrypted. Direct TLS, or a
	// trusted proxy says so.
	Secure bool
	// ForwardedHost is the address the browser used, from a trusted proxy only.
	ForwardedHost string
	// P2P: the request came over a peer-to-peer connection (see p2p.go), from
	// the device with this key. Where is then always Internet.
	P2P        bool
	P2PDevice  string
	P2PRelayed bool
}

Client is what a request says about its sender, after deciding how much of it can be believed.

func (Client) Direct

func (c Client) Direct() bool

Direct: nothing stands between this server and the client.

type ConnLimit

type ConnLimit struct {
	Total      int
	PerAddress int
	// Policy is the owner's current choices: a trusted reverse proxy is many visitors, so
	// it isn't limited as one address.
	Policy func() *Policy
	Log    *slog.Logger
	// contains filtered or unexported fields
}

ConnLimit counts open connections. One ConnLimit covers every listener wrapped with it.

func (*ConnLimit) Open

func (l *ConnLimit) Open() int

Open is how many connections are open now.

func (*ConnLimit) Wrap

func (l *ConnLimit) Wrap(ln net.Listener) net.Listener

Wrap counts the connections a listener accepts, and closes those over the limits.

type Facts

type Facts struct {
	On        bool // connections from away are allowed
	LocalOnly bool // the server listens on this computer only
	PlainAway bool // the owner lets the internet in without encryption
	Ways      []Way
	Proof     time.Time // when the outside test last passed (zero: never, or too long ago)
	Now       time.Time
}

Facts are what Describe needs to know.

type HTTPS

type HTTPS struct {

	// Conns counts this port's connections with the home port's; set before Apply.
	Conns *ConnLimit
	// contains filtered or unexported fields
}

HTTPS owns the listener and certificates.

func NewHTTPS

func NewHTTPS(handler http.Handler, dataDir string, log *slog.Logger) *HTTPS

NewHTTPS prepares an HTTPS port serving handler. Nothing opens until Apply.

func (*HTTPS) Addr

func (h *HTTPS) Addr() net.Addr

Addr is the port's address (nil when closed).

func (*HTTPS) Apply

func (h *HTTPS) Apply(cfg HTTPSConfig) error

Apply brings the port in line with cfg. Unchanged settings leave it running. A certificate that can't be used is reported, and the port stays closed.

func (*HTTPS) Obtain

func (h *HTTPS) Obtain()

Obtain asks Let's Encrypt for the certificate now, instead of waiting for the first visitor, so that Settings can report how it went. It runs in the background; Status follows it.

func (*HTTPS) Running

func (h *HTTPS) Running() bool

Running: the port is open.

func (*HTTPS) Shutdown

func (h *HTTPS) Shutdown(ctx context.Context)

Shutdown closes the port.

func (*HTTPS) Status

func (h *HTTPS) Status(ctx context.Context) HTTPSStatus

Status reports the port and its certificate. It never starts getting one.

type HTTPSConfig

type HTTPSConfig struct {
	Mode     string // off | acme | cert
	Host     string // address to listen on ("" = every network card)
	Port     int    // 0 picks a free port (tests)
	Domain   string // acme
	Email    string // acme, optional
	CertFile string // cert
	KeyFile  string // cert
}

HTTPSConfig is what the HTTPS port should be doing.

type HTTPSStatus

type HTTPSStatus struct {
	Mode      string    `json:"mode"`
	Running   bool      `json:"running"`
	Port      int       `json:"port"`
	Error     string    `json:"error,omitempty"`
	Obtaining bool      `json:"obtaining,omitempty"`
	Cert      *CertInfo `json:"cert,omitempty"`
}

HTTPSStatus is what Settings shows.

type Iface

type Iface struct {
	Name string
	Addr netip.Prefix
}

Iface is one address of one of this machine's network cards.

func Interfaces

func Interfaces() []Iface

Interfaces lists the addresses of the network cards that are up.

type P2PConn

type P2PConn struct {
	// Addr is the address the connection is counted under: the other end's
	// public address when it is direct, otherwise one made up for it. It is
	// never an address of this computer or of the home network.
	Addr netip.Addr
	// Device is the other end's key, as its ID.
	Device  string
	Relayed bool
	// Known: the device is on the server's list.
	Known bool
}

P2PConn is what is known about a peer-to-peer connection.

func P2PFrom

func P2PFrom(ctx context.Context) (P2PConn, bool)

P2PFrom reads the mark.

type Policy

type Policy struct {
	Trusted []netip.Prefix // reverse proxies whose forwarded headers are believed
	Home    []netip.Prefix // extra networks that count as the home network
	Away    []netip.Prefix // networks that count as away, even if private (a VPN of your own)
	// LocalV6 lists this machine's own IPv6 home subnets; nil uses HomeSubnets.
	LocalV6 func() []netip.Prefix
}

Policy is the owner's choices about networks. A nil Policy trusts no proxy and knows only the built-in ranges.

func (*Policy) Classify

func (p *Policy) Classify(a netip.Addr) Where

Classify says where an address is. The owner's lists win over the built-in ranges, and "away" wins over everything: a private VPN address must not count as the home network if the owner says it doesn't.

func (*Policy) Resolve

func (p *Policy) Resolve(r *http.Request) Client

Resolve works out who sent a request. Forwarded headers are read only when the connection itself comes from a trusted proxy, and then from the right (the entry that proxy added) until the first address that is not a trusted proxy: everything further left was written by the client and may be made up.

RFC 7239's Forwarded header is never read: proxies that only maintain X-Forwarded-For pass a client's made-up Forwarded through untouched.

type Standing

type Standing struct {
	// Level is the colour: good (working as chosen, green), waiting (asked
	// for, not working yet, amber) or fault (something is broken, red).
	Level   string `json:"level"`
	Subject string `json:"subject"` // what it's about, with the short answer
	Summary string `json:"summary"` // the whole answer, in a sentence or two
	Home    string `json:"home"`    // devices at home
	Away    string `json:"away"`    // devices away from home
	Checked string `json:"checked"` // how that is known
	// Warning stays while the owner lets the internet in unencrypted.
	Warning string `json:"warning,omitempty"`
}

Standing is how remote access stands right now.

func Describe

func Describe(f Facts) Standing

Describe says how remote access stands.

type VPNAddr

type VPNAddr struct {
	Kind string `json:"kind"` // Tailscale | NetBird | VPN
	IP   string `json:"ip"`
}

VPNAddr is an address of this machine on a private overlay network.

func FindVPNs

func FindVPNs(list []Iface) []VPNAddr

FindVPNs finds overlay networks from what the network cards look like. No program is run and nothing is sent. An address in 100.64.0.0/10 on a card with no telling name could also be a modem handing out a carrier's address, so only cards recognised by name count.

type Way

type Way struct {
	Kind     string // vpn | https | proxy | plain
	Label    string // Tailscale, NetBird, VPN, "the internet, over HTTPS", "your reverse proxy"
	URL      string // where to connect, if known
	State    string // ok | waiting | problem
	Detail   string // what is wrong, for a problem
	LastSeen time.Time
}

Way is one way in from away, as the status found it.

type Where

type Where int

Where a client is, from least to most trusted. The zero value is the least trusted one, so anything unknown fails closed.

const (
	Internet Where = iota // anywhere else
	VPN                   // a private overlay network (Tailscale, NetBird, or a network the owner named)
	Home                  // the home network
	Machine               // this computer
)

func (Where) AtHome

func (w Where) AtHome() bool

AtHome: the client is on this computer or the home network.

func (Where) String

func (w Where) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL