Gate the archie binary's operational services on completed owner setup #2081

Closed
opened 2026-11-20 16:19:37 +00:00 by sam · 2 comments
Owner

Why: on a fresh install the dashboard hides its normal UI until an owner account exists, but the single archie binary starts operational services without checking setup at all. The bootstrap admin token is accepted independently of owner setup, so pre-setup requests reach operational endpoints (for example GET /api/system/bootstrap). A fresh instance should run nothing operational until the owner setup transaction commits.

Today: internal/app/archie/run.go starts accepted connectors (conns.Start), registers every module's API routes plus the dashboard (apiModules{...}.register(api), dashboard.Routes), installs the starter workflow (useWorkflows), and starts the run, event, delivery and chat workers (serveWithWork with engine.Work, hear.Work, tell.Work, talk.Work) with no setup check. Module.AccountSetupRequired (modules/governance/store_identities.go) exists and the auth-status endpoint uses it (internal/webui/accounts.go) to show the setup page, but the composition root never consults it. The bootstrap admin token authenticates via settings.Authenticator(cfg.AdminTokenSHA256) whether or not an owner exists.

Required behaviour:

  1. Before setup completes, the binary serves only the setup UI and its assets, the setup/status endpoints, and liveness.
  2. Operational readiness stays false and connectors and workers do not start until setup commits.
  3. Operational API and webhook requests are rejected without executing, even with valid credentials including the bootstrap admin token; only the setup endpoints answer.
  4. The gate flips once, when the owner setup transaction commits (RegisterAccount's advisory-lock transaction in modules/governance), and a restart recognises completed setup from durable state (AccountSetupRequired) and starts normally.
  5. A failed setup attempt leaves the gate closed.

Design notes: the gate belongs in the composition root (internal/app/archie/run.go): after opening the DB, read AccountSetupRequired; while it is true, register only health, setup and dashboard static routes, skip conns.Start, module route registration, starter workflow install and the worker loops. Flip once on the setup commit (signal from the setup handler) or re-read per request until it flips; either is fine, but make the gate a small pure function of the setup-required flag so it is testable without booting the binary. Webhook intake (events module routes) is inside the gated set. Liveness stays up: missing setup is not a crash (report not-ready, never exit).

Tests (table cases, fakes, no DB): a pre-setup mux serves setup endpoints and rejects operational API and webhook paths even with the admin token; the same mux post-setup serves them; a failed setup keeps the gate closed; a fresh composition over the same durable state (simulated restart) starts normally.

Done when: task check passes with the new tests; manually on a fresh database: only setup UI/status/liveness answer, readiness reports not-ready, operational API calls 404 with the admin token; completing setup starts services exactly once; a restart starts immediately; a failed setup stays gated.

Out of scope: the setup form itself (#2076), the chat authorisation epic (#2066), chat image/CSP (#2073, closed).

Open questions for the maintainer: per-request re-read vs one-shot flip on the setup commit hook; exact health-endpoint semantics while gated (liveness up, readiness not-ready).

**Why**: on a fresh install the dashboard hides its normal UI until an owner account exists, but the single `archie` binary starts operational services without checking setup at all. The bootstrap admin token is accepted independently of owner setup, so pre-setup requests reach operational endpoints (for example `GET /api/system/bootstrap`). A fresh instance should run nothing operational until the owner setup transaction commits. **Today**: `internal/app/archie/run.go` starts accepted connectors (`conns.Start`), registers every module's API routes plus the dashboard (`apiModules{...}.register(api)`, `dashboard.Routes`), installs the starter workflow (`useWorkflows`), and starts the run, event, delivery and chat workers (`serveWithWork` with `engine.Work, hear.Work, tell.Work, talk.Work`) with no setup check. `Module.AccountSetupRequired` (modules/governance/store_identities.go) exists and the auth-status endpoint uses it (internal/webui/accounts.go) to show the setup page, but the composition root never consults it. The bootstrap admin token authenticates via `settings.Authenticator(cfg.AdminTokenSHA256)` whether or not an owner exists. **Required behaviour**: 1. Before setup completes, the binary serves only the setup UI and its assets, the setup/status endpoints, and liveness. 2. Operational readiness stays false and connectors and workers do not start until setup commits. 3. Operational API and webhook requests are rejected without executing, even with valid credentials including the bootstrap admin token; only the setup endpoints answer. 4. The gate flips once, when the owner setup transaction commits (`RegisterAccount`'s advisory-lock transaction in modules/governance), and a restart recognises completed setup from durable state (`AccountSetupRequired`) and starts normally. 5. A failed setup attempt leaves the gate closed. **Design notes**: the gate belongs in the composition root (internal/app/archie/run.go): after opening the DB, read `AccountSetupRequired`; while it is true, register only health, setup and dashboard static routes, skip `conns.Start`, module route registration, starter workflow install and the worker loops. Flip once on the setup commit (signal from the setup handler) or re-read per request until it flips; either is fine, but make the gate a small pure function of the setup-required flag so it is testable without booting the binary. Webhook intake (events module routes) is inside the gated set. Liveness stays up: missing setup is not a crash (report not-ready, never exit). **Tests** (table cases, fakes, no DB): a pre-setup mux serves setup endpoints and rejects operational API and webhook paths even with the admin token; the same mux post-setup serves them; a failed setup keeps the gate closed; a fresh composition over the same durable state (simulated restart) starts normally. **Done when**: `task check` passes with the new tests; manually on a fresh database: only setup UI/status/liveness answer, readiness reports not-ready, operational API calls 404 with the admin token; completing setup starts services exactly once; a restart starts immediately; a failed setup stays gated. **Out of scope**: the setup form itself (#2076), the chat authorisation epic (#2066), chat image/CSP (#2073, closed). **Open questions for the maintainer**: per-request re-read vs one-shot flip on the setup commit hook; exact health-endpoint semantics while gated (liveness up, readiness not-ready).
sam added the bughigh labels 2026-11-20 16:19:45 +00:00
Author
Owner

Answering the open question (commit hook vs per-request re-read): there is no hook today. The setup path is POST /api/auth/setup -> setUpAccount (modules/governance/accounts_api.go) -> RegisterAccount(bootstrap=true) -> store.RegisterAccount, which runs under pg_advisory_xact_lock(setupAdvisoryLock) in a transaction (modules/governance/internal/store/accounts.go). Nothing fires on commit; AccountSetupRequired is only read by the auth-status endpoint.

Recommendation: add a one-shot signal to the governance API package (atomic.Bool + closed channel, or OnSetupComplete(func())) and close it in the bootstrap path of RegisterAccount only after store.RegisterAccount returns nil, i.e. after the owner setup transaction committed. run.go then: reads AccountSetupRequired at boot (covers restart); while required, serves the gated mux (middleware allowlists setup UI/assets, /api/auth/setup, /api/auth/status, health; all else 404s even with the admin token) and starts neither connectors nor the run/event/delivery/chat workers; on the signal, flips the atomic and starts them once. Failed setup rolls back, no signal, gate stays closed.

Per-request re-reads need no new plumbing but still need a poll loop to start workers and pay a DB read per gated request; the hook is exact about "after the commit" and starts workers immediately. Going with the hook.

Answering the open question (commit hook vs per-request re-read): there is no hook today. The setup path is POST /api/auth/setup -> setUpAccount (modules/governance/accounts_api.go) -> RegisterAccount(bootstrap=true) -> store.RegisterAccount, which runs under pg_advisory_xact_lock(setupAdvisoryLock) in a transaction (modules/governance/internal/store/accounts.go). Nothing fires on commit; AccountSetupRequired is only read by the auth-status endpoint. Recommendation: add a one-shot signal to the governance API package (atomic.Bool + closed channel, or OnSetupComplete(func())) and close it in the bootstrap path of RegisterAccount only after store.RegisterAccount returns nil, i.e. after the owner setup transaction committed. run.go then: reads AccountSetupRequired at boot (covers restart); while required, serves the gated mux (middleware allowlists setup UI/assets, /api/auth/setup, /api/auth/status, health; all else 404s even with the admin token) and starts neither connectors nor the run/event/delivery/chat workers; on the signal, flips the atomic and starts them once. Failed setup rolls back, no signal, gate stays closed. Per-request re-reads need no new plumbing but still need a poll loop to start workers and pay a DB read per gated request; the hook is exact about "after the commit" and starts workers immediately. Going with the hook.
Author
Owner

Fixed in ae3bbc6cf and 81bca2251. The governance module signals once the owner setup transaction has committed. Until then the composition root serves only setup, status and liveness, readiness reports the missing owner, and connectors, operational routes and worker loops do not start, even for the bootstrap admin token. A restart reads the durable setup state, and a failed setup leaves the gate closed. internal/app/archie/gate_test.go covers these cases with fakes. task check passed on today's merged tree.

Fixed in ae3bbc6cf and 81bca2251. The governance module signals once the owner setup transaction has committed. Until then the composition root serves only setup, status and liveness, readiness reports the missing owner, and connectors, operational routes and worker loops do not start, even for the bootstrap admin token. A restart reads the durable setup state, and a failed setup leaves the gate closed. `internal/app/archie/gate_test.go` covers these cases with fakes. `task check` passed on today's merged tree.
sam closed this issue 2026-11-21 03:51:37 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#2081