diff --git a/docs/sidecar-topology.md b/docs/sidecar-topology.md new file mode 100644 index 00000000..3ca6c3f5 --- /dev/null +++ b/docs/sidecar-topology.md @@ -0,0 +1,83 @@ +# Sidecar topology — the target shape + +**Status:** agreed design, 2026-07-30. Nothing built yet. Owner's design; this file is the record. + +Not to be confused with `SIDECAR_ARCHITECTURE.md` at the workspace root, which is the *audit* of the +current state (what's misplaced, and where). This is where it's going. + +## The premise that makes it simple + +**The tailnet is the perimeter.** Everything moves behind Tailscale and devices are admitted by hand — +friends and family included. Authentication *inside* that boundary is solving a problem we don't have, so +this design has no token work in it at all. Sidecars trust their caller exactly as they do today; the trust +boundary just moves from loopback to the tailnet. + +Until that lands, things stay exposed as they are now. The security model is deliberately interim. + +## The design + +1. **`ecosystem.config.cjs` is the source of truth.** PM2 starts every sidecar. They stay *peers* of + `officer` — never children. This is not a style preference: officer used to spawn the agent itself, + which made it a grandchild, and PM2's tree-kill took the owner's chat session down on every restart. + That was the worst thing about working on the platform, and it is fixed. Don't reintroduce it. +2. **Fixed port per sidecar**, declared once in that table. No random ports. +3. **The platform reads the table** instead of being told at runtime. +4. **`.env` enables and disables** features, i.e. sidecars. Absent sidecar = feature 503s cleanly, which is + already how music, slskd and vault behave, so "disabled" is a tested state rather than a new one. +5. **NPM maps `/api/` straight to the sidecar** (`/api/music` → the music sidecar). Added by hand + for now; automating it via the NPM API is the last step, not the first — no point automating a config + that hasn't settled. +6. **The platform keeps auth, and the frontend's own concerns** — dashboards, persisted layouts, routing. + It comes off the data path entirely. + +## What this deletes + +The point of the exercise, and the reason it's worth doing: + +- `sidecar/connect.ts` — the dial-out-and-register loop, plus its per-sidecar reconnect backoff copies +- every port announcement: `music:server`, `slskd:server`, `vault:server`, `opencode:server`, `vnc:started` +- most of `sidecar-registry.ts` — discovery, the pending-command map, capability lookup +- officer's proxying for anything that isn't auth or layout state + +## Migration: music first, end to end + +One sidecar all the way through before touching the other nine. Music because it's the highest-traffic, +the least dangerous if it breaks, it already listens on a port, and it already has an app of its own. + +Keep officer's existing proxy in place as a fallback during the change, so a bad step is a revert rather +than an outage. Vault last — it's off-limits by standing instruction and is the least urgent anyway. + +## Open questions + +- **Ecosystem file, or a shared table?** The platform parsing `ecosystem.config.cjs` couples the app to + PM2 being the thing that started it, which matters for `DOCKERIZATION_PLAN.md` and for `bun dev`. + The alternative is one plain TypeScript table (name, script, port, capability, enabled) that + `ecosystem.config.cjs` generates its `apps:` array from and the platform imports directly — same single + source of truth, no supervisor coupling. **Recommended, not yet decided.** +- **Where do the things that are neither auth nor layout go?** The job/queue engine, the capabilities/items + store, the chat session list, the file browser. Each needs a named home or officer quietly stays fat. +- **Does the registration socket survive?** Not needed for discovery once ports are static. Possibly worth + keeping for liveness — or replace it with a health probe on the known port. +- **Capabilities.** Today a sidecar announces `capabilities: ['music']` and officer looks up by capability, + not by name — which is what let the agent's PM2 name change from `officer-claude` to `officer-agent` + without touching a caller. In a static table it collapses to a column. Keep it; it's cheap. +- **The non-owner account class may become dead weight.** `NON_OWNER_PATHS`, the music-only account + scoping and the super-admin backstop exist because music is public. If friends and family join the + tailnet instead, that whole class — and a chunk of `origin-validation.ts` — can go. + +## Considered and dropped + +Recorded so they aren't re-litigated: + +- **Platform spawns the sidecars.** Rejected — that's the tree-kill bug again. PM2 starts them; the + platform only reads the topology. +- **Platform mints a token, tells every sidecar it's valid, apps then call sidecars directly.** This was + the original points 6–8. Dropped with the tailnet decision. Worth knowing *why* it was weak even on its + own terms: it replicates session state across ten processes, and breaks whenever one restarts, is down + at login, or has to be told about a logout. +- **A dedicated public auth sidecar** issuing short-lived asymmetric tokens, with sidecars verifying via + JWKS. Correct for a public deployment, unnecessary for a private tailnet. If the perimeter ever opens + up again, this is the design to come back to. +- **Origin headers as the security boundary.** They aren't. `Origin: officer://` is client-chosen — + trivially forged outside a browser, and the token is extractable from any shipped app binary. Origin + scoping stays useful as defence in depth; it was never authentication.