zero-trust-relay

Deploy (or repair/verify) the zero-trust, end-to-end-encrypted AI relay end to end (serves both OpenAI Codex CLI and Claude Code): Taiwan VPS + sub2api behind a Cloudflare TCP tunnel wrapping mTLS. Use when the user wants to set up, finish, re-run, or verify the relay in this repo. Orchestrates all scripts, pausing only at the unavoidable human gates (VPS, domain+API token, ChatGPT/Claude OAuth, SSH).

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".

Revoke a single client device's access to the relay without affecting the others: remove its --allow-cn from ghostunnel, restart ghostunnel, and re-baseline the health check. Use when the user wants to deauthorize / remove / kick a device, a laptop is lost or compromised, or a rogue --allow-cn was found by the health check.

Diagnose a broken relay connection symptom→cause: client won't connect, browser/login redirect at the edge, TLS "unknown certificate authority", requests hang ~30s then context-canceled, balance/credit block, admin console won't load, or a stuck client. Probes the path layer by layer (local tunnel → CDN Access edge → mTLS → gateway) and applies the known fix. Use when the user says the relay/Claude/Codex "isn't working", "can't connect", "hangs", or "times out".

Open (or close) the gateway admin console — forward the VPS's loopback admin port over your secure SSH path (e.g. Google IAP) to a local port and browse it, or read usage from the CLI without a browser. Handles the recurring "console page won't load" problem (the SSH forward must run in the user's OWN terminal and stay open). Use when the user wants to open the admin UI / dashboard / server UI, log in to the gateway, or check usage and spend.

Pull, read, and act on the relay's daily health + intrusion report (the systemd timer runs the check and auto-remediates the safe subset; this pulls the secret-free report on demand). Triages FAIL/WARN lines, distinguishes auto-remediated drift from ATTENTION-REQUIRED intrusion, and re-baselines after an intentional change. Use when the user asks "is the relay healthy / safe", "check for attacks/intrusion", "pull the health report", or "re-baseline".

Gateway (sub2api) day-to-day operations on the VPS: fix an INSUFFICIENT_BALANCE-style block (raise balance AND clear the cached auth snapshot), check/restore the nightly pg_dump backups, read usage/spend, reset the admin password, and keep the routing rule intact (a key's group platform must match its account platform). Use when the user hits a balance/credit error, asks about backups/restore, billing, or the gateway behaving wrong (misrouted requests, wrong model answering).