[csdev19]

Refs NIW2-309. Spec: design/control-plane-hardening.md. ADRs: 0014 (control-plane admission), 0015 (share-token disclosure).

Decisions

• The Host allowlist checks the hostname only: loopback names plus --allowed-host. It does not check the port, so SSH and VS Code port forwards keep working.
• A request that carries Origin must send the exact served origin. Requests with no Origin (curl, scripts) are still admitted.
• Writes also need Sec-Fetch-Site, application/json (otherwise 415) and a body of at most 8 MiB (otherwise 413).
• There is no session secret.
• share.token leaves GET /api/status. The panel reveals it through a POST with no-store.
• The panel gets a strict CSP, frame-ancestors 'none', nosniff and a Referrer-Policy.
• The tunnel authenticates before counting quota. Failed auth has its own per-IP bucket, and eviction is O(1).
• SSE allows at most 8 streams, with a 256-frame queue that drops the oldest frame and a 15 s heartbeat.
• The mock app gets an onError handler, emits the request event after the response exists, and serves null-body statuses without a body.
• A reload never exits. A reload with an unchanged fingerprint is a no-op. Tunnel death after startup is reported.

Breaking for users

• curl -d without a JSON content type now gets a 415, so the README examples change.
• Proxies that keep a public Host, such as Codespaces (unverified), need --allowed-host.

Open questions

1. Add --allowed-origin for local dev tools on another port? Recommendation: no.
2. Should allowedHosts be a CLI flag only, or also a config key? Recommendation: flag only.
3. Keep the panel's Reveal/Copy through POST, or show the token in the terminal only? Recommendation: keep the POST.
4. The SSE limits (8 streams, 256-frame queue, 15 s heartbeat) are unmeasured. Accept them?
5. Restart the tunnel automatically once? Recommendation: not in this ticket.
6. Enforce the CSP from day one, or run it Report-Only for one release? Recommendation: enforce.
7. Is a body limit of 8 MiB acceptable?

Status

This PR contains only the design spec and ADR drafts. It is opened as a draft so the design is not lost. The implementation will land on this same branch after the open questions are answered. Everything is "proposed, not implemented".

Part of the 2026-10-12 audit, umbrella NIW2-302. Specs were written by Fable agents against a read-only export of main at ee34302. The ADR numbers (0014–0026) are assigned across all eight audit PRs. decisions/index.md is not edited in these PRs, to avoid eight-way conflicts; add the index rows when each PR is promoted.

🤖 Generated with Claude Code