@bongos/core 1.19.1081 → 1.20.2

package/docs/adr/0349-a-version-preview-is-a-sandboxed-child-the-web-tier-launches.md

@@ -0,0 +1,106 @@
+# ADR 0349 — A version preview is a sandboxed child the web tier launches, reached by a cookie
+
+- **Status:** accepted
+- **Date:** 2026-09-29
+- **Task:** [task 1004300](https://cloudbongos.com/builders#/task/1004300) (goal 1000090 — BONGOS-V2); split out of [task 1002622](https://cloudbongos.com/builders#/task/1002622)
+- **Deciders:** Lars (owner, Archon) approved both decisions below on 2026-09-29, in chat with the orchestrator: "Yes to cookie routing and web tier, build 1004300." Claude wrote the record.
+- **Amends:** [ADR 0293](0293-the-owners-deploy-door-is-an-intent-the-control-plane-drains.md) D1, for this one feature only.
+- **Related:** [ADR 0016](0016-trust-boundary-server-enforced-permissions.md) (authority is resolved per request) · [ADR 0043](0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md) (the control plane is a separate privilege domain) · [ADR 0151](0151-governance-permissions-as-atom-ranks-as-roles.md) (`requirePermission`) · [`docs/modules-contract.md`](../modules-contract.md) (the `request.divert` seam)
+
+## Context
+
+The owner asked for the version history on `/deploy` to open the hall **as it was at that
+version**, with a banner saying which version it is. A release-notes page was rejected: the
+point is to see, and to run a version's migrations against real data before that version goes
+live. So a preview is a second Bongos process, running an installed copy of that core against
+a copy of the live database.
+
+Two questions had no safe default.
+
+**How does a browser reach it?** The hall's pages call absolute `/api/bongos/...` URLs about
+133 times across `modules/*/public`, and the hall is routed on the Host header
+(`src/bongos/serve-internal.js`, `isBuildersHost`). Serving a preview under a `/preview/<v>/`
+path would break both. A second origin would need its own GitHub OAuth app, an owner step.
+
+**Who launches it?** ADR 0293 D1 keeps the web tier shell-less: it asks, and the control-plane
+runner acts. That fits a privileged act like moving a pin. A preview is unprivileged by
+design, and routing every start and stop through the intent queue would add a timer's latency
+to something a person is waiting on.
+
+## Decision
+
+### D1 — Route by cookie, through an optional `request.divert` seam (owner)
+
+`GET /api/bongos/npm-release/preview/enter?v=X` sets `bongos_preview=X` (HttpOnly, SameSite=Lax,
+Path=/). A kernel middleware, mounted before any surface, asks an **optional** provider of the
+`request.divert` seam whether to take the request. With no provider it is one map lookup and
+`next()`: an instance without the npm-release module is served exactly as before. A provider
+that throws is treated as absent for that request.
+
+The npm-release provider forwards a request to the preview only when **all** hold:
+
+- the cookie names the version now running;
+- the path is not sign-in (`/api/bongos/auth/*`) and not the module's own preview routes, so
+  signing in and **leaving** a preview always reach the live hall;
+- there is no `Authorization` header (a CLI or API call is never a preview);
+- the caller is signed in and holds `core.pin.move`, resolved by the kernel's own
+  `requireBuilder` and `requirePermission` gates on **every** forwarded request, uncached
+  (ADR 0016). A refusal clears the cookie and serves the live hall.
+
+The proxy keeps the Host header, passes server-sent-events streams through unbuffered, strips
+the steering cookie from what the preview sees, and injects the banner after `<body>` on HTML
+responses, so a version older than any banner code still shows it.
+
+The session cookie is forwarded: the preview's database is a copy, so the same session rows
+exist in it and no second sign-in is needed. Anything done there stays in the copy.
+
+**Rejected:** a `/preview/<v>/` path (breaks 133 absolute URLs and Host routing); a second
+origin (an OAuth app per preview host, and cookies that no longer carry).
+
+### D2 — The web tier launches the preview, as a sandboxed child (owner; amends ADR 0293 D1)
+
+The npm-release module's supervisor installs the version, copies the database, migrates the
+copy and spawns the child itself. This is the exception ADR 0293 D1 refuses for the deploy
+door, granted here because a preview is not the deploy door: it changes nothing live.
+
+What keeps that exception narrow:
+
+- **The child's environment is built from nothing.** An allow-list of `PATH`, `NODE_ENV`,
+  `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, plus its own `PORT`/`HOST` on 127.0.0.1. `HOME`
+  is an empty scratch directory, so the Discord webhook file is not found. Every `GITHUB_*`,
+  `DISCORD_*` and AI key is absent because nothing carries it, not because it was removed.
+  `CHAT_DRY_RUN=1`; nine pollers off (`PUBLISH_RECONCILER_DISABLED`, `ROUTINE_TIMERS_DISABLED`,
+  `BOARD_EXPIRY_DISABLED`, `SEARCH_INDEX_SWEEP_DISABLED`, `SESSION_UPLOAD_HEALTH_DISABLED`,
+  `SESSION_REWARD_RECONCILE_DISABLED`, `PROVISIONING_LIVENESS_DISABLED`,
+  `PROVISIONING_CATALOG_BACKFILL_DISABLED`, `CONFLICT_RESOLVE_DISABLED`); modules `discord`,
+  `agents`, `provisioning` and `npm-release` off.
+- **The copy is a dump and a restore, never a template copy.** `pg_dump -Fc` then `pg_restore
+  --no-owner` into `bongos_preview`. A template copy needs no other connection on the source,
+  and the live pool holds some. `PGDATABASE` is pinned to the copy and `DATABASE_URL` blanked
+  for the migration, so nothing can be applied to the live database.
+- **Commands run without a shell.** A version is `^\d+\.\d+\.\d+$` before it reaches any
+  command line.
+- **One preview at a time; 20 minutes idle stops it** and drops the copy.
+- **Only published versions**, no older than the running version minus 30 published versions.
+- **Nothing here holds a control-plane credential.** The web tier already cannot read
+  `/etc/cloudbongos/box.env` (ADR 0327 §5); the child gets less than the web tier has.
+
+### D3 — Accepted residual risks, for now
+
+- The child connects to Postgres as the same role as the live hall (`PGUSER`), so a hostile
+  published core could open the live database. It is our own published package, built from
+  this repository by CI, and a preview is limited to `core.pin.move` holders; a per-preview
+  database role is the next step, not built here.
+- **No egress firewall yet** (owner default). The env allow-list means the child holds no
+  outward credentials; it can still make anonymous outbound requests. `systemd-run
+  IPAddressDeny` is the follow-up and needs the droplet.
+- A preview started by the live process is stopped when that process exits, but the copy is
+  dropped only by the next start or stop. It is one fixed name, so it cannot pile up.
+
+## Consequences
+
+- One new optional seam, `request.divert`, listed in `docs/modules-contract.md`.
+- No migration. No schema. The provider is registered only where npm-release is on.
+- **Part B is unverified until run on the droplet:** the `lars` role has CREATEDB, the unit's
+  `MemoryMax` fits a second Node process plus a restore, the dump time, one preview end to end,
+  and live row counts before and after. Until then the code is implemented, not verified.

package/docs/adr/0350-the-hub-holds-a-per-project-write-deploy-key-so-a-hosted-upgrade-reaches-github.md

@@ -0,0 +1,103 @@
+# ADR 0350 — The hub holds a per-project WRITE deploy key, so a hosted project's upgraded pin always reaches its GitHub repo
+
+- **Status:** accepted
+- **Date:** 2026-09-29
+- **Task:** [task 1004291](https://cloudbongos.com/builders#/task/1004291) (follow-up to task 1004065)
+- **Deciders:** the owner chose this option on 2026-09-25 (a per-project write key, over keeping the owner's GitHub access longer, or leaving it as is); the shared-account default below was stated in the task and is the safe default, not a new ruling; Claude wrote the record.
+- **Amends:** [ADR 0176](0176-private-repo-deploy-keys.md) (which said the deploy key is read-only and that pushes ride the owner's token) · **Related:** [ADR 0281](0281-an-instance-identity-is-its-own-unix-account-and-pg-role.md) (a project's own account and database) · [ADR 0155](0155-adopt-private-repo-widen-oauth-scope.md) (the owner's token)
+
+## Context
+
+When a hosted project's core is upgraded, the pin is committed in the project's checkout and
+the hub's runner pushes it to the owner's GitHub repo (task 1004065, `pushUpgradePin`). That
+push needs a credential that can WRITE. There were two, and neither lasts:
+
+- the owner's token is stored for one hour after they sign in with repository access
+  (`GITHUB_TOKEN_TTL_MS`), and the scaffold path deletes it after use, so an upgrade days later
+  normally finds none;
+- the checkout's own `origin` is the read-only pull key of ADR 0176 (or the shared alias key),
+  which cannot write the owner's repo.
+
+So most upgrades still ended "GitHub was not updated". The box and the repo split, and the
+box's local commit stopped its fast-forward pull from taking the owner's new work (the
+hermeslines-marketing shape).
+
+## Decision
+
+**D1. A second deploy key per hosted repo, registered writable.** Minted with
+`ssh-keygen -t ed25519`, registered with `read_only: false` under its own title
+`cloudbongos-pin-<slug>`, distinct from the ADR 0176 pull key `cloudbongos-deploy-<slug>`. The pull key
+stays exactly as it was and stays read-only. Registering a deploy key needs repository admin
+for the owner, the same requirement the pull key already has. Public repos get one too (they
+have no per-repo key today).
+
+**D2. Where it lives and who can read it.** Outside every project checkout, in a directory of
+the runner's own account: `PROVISION_PIN_KEY_DIR`, default `~/.config/cloudbongos/pin-keys/`,
+directory mode 0700, key mode 0600, born under `umask 077`, and the modes are read back and
+the key deleted if they are not exactly 700/600. It is never written into the project's
+`.git`, its unix home (`/var/lib/bongos-<slug>`) or anywhere the project's account
+(ADR 0281) can read.
+
+**D3. When it is minted.** At standup (scaffold and adopt), right after the ADR 0176 wiring, and
+on any later pass that holds a fresh owner token and finds no key: `pushUpgradePin` mints it
+before pushing. So an existing project needs the owner to reconnect GitHub with repository
+access once; the next upgrade then sets up lasting access. Minting is best effort and never
+fails a standup or an upgrade.
+
+**D4. How it is used.** `pushUpgradePin` tries, in order: the write key, then the owner's token
+(when fresh), then the checkout's own `origin`. The write key is passed for that one push only
+(`-c core.sshCommand="ssh -F /dev/null -i <key> -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new"`
+against `git@github.com:<owner>/<repo>.git`), with hooks off, no prompt, never forced. A push the
+key made that GitHub rejects as non-fast-forward is reported as "behind" and nothing else is
+tried, because the credential worked and the history is what stopped it.
+
+**D5. Revoked when the project leaves.** Teardown, and therefore disconnect (which runs the
+teardown first), deletes the `cloudbongos-pin-<slug>` registration by title next to the pull
+key's, and removes the local key whatever else happened. With no usable owner token the
+registration cannot be removed by us; the log names it so the owner can remove it in their repo
+settings.
+
+**D6. A project with no account of its own is refused a key (the recorded default).** A project
+still running as the shared app user (the `resolveRunAs` fallback, no `bongos-<slug>`
+account) has the SAME uid as the runner and could read the runner's key, so no write key is
+minted for it, and the deploy page reports "needs its own account first" (repo note code
+`needs_account`) instead of offering a reconnect that could not help. The check is fail-closed:
+only a positive `id -u bongos-<slug>` counts; an inconclusive probe refuses. If the owner wants a
+shared-uid project to hold a write key anyway, that is a new decision recorded here, not a
+silent one.
+
+**D7. The deploy page.** The `no_access` note and the reconnect link now say that reconnecting
+sets up lasting access, no longer "about an hour".
+
+## What a compromise can and cannot do
+
+- **The runner account** (the hub's app user) already holds the database, the owner tokens and the
+  process manager, so it can already do everything the write key can. The key adds, for that
+  one account, the ability to push to each hosted owner repo without a live token — one repo per
+  key, revocable individually from the owner's repo settings.
+- **A project's own process** (its `bongos-<slug>` account, ADR 0281) can read the read-only pull
+  key, exactly as before, and can NOT read the write key: wrong owner, directory 0700. It
+  therefore cannot push code into the owner's repo, which is the point of keeping the key
+  outside the checkout. A project on the shared account can, which is why D6 refuses it a key.
+- **GitHub or the network** learn only the public half. A leaked write key can push to that one
+  repository until the owner deletes it in their settings; it cannot read other repos, and it
+  is a per-repo deploy key, not an account token.
+
+## Alternatives rejected
+
+- **Keep the owner's token longer.** A long-lived account-wide token in the hub is a bigger
+  prize than a per-repo key, and it still lapses when the owner revokes the OAuth grant.
+- **Leave it as is.** Most upgrades keep ending in a split that blocks the owner's own pushes.
+- **Make the pull key writable.** It lives in the checkout, readable by the project's own
+  account, so a compromised project could push code to the owner's repo.
+
+## Consequences
+
+- Existing projects get the key on the next runner pass after the owner reconnects GitHub with
+  repository access; until then the deploy page still reports "GitHub was not updated" with the
+  corrected copy.
+- Reconciling an already-split repo (hermeslines-marketing) and auto-rebasing a pin onto newer
+  GitHub commits stay out of scope; both are still reported, not resolved.
+- Code: `scripts/gds/provision-pin-key.js`, `pushUpgradePin` in
+  `scripts/gds/provision-core-upgrade.js`, the revoke in `scripts/gds/provision-teardown.js`,
+  the copy in `modules/hall-ui/public/deploy.js`; tests in `tests/pin_write_key.mjs`.

package/docs/adr/README.md

@@ -439,3 +439,6 @@ This keeps the decision history honest and traceable.
 | 0345 | [**We host every project's hall, and its app deploys where the owner chooses** ([task 1004349](https://cloudbongos.com/builders#/task/1004349), goal 1000106 — working area 1, owner Lars). Reverses ADR 0323 §2 and the hall half of ADR 0327. **D1 (owner):** every project's Builders Hall runs on our shared server; `cloud-host` now means "hosted by us". **D2 (owner):** the hall's address is ours or the owner's own domain. **D3 (owner):** the setup wizard asks where the APP deploys; Render only at launch; choosing it creates the app on the owner's own Render account with ADR 0327's borrowed key. **D4 (owner):** "decide later" is allowed. **D5 (owner):** no project is moved. **D6 (measured):** ADR 0145 Finding 1 is live — the hub cookie is `Domain=.cloudbongos.com` and a hall loads modules from its own repo — so our-address halls need task 1004357; an owner domain is safe. **D7 (measured):** at the ceiling the create route refuses `box_full` up front, and the resize is not a prerequisite. Task 1004184 re-scoped, task 1004185 on hold.](0345-we-host-every-projects-hall-and-its-app-deploys-where-the-owner-chooses.md) | hosting / provisioning / security |
 | 0346 | [**Dev boxes are retired; a builder builds from their own checkout** ([task 1003898](https://cloudbongos.com/builders#/task/1003898), goal 1000120 — owner Lars). Records the whole removal, link by link, the owner's three rulings of 2026-09-13 (drop the data, delete `.devcontainer/`, remove `bongos box`/`shell`/`code`), what was kept on purpose (server-mediated publish, the CLI downloads, `secret-box`, `do-api`, the declared-source rule), and the retirement guards that still name the box. Supersedes 0031, 0044, 0045, 0053, 0057, 0059, 0071, 0072 (code staleness), 0123, 0144, 0145 (desktop-app branding), 0148, 0193, 0277; supersedes in part 0035, 0046, 0052, 0055, 0072 (Bongos app), 0151 §3.](0346-dev-boxes-are-retired.md) | builder environment / removal |
 | 0347 | [**Every store module ships a how-to: a file in the module, a publish gate, and a Docs score shown on its own** ([task 1004364](https://cloudbongos.com/builders#/task/1004364), goal 1000091 — working area 5, owner Will). Amends ADR 0343 D1. **D1-D2 (owner):** the how-to is `HOWTO.md` at the module root, frozen with the version by the tarball hashes, with five required sections (what it does; install and enable; how to use it, with one worked example; configuration; limits and known issues). **D3:** an optional `howto.artifactUrl` Claude artifact shown as "also available as", never graded. **D4:** `bongos module publish` and the store refuse a version with a missing file or empty section, naming it; store versions only. **D5 (owner):** a Docs part scored 0–100 per version, day one, shown beside the parts but NOT in the D3 average, floor or ranking; "pending"/"not scored" never zero; price never an input. **D6 (owner):** one Sonnet 5 call per version, 5¢ ceiling.](0347-every-store-module-ships-a-how-to.md) | modules / store / quality |
+| 0348 | [**The web tier may look, read-only, at what an owner's Render key can see** ([task 1004352](https://cloudbongos.com/builders#/task/1004352), goal 1000106 — working area 1, owner Lars). Amends ADR 0111 §2. **D1 (owner):** one route, `POST /provisioning/render/lookup`, may call Render from the web tier — GET only (workspaces; web services in one named workspace), the owner's key held for that request and never stored, logged or returned, every service checked to carry the workspace asked about, capped per builder. Every write stays in the runner. **D2 (owner):** a key sent during a Create rides the project's own `provision` run; the runner sets the app up on Render straight after the project is up and clears the key either way.](0348-the-web-tier-may-look-read-only-at-what-an-owners-render-key-can-see.md) | provisioning / security / render |
+| 0349 | [**A version preview is a sandboxed child the web tier launches, reached by a cookie** ([task 1004300](https://cloudbongos.com/builders#/task/1004300), goal 1000090 — BONGOS-V2, owner Lars, approved 2026-09-29). Amends ADR 0293 D1 for this feature only. **D1 (owner):** route by a `bongos_preview` cookie through an optional `request.divert` seam, not a path; forward only with the cookie, off the sign-in and preview paths, with no Bearer, and with `core.pin.move` re-checked on every request. **D2 (owner):** the npm-release module launches the preview itself, with a deny-by-default environment, a dump-and-restore copy of the database (never a template copy), one at a time, 20-minute idle stop, published versions within 30 of the running one. **D3:** the same database role and no egress firewall are accepted for now.](0349-a-version-preview-is-a-sandboxed-child-the-web-tier-launches.md) | modules / npm-release / deploy |
+| 0350 | [**The hub holds a per-project WRITE deploy key, so a hosted project's upgraded pin always reaches its GitHub repo** ([task 1004291](https://cloudbongos.com/builders#/task/1004291), follow-up to task 1004065). Amends ADR 0176. The owner's token lasts one hour and the checkout's own key is read-only, so most hosted upgrades ended "GitHub was not updated". **D1:** a second deploy key per repo, registered `read_only: false` as `cloudbongos-pin-<slug>`, the pull key untouched. **D2:** kept outside every checkout in the runner's own directory (0700 dir, 0600 key, modes verified), unreadable by the project's account. **D3:** minted at standup and whenever a fresh owner token finds none, so reconnecting GitHub once is enough. **D4:** `pushUpgradePin` tries write key, then owner token, then origin, never forced. **D5:** revoked on teardown and disconnect. **D6:** a project on the shared app user is refused a key: "needs its own account first". **D7:** /deploy says reconnecting sets up lasting access.](0350-the-hub-holds-a-per-project-write-deploy-key-so-a-hosted-upgrade-reaches-github.md) | provisioning / security |