FM-944 — ADR and implementation: tailnet identity as the request principal

[Andreas-Froyland]

Epic: #122 · Depends on: FM-943

Context

The maintainer reaches the controller through tailscale serve, which can attach identity headers (e.g. Tailscale-User-Login) to proxied requests. The maintainer approved exploring this as the first step away from anonymous-lan-admin.

Goal

An ADR, then an opt-in mode: when requests arrive from a configured loopback serve proxy with identity headers, the principal is the tailnet user. It feeds the existing authz boundary and audit; otherwise behavior is unchanged.

Architecture reference

ADR-0003/0004; FM-105/FM-S02 (deferred auth); docs/architecture/security.md; PLAN M8.

Dependencies

FM-943

Research required

Tailscale serve identity header documentation; header spoofing risks when not behind serve.

Acceptance criteria

• Headers trusted only from the configured loopback peer; spoofed headers from other peers are ignored and audited as evidence
• Audit records the tailnet principal; UI shows who you are

Non-goals

• Full M8 authentication, OIDC, per-user permissions

Tests

Header-trust unit tests, spoofing tests, audit tests.

[Andreas-Froyland]

FM-944 implementation approach:

• Add an optional, dedicated Tailscale Serve listener separate from the existing direct controller listener. When enabled, both listeners must bind loopback and use distinct addresses; the existing listener remains available for local fleetctl at its default URL. This prevents the anonymous listener from becoming a remote bypass.
• Only the Serve listener may resolve Tailscale-User-Login, and only when the TCP peer is the configured loopback address. Require exactly one bounded, valid login; missing, duplicated, or malformed identity returns 401. Do not infer identity from X-Forwarded-For.
• Keep the existing anonymous-lan-admin behavior when this mode is disabled. With it enabled, requests through the direct local listener remain anonymous admin; the identity listener attributes requests to tailscale:<login>. Tailnet users retain the current full permission set; per-user roles remain out of scope.
• Ignore identity headers from untrusted peers and write a bounded audit observation containing only header names and the trust result, never caller-supplied values. Show the resolved principal in the system UI.
• Document that loopback is a host trust boundary: local processes can spoof headers but already have direct local admin access. The default bridged Compose deployment cannot provide a loopback peer to the container, so startup must reject that configuration with a clear error; the supported Tailscale setup must share the host network namespace with Serve (or use the host binary).

Tailscale documents that Serve removes inbound identity headers before adding its own, that tagged devices receive no user identity headers, and that the backend should listen on localhost: https://tailscale.com/docs/features/tailscale-serve