[jayleaton]

One owner's T3 servers on a tailnet still needed a pairing code each way. Now they find each other and link both ways, and nobody can talk a server into handing over a token.

How a link is proven

R ──request{challenge}──▶ I     I resolves R's address itself (tailnet IP, or https MagicDNS name)
                               I whoises it: same user, untagged, [t3.codes/device]
                               I fetches R's descriptor: environmentId matches
I ──confirm{challenge}──▶ R     R: "pending, for you"   ← a forged request dies here; nothing minted
I ──grant{token}────────▶ R     token only goes to the address I proved
I ──request (link back)─▶ R     before answering R, so one request = mutual link

No Tailscale-User-* header or source address is trusted. Requests arriving through Serve come from loopback, so neither tells you anything.

What's in it

• peer/TailnetDevices.ts: the handshake on both sides, the scan, gossip and refresh.
  • The scan probes online same-user peers at startup, when the tailnet changes and every 10 min, with at most 4 probes at once and a 2.5 s timeout each.
  • Gossip exchanges device hints with linked devices. A hint still goes through the full handshake.
  • Tailnet links renew a week before expiry. A 401 triggers a re-handshake and one retry (PeerMcpClient).
• peer/TailnetIdentity.ts: the seam over Doug A's readTailnet and whoisTailnetAddress. locateTailnetTarget never maps plain-http names, LAN or public addresses.
• Fork migration 012_TailnetDevices: auth_sessions.peer_environment_id, peer_environment_links.origin, and the tailnet_devices and tailnet_device_settings tables. Every incoming peer session, including pairing-code ones, now records the caller's environmentId.
• t3_environment_link links one of my tailnet devices directly. Other targets still get the card. assertNotLinked is unchanged.
• tailnetDevices.list and tailnetDevices.updateSettings are served. setAccess lands in the next PR and openDevice in the one after.
• Tailscale Serve defaults on, tailnet only and never Funnel, for the server CLI and the desktop setting. Dev servers are excluded.
• docs/internals/remote.md: a short trust-model section.

Proof (TailnetDevices.test.ts, real HTTP servers per device and a stubbed tailnet)

• One request yields a mutual link. Each side's session is labelled with the other's environmentId.
• Refused with no grant delivered and no session minted:
  • same user but tagged
  • another user
  • a non-tailnet URL
  • a forged request naming a real device's URL
  • a descriptor environmentId mismatch
• requireCapability filters nodes. Auto-link off refuses.
• Gossip: A links C, which only B knew, after one scan.
• locateTailnetTarget table: MagicDNS (https only), v4 and v6 tailnet IPs, and rejects for everything else.
• PeerLinks.test: pairing-code links still work, and now record the caller's environmentId.
• PeerLinkRequests.test: a tailnet device links directly with no card.

Merge risk: medium.

• Serve now publishes by default on the tailnet.
• Unauthenticated /api/tailnet-devices/request makes this server dial out. It's bounded to 4 concurrent handshakes, 8 URLs per request and short timeouts.
• ForkMigrations.test > keeps upstream's migration ids fails locally only because this machine's upstream/main ref is stale. CI fetches it fresh.

Checks: vp run check:changed feat/mesh-contracts-pr2 passes: format, lint, knip, typecheck of 33 packages, and 12 test files. Peer, auth, MCP, WS, persistence and desktop settings suites pass locally.

Stacked on #168.

🤖 Generated with Claude Code · Claude Opus 5.5 in T3 Code

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ No successful main baseline artifact is available yet. This run establishes the initial measurement.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	—	5.0 KiB	—	6.8 KiB	✅
Codex	Thread snapshot wire	—	3.8 KiB	—	4.9 KiB	✅
Codex	Live turn WebSocket wire	—	1.2 KiB	—	2.0 KiB	✅
Codex	Live turn WebSocket decoded	—	21.6 KiB	—	24.4 KiB	✅
Codex	Live turn messages	—	2	—	8	✅
Claude	Total thread wire	—	5.0 KiB	—	6.8 KiB	✅
Claude	Thread snapshot wire	—	3.8 KiB	—	4.9 KiB	✅
Claude	Live turn WebSocket wire	—	1.3 KiB	—	2.0 KiB	✅
Claude	Live turn WebSocket decoded	—	21.9 KiB	—	24.4 KiB	✅
Claude	Live turn messages	—	2	—	8	✅

Baseline: unavailable · PR result: ffa2fad · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.