relay-add-device

name	relay-add-device
description	Add a new client device to the relay using ADDITIVE TRUST (no CA regeneration, no impact to existing devices): mint the device a client cert with a fresh CN from the shared CLIENT CA (which the VPS already trusts), add --allow-cn for the new CN, restart ghostunnel, fill the device's client bundle, and re-baseline the health check. Use when the user wants to authorize a new laptop/PC/device to use the relay, or "add a client".
allowed-tools	Read, Edit, Write, Bash, Agent, AskUserQuestion, TodoWrite

Add a client device (additive trust)

Read CLAUDE.md and docs/GETTING-STARTED.md first. The relay is client-IP-agnostic (auth = mTLS cert + CDN service token; upstreams only ever see the VPS static IP), so the new device's network adds no ban risk. Additive trust = each device gets its own CN (signed by the shared client CA the VPS already trusts) — so it can be revoked alone and the server cert is never re-keyed (existing devices stay up). Prefer this over full CA regeneration (which breaks everyone). Pick the next free CN (e.g. zt-relay-client-<N>).

Drive it with a TodoWrite list.

Steps

1. On the box holding the client CA (certs/out/client-ca.{key,crt}): mint a client cert with the fresh CN: MSYS_NO_PATHCONV=1 bash certs/gen-client-cert.sh zt-relay-client-<N> <outdir>. This also drops server-ca.crt into the bundle (so the device can verify the server). The client CA key never leaves this box.
2. On the VPS (delegate to the relay-operator agent over your secure SSH path — back up first):
   • Back up the ghostunnel unit (*.bak.<ts>).
   • Add --allow-cn zt-relay-client-<N> to the ghostunnel server unit. No client-ca.crt change — the VPS already trusts the shared client CA that signed the new cert.
   • sudo systemctl daemon-reload && sudo systemctl restart ghostunnel-server; confirm active.
3. Fill the device bundle: copy local/win-client-template/ → the device's own bundle, drop in server-ca.crt, this device's client.{crt,key}, and the .env secrets (CDN service-token id/secret, the relay hostname, the gateway API key). Run setup.ps1, then test the relay client.
4. Re-baseline the health check — a new --allow-cn is otherwise flagged as drift on the next run: bash local/healthcheck-pull.sh --update-baseline.

Verify

• The new device gets a real completion through the relay.
• Existing devices still work (additive path never touched the server cert).
• Next health pull is clean (no unexpected --allow-cn drift).

Guardrails

• Never regenerate the CA to add a device (that re-keys the relay and breaks every device) unless the user explicitly wants the full rotation.
• Never commit or print the device key / .env. Never weaken loopback/TCP-mode/two-gate invariants.
• Each device keeps its own CN — never reuse one CN across machines (can't revoke one alone).