| 1 | # Review brief: platform GeoIP for apps |
| 2 | |
| 3 | You are GPT-6 reviewing a 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-10-06-platform-geoip-design.md`. |
| 10 | §0's rulings are Paul's and fixed. Report a mechanism that fails one; |
| 11 | do not re-argue one. |
| 12 | 2. The originating request: amadan discussion carlos/platform #241, quoted |
| 13 | in the spec's §1. The nearest-region spec it builds on: |
| 14 | `docs/superpowers/specs/2026-10-01-nearest-region-default-design.md` §6. |
| 15 | 3. The code it fits into, in this worktree: |
| 16 | - `internal/geo/` (`mmdb.go`, `point.go`, `tz.go`), `cmd/console/main.go` |
| 17 | (`openGeoIP`); |
| 18 | - `internal/edge/edge.go` (`ServeHTTP`, the six proxies and their |
| 19 | `Rewrite` functions, `observeAnalytics` defer), `internal/edge/homemap.go` |
| 20 | (`acceptHop`, `setForwarded`, `stripForwardedHeaders`), |
| 21 | `internal/edge/analytics.go` (`clientIP`, `hopVerified`), |
| 22 | `internal/edge/door.go`, `internal/edge/cache.go`, |
| 23 | `internal/edge/certsync.go` (the precedent for mirroring from the bucket), |
| 24 | `internal/edge/purge_header.go`; |
| 25 | - `internal/tunnelclient/`, `internal/host/tunnel_client.go`, |
| 26 | `internal/host/agent.go`, `internal/host/units/carlos-edge.service`; |
| 27 | - `internal/release/store.go` (`Store`), the S3 store; |
| 28 | - `internal/analytics/` (`Day`, `Delta`, `Obs`, flush and merge); |
| 29 | - `internal/console/authcli.go` (`cliRoute`, roles, rate limiting), |
| 30 | `internal/console/alertwatch.go`, `system.go` (the `carlos system |
| 31 | antivirus` verbs as the precedent for operator verbs); |
| 32 | - `AGENTS.md`. |
| 33 | |
| 34 | ## What matters most |
| 35 | |
| 36 | - **Forgery.** Find any path by which a client-chosen value reaches an app |
| 37 | in an `X-Carlos-Geo-*` header: any proxy, hop, tunnel, door, upgrade or |
| 38 | cache path the strip in §8 misses, or a way to get `tunnelKey` onto a |
| 39 | request that did not arrive over the tunnel. |
| 40 | - **Wrong location.** Any path where the edge locates the wrong address |
| 41 | (the box itself, the hub, a sender edge, a proxy) and sets headers that |
| 42 | look authoritative. |
| 43 | - **The hot swap (§5.3).** Can a lookup ever run against a closed mapping? |
| 44 | Any deadlock or starvation under load? |
| 45 | - **The mirror and publish protocol (§3–§5).** Races between publishers, |
| 46 | between a publish and an edge poll, a deleted blob, a partially written |
| 47 | file, disk filling, a box restarting mid-swap, the console box reading a |
| 48 | file the edge is replacing. |
| 49 | - **The feed (§10).** Supply-chain risks in fetching and publishing a file |
| 50 | every edge maps into memory; decompression limits; the monotonic rule; |
| 51 | credential handling; behaviour when DB-IP or MaxMind change URLs. |
| 52 | - **Cache interaction (§7, §8.2).** Does setting headers before the cache |
| 53 | lookup interact correctly with `Vary`, the 8-variant limit and purge? |
| 54 | - **Licensing (§13).** Is anything stated wrongly about DB-IP Lite's |
| 55 | CC BY 4.0 terms or MaxMind's GeoLite2 EULA? |
| 56 | - **Claims about the code.** Every `file:line` and every "already exists" |
| 57 | claim: check it. Report each one that is wrong. |
| 58 | - **Completeness for planning.** Anything an implementer would have to |
| 59 | invent because the spec is silent. |
| 60 | |
| 61 | ## Output |
| 62 | |
| 63 | A numbered list of findings, most severe first, each with: severity |
| 64 | (P1 = wrong or unsafe as written, P2 = gap an implementer would get wrong, |
| 65 | P3 = clarity), the spec section, the code evidence with file:line, and a |
| 66 | concrete fix. End with a one-line verdict: accept, or revise. |
| 67 | |
| 68 | ## Later rounds |
| 69 | |
| 70 | For round N > 1, first give a disposition table for every finding of the |
| 71 | previous round (`CODEX-FINDINGS-GEOIP-R<N-1>.md`): resolved, partly |
| 72 | resolved, or not resolved, with one line of evidence from the revised |
| 73 | spec. Then report only NEW findings, numbered from 1. Decisions marked D |
| 74 | in §0 are open to challenge on mechanism, not on whether to exist; R |
| 75 | rulings are fixed. |
| 76 | |
amadan