| 1 | # Review brief: stage 4a relay spec |
| 2 | |
| 3 | You are GPT-6 reviewing a stage design spec independently of its author. |
| 4 | Your output is a findings report, not an edit. Do not modify any file. |
| 5 | |
| 6 | ## What to read |
| 7 | |
| 8 | 1. The spec under review: |
| 9 | `docs/superpowers/specs/2026-09-07-relay-stun-turn-design.md`. |
| 10 | 2. Its parent, which it must honour: the media roadmap |
| 11 | `docs/superpowers/specs/2026-09-07-media-platform-roadmap-design.md`, |
| 12 | especially §1, §3, stage 4a, §7 rulings 8, 10 and 11, and §9's stage |
| 13 | 4a gate. Rulings are fixed; report a mechanism that fails one, do not |
| 14 | re-argue one. |
| 15 | 3. The code it fits into, in this worktree: `internal/host/bootstrap.go` |
| 16 | and `internal/host/units/carlos-edge.service` (units, hardening, |
| 17 | `enabledUnits`); `internal/host/agent.go` (IMDS reads near line 1761, |
| 18 | fast-converge loop near 1304, config generation loop near 985); |
| 19 | `internal/host/edgesfile.go`; `internal/host/metrics_loop.go`; |
| 20 | `internal/objstore/walk.go` (`writeEnv` near 554) and |
| 21 | `internal/appconfig/` (Apply, generation, sync); `store.go`, |
| 22 | `internal/console/apistore.go`, `internal/console/apicli.go` |
| 23 | (`apiAccountApp`); `internal/release/serial.go`; |
| 24 | `infra/modules/region-host/main.tf`; `go.mod`; `AGENTS.md`. |
| 25 | 4. pion/turn v4's API as documented at pkg.go.dev |
| 26 | (`ServerConfig`, `AuthHandler`, `PermissionHandler`, `QuotaHandler`, |
| 27 | `EventHandler`, `RelayAddressGeneratorPortRange`, `GenerateAuthKey`). |
| 28 | Check the spec's claims about when pion calls the auth handler and |
| 29 | what it does with the returned key. |
| 30 | 5. The suite doctrine ruling 6 and §8 at |
| 31 | `/home/paulca/amadan.net/oficina/suite/docs/superpowers/specs/2026-09-05-suite-sharing-doctrine.md`. |
| 32 | |
| 33 | ## What matters most |
| 34 | |
| 35 | - **The app-facing contract in §2** is what the Meet app will code |
| 36 | against today. Is it complete, unambiguous and implementable from the |
| 37 | text alone? Does the test vector follow from §4 exactly? Is anything |
| 38 | the app needs missing? |
| 39 | - **Verification in §4.** Look for a way to obtain a TURN allocation |
| 40 | without a key an enabled app was given, to use one app's credential |
| 41 | for another, to keep using a credential after disable, or to make the |
| 42 | relay accept something the authority record does not cover. Check the |
| 43 | interaction with pion's long-term credential mechanism. |
| 44 | - **Key custody in §4 and §5.** Masters in `host.env` and as console |
| 45 | secrets, two hand-staged copies. Is the exposure stated honestly and |
| 46 | consistently with roadmap §1's statement that sealed config is |
| 47 | decryptable on every host? Does rotation as written ever leave a |
| 48 | window where a credential stops working or an old master is accepted |
| 49 | too long? |
| 50 | - **The unit in §3.** Hardening, ports, the allocation range, the EIP |
| 51 | as relay address, the certificate for 5349, the authority record and |
| 52 | its fifteen-minute lease. Is anything unbuildable as written on a |
| 53 | `t4g.small` sharing the box with the edge? |
| 54 | - **Limits and metering.** Can one app starve another, exhaust the port |
| 55 | range, or relay to somewhere it should not? Can the meters be |
| 56 | attributed wrongly? |
| 57 | - **Claims about the code.** Every `file:line` and every "already |
| 58 | exists" claim: check it. Report each one that is wrong. |
| 59 | - **Operability.** Can a member, with no box access, enable, see status |
| 60 | and disable? Can an operator rotate a master without a call dropping? |
| 61 | |
| 62 | ## How to report |
| 63 | |
| 64 | Number findings R1-1 onward. For each: severity (P1 breaks a trust |
| 65 | guarantee or makes the stage unbuildable; P2 a contract or claim defect |
| 66 | to fix before the plan; P3 advisory), the section, the problem, the |
| 67 | evidence with citations, a proposed correction. End with a verdict: |
| 68 | accept, accept with corrections, or request changes. Do not soften, do |
| 69 | not pad, do not restate the spec. |
| 70 | |
amadan