A container may declare the capabilities it is granted (hq ADR 0169)

Exactly the names declared reach the runtime, named in the spec so a change recreates the container; a name that is not a capability's is refused and a privileged container stays undeclarable. For a seat holder whose runtime changes the machine's packet filter.
2026-10-02 13:27:34 +02:00
10 changed files with 84 additions and 313 deletions
@@ -1,119 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-
-	"github.com/novox/mesh-host/internal/apply"
-	"github.com/novox/mesh-host/internal/identity"
-)
-
-// Joining through the tunnel (novox/hq ADR 0169).
-//
-// **The bus is never open to the internet, so a joining machine reaches it over the tunnel.** It
-// makes its tunnel key first and prints the public half; the token is issued for that key, and the
-// hub is told the key before the token is shown; the token carries the one peer this machine needs.
-// So the tunnel can come up before the mesh has said anything else — the circle ADR 0004 broke by
-// carrying the bus's address in the token is broken here by carrying the hub's.
-
-// tunnelConfigPath and tunnelUnit are where the mesh's own declaration puts the private network, so
-// the first tunnel is the same interface and unit the mesh takes over, not a second one beside it.
-var (
-	tunnelConfigPath = "/etc/wireguard/mesh0.conf"
-	tunnelUnit       = "wg-quick@mesh0"
-	// lookPath finds WireGuard's tools; a variable so a test needs none installed.
-	lookPath = exec.LookPath
-)
-
-// keyCommand makes this machine's tunnel key, or reads the one it already made, and prints the
-// public half: what the token is issued for. Making it twice would be a token issued for a key the
-// machine no longer has, so an existing key is kept.
-func keyCommand(opts options) error {
-	path := identity.OverlayKeyPath(opts.state)
-	if key, err := identity.LoadOverlayKey(path); err == nil {
-		fmt.Println(key.Public)
-		return nil
-	} else if !errors.Is(err, os.ErrNotExist) {
-		return err
-	}
-	if _, err := os.Stat(identity.Path(opts.state)); err == nil {
-		return fmt.Errorf("this machine has joined already (%s), and its tunnel key is its own; "+
-			"there is no key to make", identity.Path(opts.state))
-	}
-	key, err := identity.GenerateOverlayKey()
-	if err != nil {
-		return err
-	}
-	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
-		return err
-	}
-	if err := os.WriteFile(path, []byte(key.Private+"\n"), 0o600); err != nil {
-		return fmt.Errorf("cannot write this machine's tunnel key: %w", err)
-	}
-	fmt.Println(key.Public)
-	fmt.Fprintln(os.Stderr, "\nthis machine's tunnel key, made here; the private half stays in "+path+".\n"+
-		"Issue the token for it — `token issue --new <name> --overlay-key <the line above>` — and enrol with that token.")
-	return nil
-}
-
-// tunnelKeyFor is the key a token through the tunnel was issued for, read from where `key` left it.
-// Refused when there is none, or it is another: the hub knows only the key the token names.
-func tunnelKeyFor(t *identity.TokenTunnel, state string) (identity.OverlayKey, error) {
-	path := identity.OverlayKeyPath(state)
-	key, err := identity.LoadOverlayKey(path)
-	if errors.Is(err, os.ErrNotExist) {
-		return identity.OverlayKey{}, fmt.Errorf("this token was issued for a tunnel key, and this " +
-			"machine has none: run `nox-mesh-host key` here first and issue the token for the key it prints")
-	}
-	if err != nil {
-		return identity.OverlayKey{}, err
-	}
-	if key.Public != t.Key {
-		return identity.OverlayKey{}, fmt.Errorf("this token was issued for the tunnel key %s, and this "+
-			"machine's is %s — it is another machine's token, or the key was made again; issue a new "+
-			"token for %s", t.Key, key.Public, key.Public)
-	}
-	return key, nil
-}
-
-// tunnelConfig is the first tunnel: this machine's address, and the hub as its one peer, reaching the
-// whole private network through it. The private key is set from its file, as the mesh's own
-// declaration does it, so the file holds no secret.
-func tunnelConfig(t *identity.TokenTunnel, keyPath string) string {
-	return fmt.Sprintf(`# Written by nox-mesh-host enrol: the one peer a joining machine needs (novox/hq ADR 0169).
-# The mesh's own declaration replaces this once the machine has joined.
-[Interface]
-Address = %s
-PostUp = wg set %%i private-key %s
-
-[Peer]
-PublicKey = %s
-Endpoint = %s
-AllowedIPs = %s
-PersistentKeepalive = 25
-`, t.Address, keyPath, t.HubKey, t.HubEndpoint, t.Range)
-}
-
-// bringTheTunnelUp writes the first tunnel and starts it, so the bus the token names can be reached.
-func bringTheTunnelUp(ctx context.Context, t *identity.TokenTunnel, keyPath string, run apply.Runner) error {
-	if _, err := lookPath("wg-quick"); err != nil {
-		return errors.New("joining through the tunnel needs WireGuard's tools on this machine " +
-			"(wireguard-tools), and wg-quick is not here")
-	}
-	if err := os.MkdirAll(filepath.Dir(tunnelConfigPath), 0o700); err != nil {
-		return err
-	}
-	if err := os.WriteFile(tunnelConfigPath, []byte(tunnelConfig(t, keyPath)), 0o600); err != nil {
-		return fmt.Errorf("cannot write the first tunnel: %w", err)
-	}
-	if out, err := run(ctx, "systemctl", "restart", tunnelUnit); err != nil {
-		return fmt.Errorf("the first tunnel would not start (%s): %v %s", tunnelUnit, err, strings.TrimSpace(out))
-	}
-	fmt.Printf("the tunnel to the hub is up: %s, through %s\n", t.Address, t.HubEndpoint)
-	return nil
-}
@@ -1,112 +0,0 @@
-package main
-
-import (
-	"context"
-	"io"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-host/internal/identity"
-)
-
-// `key` makes the tunnel key once and prints its public half; asked again it prints the same one,
-// because a token may already have been issued for it (novox/hq ADR 0169).
-func TestKeyMakesTheTunnelKeyOnceAndKeepsIt(t *testing.T) {
-	dir := t.TempDir()
-	opts := options{state: filepath.Join(dir, "state.json")}
-	first := captureStdout(t, func() {
-		if err := keyCommand(opts); err != nil {
-			t.Fatal(err)
-		}
-	})
-	second := captureStdout(t, func() {
-		if err := keyCommand(opts); err != nil {
-			t.Fatal(err)
-		}
-	})
-	if strings.TrimSpace(first) == "" || strings.TrimSpace(first) != strings.TrimSpace(second) {
-		t.Fatalf("the key changed between two asks: %q then %q", first, second)
-	}
-	info, err := os.Stat(identity.OverlayKeyPath(opts.state))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if info.Mode().Perm() != 0o600 {
-		t.Errorf("the private half is readable beyond root: %v", info.Mode().Perm())
-	}
-}
-
-// A token through the tunnel takes the key it was issued for, and says so when this machine has none
-// or another.
-func TestATokenThroughTheTunnelTakesItsOwnKey(t *testing.T) {
-	dir := t.TempDir()
-	state := filepath.Join(dir, "state.json")
-	tt := &identity.TokenTunnel{Key: "x", Address: "10.42.0.9/32", Range: "10.42.0.0/16", HubKey: "h", HubEndpoint: "198.51.100.1:51820"}
-	if _, err := tunnelKeyFor(tt, state); err == nil || !strings.Contains(err.Error(), "nox-mesh-host key") {
-		t.Fatalf("a machine with no key was not told to make one: %v", err)
-	}
-	captureStdout(t, func() { _ = keyCommand(options{state: state}) })
-	if _, err := tunnelKeyFor(tt, state); err == nil || !strings.Contains(err.Error(), "issued for the tunnel key x") {
-		t.Fatalf("another machine's token was taken: %v", err)
-	}
-	mine, _ := identity.LoadOverlayKey(identity.OverlayKeyPath(state))
-	tt.Key = mine.Public
-	if got, err := tunnelKeyFor(tt, state); err != nil || got.Public != mine.Public {
-		t.Fatalf("this machine's own token was refused: %v", err)
-	}
-}
-
-// The first tunnel is the mesh's interface and unit, with the hub as its one peer and no secret in
-// the file — the same shape the mesh's declaration replaces it with.
-func TestTheFirstTunnelIsTheMeshsInterfaceWithTheHubAsItsPeer(t *testing.T) {
-	dir := t.TempDir()
-	tunnelConfigPath = filepath.Join(dir, "wireguard", "mesh0.conf")
-	lookPath = func(string) (string, error) { return "/usr/bin/wg-quick", nil }
-	t.Cleanup(func() { tunnelConfigPath = "/etc/wireguard/mesh0.conf" })
-	var ran []string
-	run := func(_ context.Context, name string, args ...string) (string, error) {
-		ran = append(ran, name+" "+strings.Join(args, " "))
-		return "", nil
-	}
-	tt := &identity.TokenTunnel{Key: "k", Address: "10.42.0.9/32", Range: "10.42.0.0/16", HubKey: "HUBKEY", HubEndpoint: "198.51.100.1:51820"}
-	captureStdout(t, func() {
-		if err := bringTheTunnelUp(context.Background(), tt, "/var/lib/mesh-host/overlay.key", run); err != nil {
-			t.Fatal(err)
-		}
-	})
-	raw, err := os.ReadFile(tunnelConfigPath)
-	if err != nil {
-		t.Fatal(err)
-	}
-	conf := string(raw)
-	for _, want := range []string{"Address = 10.42.0.9/32", "PostUp = wg set %i private-key /var/lib/mesh-host/overlay.key",
-		"PublicKey = HUBKEY", "Endpoint = 198.51.100.1:51820", "AllowedIPs = 10.42.0.0/16", "PersistentKeepalive = 25"} {
-		if !strings.Contains(conf, want) {
-			t.Errorf("the first tunnel lacks %q:\n%s", want, conf)
-		}
-	}
-	if strings.Contains(conf, "PrivateKey") {
-		t.Error("the first tunnel's file holds the private key")
-	}
-	if len(ran) != 1 || ran[0] != "systemctl restart wg-quick@mesh0" {
-		t.Errorf("the tunnel was started as %v", ran)
-	}
-}
-
-// captureStdout is what fn printed to standard output.
-func captureStdout(t *testing.T, fn func()) string {
-	t.Helper()
-	r, w, err := os.Pipe()
-	if err != nil {
-		t.Fatal(err)
-	}
-	was := os.Stdout
-	os.Stdout = w
-	fn()
-	os.Stdout = was
-	w.Close()
-	out, _ := io.ReadAll(r)
-	return string(out)
-}
@@ -96,9 +96,6 @@ const usage = `mesh-host — the node host
  reconcile   make this machine match what the mesh last told it — or, before any
              mesh has, the bundle this host carries
  bundle      show what this host carries
-  key         make this machine's tunnel key, or read the one it made, and print the public
-              half: what its join token is issued for (novox/hq ADR 0169)
-  enrol --token T  join the mesh — through the tunnel when the token was issued for a key
  overlay take  take over the tunnel found here (novox/hq ADR 0105): its key becomes this
              node's overlay key and the mesh is told, signed; --tunnel <iface> when several are up
  owned       what this host has applied and still owns
@@ -215,9 +212,6 @@ func parseArgs(args []string) (string, options, error) {
 func run(ctx context.Context, command string, opts options) error {
 	jsonOut, timeout := opts.json, opts.timeout
 	switch command {
-	case "key":
-		return keyCommand(opts)
-
 	case "profile":
 		p := profile.Detect(ctx, profile.Default(nil), timeout)
 		if jsonOut {
@@ -794,18 +788,7 @@ func enrol(ctx context.Context, opts options) error {
 			fmt.Printf("this node's overlay key is the found tunnel's (%s): %s\n", tun, mine.Overlay.Public)
 		}
 	}
-	switch {
-	case found == nil && token.Tunnel != nil:
-		// Through the tunnel (novox/hq ADR 0169): the key `key` made, which the token names, and the
-		// tunnel brought up from the token before the bus is dialled — the bus is reached over it.
-		mine.Overlay, err = tunnelKeyFor(token.Tunnel, opts.state)
-		if err != nil {
-			return err
-		}
-		if err := bringTheTunnelUp(ctx, token.Tunnel, identity.OverlayKeyPath(opts.state), apply.ExecRunner); err != nil {
-			return err
-		}
-	case found == nil:
+	if found == nil {
 		mine.Overlay, err = identity.GenerateOverlayKey()
 		if err != nil {
 			return err
@@ -1583,6 +1583,11 @@ func containerSpecReading(r *declaration.Container, declares, reads map[string]s
 	for _, n := range r.Networks {
 		b.WriteString("also-on " + n + "\n")
 	}
+	// And the capabilities it was granted (ADR 0169): one gained or dropped is a different
+	// container, and the runtime cannot change a running one's.
+	for _, c := range r.Capabilities {
+		b.WriteString("cap " + c + "\n")
+	}
 	// The cadence is part of what was declared, so a changed schedule is a changed spec — the marker
 	// moves and the install is reported "updated" and re-established. Added only when present, so no
 	// ordinary container's or run-once step's digest moves for a field it does not set.
@@ -1777,6 +1782,9 @@ func applyContainer(ctx context.Context, r *declaration.Container, run Runner,
 	if r.Network != "" {
 		args = append(args, "--network", r.Network)
 	}
+	for _, c := range r.Capabilities {
+		args = append(args, "--cap-add", c)
+	}
 	for _, d := range r.Dns {
 		args = append(args, "--dns", d)
 	}
@@ -134,3 +134,42 @@ func TestALeftOutModuleIsNeitherRemovedNorForgotten(t *testing.T) {
 		t.Fatalf("keeping the left-out module's container was not said: %+v", report.Outcomes)
 	}
 }
+
+// A container's capabilities reach the runtime and are part of its spec (novox/hq ADR 0169).
+func TestACapabilityReachesTheRuntimeAndTheSpec(t *testing.T) {
+	var ran []string
+	run := func(_ context.Context, name string, args ...string) (string, error) {
+		if name != "docker" {
+			return "", errors.New("not installed")
+		}
+		switch args[0] {
+		case "info":
+			return "29.0.0\n", nil
+		case "container":
+			return "false\t\n", errors.New("no such container")
+		case "run":
+			ran = args
+			return "deadbeef\n", nil
+		}
+		return "", nil
+	}
+	d := parseTrusted(t, `{"declaration":1,"resources":[
+	  {"id":"fw","type":"container","name":"fw","image":"`+pinned+`","network":"host","capabilities":["NET_ADMIN"]}
+	]}`)
+	_, _, _ = Apply(context.Background(), archHost(t), d, store.State{}, store.OriginCarried, run, nil, nil)
+	granted := false
+	for i, a := range ran {
+		if a == "--cap-add" && i+1 < len(ran) && ran[i+1] == "NET_ADMIN" {
+			granted = true
+		}
+	}
+	if !granted {
+		t.Fatalf("the capability was not granted: %v", ran)
+	}
+	with := d.Resources[0].(*declaration.Container)
+	without := *with
+	without.Capabilities = nil
+	if containerSpec(with, inputs{}) == containerSpec(&without, inputs{}) {
+		t.Fatal("a capability is not part of the container's spec")
+	}
+}
@@ -940,6 +940,12 @@ type Container struct {
 	// its siblings can name before any of them can resolve anything.
 	Dns []string `json:"dns,omitempty"`

+	// Capabilities are the Linux capabilities this container is granted beyond the runtime's
+	// default set, by name (novox/hq ADR 0169): a holder's runtime that changes the machine's packet
+	// filter asks for NET_ADMIN. Exactly these, named in the spec so a change recreates the
+	// container; a privileged container stays undeclarable.
+	Capabilities []string `json:"capabilities,omitempty"`
+
 	// Networks are networks this container also joins once created, by name — a found network a
 	// per-machine setting keeps for a taken container (novox/hq ADR 0163, rule 4), so a
 	// neighbour that resolves it there keeps resolving it until the neighbour is taken too.
@@ -1039,6 +1045,12 @@ func (c *Container) validate(where string, _ bool) []string {
 				"static address anywhere but a user-defined one")
 		}
 	}
+	for _, cap := range c.Capabilities {
+		if !capabilityName.MatchString(cap) {
+			problems = append(problems, where+": capabilities names "+strconv.Quote(cap)+", which is not a "+
+				"capability's name (CAP_NET_ADMIN or NET_ADMIN)")
+		}
+	}
 	for _, n := range c.Networks {
 		problems = append(problems, (&Network{Name: n}).validate(where+": networks", false)...)
 		if n == c.Network {
@@ -1209,6 +1221,10 @@ type Adoption struct {
 	Untaken map[string][]string `json:"untaken,omitempty"`
 }

+// capabilityName is what a Linux capability is called: upper case, underscores, an optional CAP_
+// prefix. The runtime accepts either spelling.
+var capabilityName = regexp.MustCompile(`^(CAP_)?[A-Z][A-Z0-9_]*$`)
+
 // AdoptionPrefix is the id prefix of what the mesh itself declares because a node is adopted —
 // its openings and its guard. Nothing under it belongs to a module, so none of it is ever held.
 const AdoptionPrefix = "adoption."
@@ -504,3 +504,23 @@ func TestKeptNetworksAndLeftOutModulesAreReadStrictly(t *testing.T) {
 		t.Fatalf("a carried bundle leaving modules out was accepted: %v", err)
 	}
 }
+
+// A container may ask for a capability by name, and nothing else (novox/hq ADR 0169).
+func TestACapabilityIsNamedOrRefused(t *testing.T) {
+	image := "postgres@sha256:" + strings.Repeat("a", 64)
+	d, err := Parse([]byte(`{"declaration":1,"resources":[
+	  {"id":"fw","type":"container","name":"fw","image":"` + image + `","network":"host","capabilities":["NET_ADMIN","CAP_NET_RAW"]}
+	]}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := d.Resources[0].(*Container).Capabilities; len(got) != 2 || got[0] != "NET_ADMIN" {
+		t.Fatalf("capabilities read as %v", got)
+	}
+	for _, bad := range []string{`"net_admin"`, `"ALL;rm -rf /"`, `"privileged"`} {
+		if _, err := Parse([]byte(`{"declaration":1,"resources":[
+		  {"id":"fw","type":"container","name":"fw","image":"` + image + `","capabilities":[` + bad + `]}]}`)); err == nil {
+			t.Errorf("%s was accepted as a capability", bad)
+		}
+	}
+}
@@ -409,26 +409,3 @@ func TestATokenSaysWhatTheMeshCallsThisMachine(t *testing.T) {
 		t.Fatalf("the name did not survive the token: %q", token.Node)
 	}
 }
-
-// A token through the tunnel carries the one peer, in the field names the control plane writes
-// (novox/hq ADR 0169), and an incomplete tunnel is refused naming what is missing.
-func TestATokenThroughTheTunnelParsesAndAPartOneIsRefused(t *testing.T) {
-	whole := map[string]any{"v": 1, "node": "n", "broker": "10.42.0.1:4222", "fingerprint": "sha256:x",
-		"signer": make([]byte, 32), "secret": "s",
-		"tunnel": map[string]any{"key": "k", "address": "10.42.0.9/32", "range": "10.42.0.0/16",
-			"hub_key": "h", "hub_endpoint": "198.51.100.1:51820"}}
-	raw, _ := json.Marshal(whole)
-	got, err := ParseToken(base64.RawURLEncoding.EncodeToString(raw))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if got.Tunnel == nil || got.Tunnel.HubEndpoint != "198.51.100.1:51820" || got.Tunnel.Range != "10.42.0.0/16" {
-		t.Fatalf("the tunnel was not read: %+v", got.Tunnel)
-	}
-	whole["tunnel"] = map[string]any{"key": "k"}
-	raw, _ = json.Marshal(whole)
-	if _, err := ParseToken(base64.RawURLEncoding.EncodeToString(raw)); err == nil ||
-		!strings.Contains(err.Error(), "the hub's tunnel key") {
-		t.Fatalf("a token with half a tunnel was taken: %v", err)
-	}
-}
@@ -5,8 +5,6 @@ import (
 	"crypto/rand"
 	"encoding/base64"
 	"fmt"
-	"os"
-	"strings"
 )

 // The node's key on the private network, which is a different key from the one that says who it
@@ -66,19 +64,6 @@ func OverlayKeyFrom(privateBase64 string) (OverlayKey, error) {
 	}, nil
 }

-// LoadOverlayKey reads the key `key` made and left in its file (novox/hq ADR 0169).
-func LoadOverlayKey(path string) (OverlayKey, error) {
-	raw, err := os.ReadFile(path)
-	if err != nil {
-		return OverlayKey{}, err
-	}
-	key, err := OverlayKeyFrom(strings.TrimSpace(string(raw)))
-	if err != nil {
-		return OverlayKey{}, fmt.Errorf("%s does not hold a tunnel key: %w", path, err)
-	}
-	return key, nil
-}
-
 // OverlayKeyPath is where the private half lives: a file of its own, referenced by the interface
 // configuration rather than embedded in it.
 //
@@ -35,21 +35,6 @@ type Token struct {
 	// firewall found here before enrolling, because an adopted node keeps that firewall in force.
 	// Absent for a converged node.
 	Adopted bool `json:"adopted,omitempty"`
-
-	// Tunnel is this machine's first tunnel, when the token was issued for the key it made with
-	// `key` (novox/hq ADR 0169): its own address and the hub to reach. It brings the tunnel up from
-	// this alone and reaches the bus over it, so the bus never has to face the internet.
-	Tunnel *TokenTunnel `json:"tunnel,omitempty"`
-}
-
-// TokenTunnel is the joining machine's side of its first tunnel. Field names are the wire format
-// the control plane writes.
-type TokenTunnel struct {
-	Key         string `json:"key"`
-	Address     string `json:"address"`
-	Range       string `json:"range"`
-	HubKey      string `json:"hub_key"`
-	HubEndpoint string `json:"hub_endpoint"`
 }

 // ParseToken reads a token a person pasted.
@@ -85,17 +70,6 @@ func ParseToken(encoded string) (Token, error) {
 	if strings.TrimSpace(t.Secret) == "" {
 		missing = append(missing, "the one-time secret")
 	}
-	if tt := t.Tunnel; tt != nil {
-		for _, part := range []struct{ value, says string }{
-			{tt.Key, "the tunnel key it was issued for"}, {tt.Address, "this machine's address"},
-			{tt.Range, "the private network's range"}, {tt.HubKey, "the hub's tunnel key"},
-			{tt.HubEndpoint, "where the hub's tunnel is dialled"},
-		} {
-			if strings.TrimSpace(part.value) == "" {
-				missing = append(missing, part.says)
-			}
-		}
-	}
 	if len(missing) > 0 {
 		// Refused whole rather than used partially. A token missing the fingerprint would have
 		// this node connect to whatever answers at that address, and one missing the signing key