Embedded Nebula overlay host, off by default

[skeeeon]

Makes the agent a Nebula host on its organization's mesh, opt-in via nebula.enabled. Design record and rejected alternatives in docs/nebula-design.md; user guide in docs/nebula.md.

Why

The platform already manages a Nebula mesh — pb-nebula runs the CA, signs certificates, generates each host's config. What it could not do is make a device adopt the config it just generated. That was a person with curl.

That gap is load-bearing. Nebula has no CRL: revoking a certificate means listing its fingerprint in pki.blocklist in every other host's config, so a revoked device stays on the mesh until each peer re-reads its own config. CA rotation's three-step interlock and certificate renewal rest on the same assumption. This closes all three loops.

The feature is convergence. Connectivity is a side effect.

Nothing was needed platform-side: things.nebula_host already sits beside things.nats_user, and the nebula_hosts rules already carry an explicit branch letting a thing read the host assigned to it.

Commits

1. refactor: — retry the NATS connection instead of refusing to start
2. feat: — the overlay itself
3. docs: — user guide, example configs, Wintun hint

Commit 1 stands alone: the agent treated NATS as a construction-time dependency, so an agent whose NATS lives on the overlay could never start — connect fails, process exits, and the overlay that would have made it succeed never comes up. A deadlock by structure.

Decisions worth reviewing

The apply path is a ladder of outcomes, not a table of config keys. Reload → if the overlay does not come back, restart → if still not, roll back to the cached config. An earlier draft had the agent classify which keys hot-reload; Nebula already does that internally (firewall, lighthouse, hostmap, connection manager and each tun device register their own callbacks), so a table here would drift on every upgrade. The one key that genuinely cannot reload is listen.port, and pb-nebula issues port 0 to anything that is not a lighthouse or relay.

cmd.nebula answers before it acts. sync and restart reply accepted and work asynchronously, because both can interrupt the tunnel the request arrived through — a reply sent afterwards never lands, and the caller sees a timeout on an operation that succeeded. Outcome is read from cmd.health. There is no stop: it would sever the only channel that could deliver start.

Verification waits for a handshake only when the config names a lighthouse to reach. A lighthouse has no peer to hand shake with, and rolling back a good config because peers were offline causes the outage the rollback prevents.

nebula.sync_interval is bounded above (1m–1h), not just below. It is this device's revocation latency.

Two bugs found while building

• A self-deadlock I introduced. The session file now has two writers (creds sync, nebula sync), so platform.Client got a mutex — which deadlocked startup, because EnsureCredentials calls Sync and Go mutexes are not reentrant. Existing platform tests caught it by hanging 600s. Split into a locking wrapper plus syncLocked.
• The Windows example config stopped parsing. Its paths are double-quoted YAML where a lone backslash is an invalid escape. TestExampleConfigsParse now loads all three examples through the real loader.

Costs

	before	after
binary	19.2 MB	30.5 MB
Go floor	1.24	1.26

The Go bump is unavoidable — every Nebula new enough to issue v2 certificates needs ≥1.25, and v1.11 needs 1.26. Pinned to the same version pb-nebula uses so the library generating configs and the one reading them cannot disagree. CI and goreleaser read go-version-file: go.mod and follow on their own.

Testing

internal/nebula is new (16 tests), internal/nats had none before (3 added), plus Nebula config validation and the example-config parse test. All packages pass; go vet clean; cross-compiles for linux/freebsd/windows.

Not covered: bringing Nebula up needs a real TUN device and root, so the reload/restart/rollback ladder is unverified by go test — the unit tests cover the state machine around it. This is called out in the test file and the design doc. A real-host smoke test is wanted before this is relied on.

internal/tasks fails three tests, identically on main — Windows service-manager access and path-allowlist tests, unrelated to this branch.

Not included

wintun.dll is not shipped (third-party binary; documented instead, with the agent naming the path it looked in). IP-forwarding detection was cut — no gateway is deployed yet, and unsafe_networks from the live certificate already identifies a certified gateway. leaf-sync gaining the same feature is step 4, in the platform repo.

🤖 Generated with Claude Code