From 6b0916f1fa64b619312313b8249da458cd066617 Mon Sep 17 00:00:00 2001 From: Egutierrez Date: Sun, 7 Jun 2026 12:49:19 +0200 Subject: [PATCH] docs(0001e): note remaining gateway and unibots migration The web gateway (playground) and unibots (in the agents repo) are not migrated here: the gateway stays a local dev tool at AuthOff, and the bot transport lives outside this sub-repo. dev/0001e-remaining-clients.md records exactly what each needs (client.Connect with ca.crt, identity registered in the allowlist) and the operator server flags for phase 0001f. Co-Authored-By: Claude Opus 4.8 (1M context) --- dev/0001e-remaining-clients.md | 55 ++++++++++++++++++++++++++++++++++ playground/server.go | 3 +- 2 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 dev/0001e-remaining-clients.md diff --git a/dev/0001e-remaining-clients.md b/dev/0001e-remaining-clients.md new file mode 100644 index 00000000..6c0e488c --- /dev/null +++ b/dev/0001e-remaining-clients.md @@ -0,0 +1,55 @@ +# Issue 0001e — remaining client migrations (notes, NOT implemented) + +Phase 0001e migrated the first-class Go clients and the mobile binding to the +secure connection path (`client.Connect(caPath)` → TLS + nkey; control-plane +requests are always signed). Two consumers are intentionally **left as notes** +because they live outside this sub-repo or need their own coordination: + +## 1. Web gateway (`playground/server.go`) + +The playground is a local dev gateway that embeds its own membershipd +(`membership.NewServer(..., AuthOff)`) and an open embedded NATS, and connects +browser sessions through an in-process client. To run it against a **secured** +bus it would need: + +- Connect its internal client via `client.Connect(natsURL, ctrlURL, id, caPath)` + with the bundled `ca.crt` (it currently builds the client without options). +- If it should itself enforce auth on the browser-facing side, start its + embedded membershipd with an auth mode and its embedded NATS with + `embeddednats.StartServer(ServerConfig{Auth: ..., TLS: ...})` — but a local + dev gateway typically stays open and only the *upstream* bus is secured. +- The gateway's own bus identity must be registered in the upstream allowlist + (`membershipd user add`). + +Decision: left at `AuthOff` + plaintext for now (local dev tool). Migrate when +the gateway is pointed at the public bus. + +## 2. unibots (`shell/transportunibus`, in the agents repo — NOT this sub-repo) + +The bot transport lives in the `agents_and_robots` / message_bus consumer, not +in `dataforge/unibus`. To talk to the secured bus it must, after recompiling +against this `pkg/client`: + +- Switch its connect call to `client.Connect(natsURL, ctrlURL, id, caPath)`, + passing the path to the bundled `ca.crt`. +- Ship `ca.crt` alongside the bot binary (read-only) and point `caPath` at it. +- Register each bot's identity (`hex(SignPub)`) in the bus allowlist via + `membershipd user add --handle --sign-pub ` on the bus host. +- Run as `systemd --user` with `caPath` set, per the deploy plan (0001f). + +No code change is possible from this sub-repo; this is the contract the bot +transport consumes. + +## Server enablement (operator, phase 0001f) + +`membershipd` now accepts: + +- `--bus-auth enforce` — verify signed control-plane requests AND turn on the + NATS nkey authenticator (only allowlisted identities connect). +- `--tls-cert deploy/tls/server.crt --tls-key deploy/tls/server.key` — present + the server certificate and require TLS on the embedded NATS. + +`dev/feature_flags.json` now declares both `bus-auth: enforce` and +`bus-tls: enabled` as the project's target state. The flags are declarative; +the operator activates them at deploy time with the flags above. The CLI +defaults remain off so local dev and the test suite are unaffected. diff --git a/playground/server.go b/playground/server.go index 0e44a5d7..b93a409e 100644 --- a/playground/server.go +++ b/playground/server.go @@ -861,7 +861,8 @@ func main() { log.Fatalf("open blob store: %v", err) } // AuthOff: the playground is a local dev gateway that has not migrated to - // signed control-plane requests yet (tracked in phase 0001e of issue 0001). + // signed control-plane requests or a secured upstream bus yet. What it would + // need is written up in dev/0001e-remaining-clients.md (issue 0001, phase 0001e). ctrlSrv := &http.Server{Addr: ctrlAddr, Handler: membership.NewServer(store, blobs, membership.AuthOff)} go func() { if err := ctrlSrv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {