@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/provision-teardown.js

@@ -0,0 +1,106 @@
+'use strict';
+// provision-teardown.js — reverse the provisioning runbook for one instance
+// (idempotent). Split out of provision.js (task 1002897), which sat at the size
+// ratchet; provision.js re-exports teardownInstance, so its callers are unchanged.
+//
+// What a teardown takes down: the service + backup units, the per-instance Caddy
+// snippet, the DNS record (parked at the blackhole), and the deploy key. What it
+// deliberately LEAVES (ADR 0181): the database, its dumps and the checkout (data is
+// precious), and the row's `domain` + `port` — a revive re-uses exactly that address,
+// and step 5 of the next standup UPSERTs it straight back.
+
+const path = require('node:path');
+const { CONFIG, REPO_ROOT } = require('./provision-config.js');
+const { dbName, deployKeyPath, deployKeyTitle, parseTargetRef, resolveOwnerGithubToken } = require('./provision-repo.js');
+const { pinKeyPath, pinKeyTitle, revokePinWriteKey } = require('./provision-pin-key.js');
+const { resolveProcessManager } = require('./provision-process.js');
+const { caddySnippetPath, dnsReleaseEnv } = require('./provision-net.js');
+const apexMod = require('./instance-apex.js');
+const { isReservedHostname } = require('../../modules/provisioning/provisioning.js');
+
+async function teardownInstance(inst, deps) {
+  const { db, provisioning, exec, log, apply, privileged } = deps;
+  const controlExec = deps.controlExec || exec;
+  // Tear down on the box the instance actually RAN on: a standalone ran control-plane-
+  // local (task 2074), so disable/remove its unit HERE — not on the remote co-hosting
+  // box, where it was never installed (that would allowFail-noop and leave the real
+  // control-plane unit running). Co-tenant is unchanged.
+  const boxExec = inst.hosting_shape === 'cloud-host' ? controlExec : exec;
+  const sudoP = privileged ? 'sudo ' : '';   // systemctl / rm-under-/etc escalation (task 2066)
+  log(`teardown ${inst.slug} (status=${inst.status})`);
+  if (apply) await provisioning.setInstanceStatus(db, inst.id, 'tearing_down');
+  // Stop + remove the service AND the nightly backup units (task 2213; the dir + dumps stay — precious data, like the DB below). Whoever supervises the instance owns its removal (ADR 0306) — the systemd manager keeps the reset-failed step task 1003940 added, since a removed unit's FAILED state outlives its file and `systemctl --failed` listed torn-down ghosts for weeks.
+  (deps.processManager || resolveProcessManager()).removeService(inst, { exec: boxExec, sudoP });
+  // The site snippet standup step 6 wrote: while it stays, Caddy proxies the hostname to
+  // a port nothing listens on and every visitor gets a 502 (task 1002897). Not precious.
+  boxExec(`${sudoP}rm -f ${caddySnippetPath(inst)}`, { allowFail: true });
+  boxExec(`${sudoP}systemctl reload caddy`, { allowFail: true });
+  // Left for an operator (data is precious), naming ONLY what this row created —
+  // teardown now takes 'requested'/'error'. `port` + `domain` stay held: ADR 0181.
+  if (inst.db_name) log(`  (left for the operator: dropdb ${dbName(inst)}, prune ${CONFIG.backupDir}/${dbName(inst)}-*.sql.gz)`);
+  parkAddress(inst, { controlExec, log, apply });
+  // The app's Render services are the OWNER's: forget them, never delete them (ADR 0327 §3, task 1004183).
+  await require('./provision-render.js').forgetRenderApp(inst, { db, log, apply });
+  // Revoke the instance's deploy key (ADR 0176) and remove its local halves. The
+  // checkout itself is deliberately left in place (data is precious), so the key
+  // files must NOT ride along — and a revoke skip must be LOUD: a torn-down project
+  // silently keeping durable read access to the owner's private repo is the exact
+  // shape a teardown exists to end. A missing token / API hiccup never blocks it.
+  if (inst.hosting_shape === 'cloud-host' && inst.target_ref) {
+    const repo = parseTargetRef(inst.target_ref);
+    if (repo) {
+      try {
+        const token = await resolveOwnerGithubToken(inst, deps, { tag: '[teardown]' });
+        if (token) {
+          const ghRepos = deps.githubRepos || require(path.join(REPO_ROOT, 'src/bongos/github-repos'));
+          if (apply) {
+            const keys = await ghRepos.listDeployKeys(token, { owner: repo.owner, name: repo.name, fetchImpl: deps.fetchImpl });
+            const ours = keys.find((k) => k.title === deployKeyTitle(inst));
+            if (ours) {
+              await ghRepos.deleteDeployKey(token, { owner: repo.owner, name: repo.name, keyId: ours.id, fetchImpl: deps.fetchImpl });
+              log(`  revoked the "${deployKeyTitle(inst)}" deploy key on ${repo.owner}/${repo.name}`);
+            }
+            // The hub's WRITE key (ADR 0350) — the more dangerous of the two to leave behind.
+            await revokePinWriteKey(inst, { ...deps, controlExec: boxExec, apply: true, githubRepos: ghRepos }, { token, repo, keys });
+          } else log(`  would revoke the "${deployKeyTitle(inst)}" and write deploy keys on ${repo.owner}/${repo.name} if present`);
+        } else {
+          log(`  (deploy-key revoke skipped: no usable owner credential — if ${repo.owner}/${repo.name} carries a "${deployKeyTitle(inst)}" or "${pinKeyTitle(inst)}" deploy key, remove it in the repo's settings)`);
+        }
+      } catch (e) { log(`  (deploy-key revoke skipped: ${e && e.message})`); }
+      boxExec(`rm -f ${deployKeyPath(inst)} ${deployKeyPath(inst)}.pub`, { allowFail: true });
+      // The write key's local half goes whatever happened above (lookup failed, no token).
+      boxExec(`rm -f ${pinKeyPath(inst, deps)} ${pinKeyPath(inst, deps)}.pub`, { allowFail: true });
+    }
+  }
+  if (apply) {
+    await provisioning.setInstanceStatus(db, inst.id, 'torn_down', { torn_down_at: new Date().toISOString() });
+    await provisioning.recordEvent(db, { instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'torn_down', detail: 'torn down by runner', actor: 'runner' });
+  }
+  log(`  ✓ ${inst.slug} torn down`);
+  return { ok: true };
+}
+
+// Park the row's hostname at the RFC 5737 blackhole — the release a re-point already
+// uses (ADR 0200 §2: parked, not deleted, so no NXDOMAIN window gets negative-cached).
+// Runs on the CONTROL PLANE for every shape: the hook needs the Cloudflare token, which
+// never leaves it. BEST-EFFORT: a failure is logged and never strands the row. A
+// platform-reserved hostname is refused outright — standup would never have been given
+// one, and blackholing it would take the platform's own record down.
+function parkAddress(inst, { controlExec, log, apply }) {
+  if (!inst.domain) return;
+  if (isReservedHostname(inst.domain, apexMod.instanceApex())) {
+    log(`  [dns] NOT parking ${inst.domain}: a platform-reserved hostname is never blackholed by a teardown`);
+    return;
+  }
+  if (!CONFIG.dnsHook) {
+    log(`  [dns] cannot park ${inst.domain} (BOX_DNS_HOOK unset) — point its A record at 192.0.2.1 by hand`);
+    return;
+  }
+  const env = dnsReleaseEnv(inst.domain);
+  log(`  [dns] park ${inst.domain} -> ${env.BOX_IP} (blackhole, zone ${env.CLOUDFLARE_ZONE}) via ${CONFIG.dnsHook}`);
+  if (!apply) return;
+  try { controlExec(CONFIG.dnsHook, { env }); }
+  catch (e) { log(`  ⚠ could not park ${inst.domain}: ${(e && e.message) || e} — its A record still points at the platform`); }
+}
+
+module.exports = { teardownInstance };

package/scripts/bongos/provision-units.js

@@ -0,0 +1,469 @@
+// scripts/bongos/provision-units.js — the systemd + environment templates: the
+// instance service unit, the db-backup service and timer, and the web.env body.
+//
+// Carved out of scripts/bongos/provision.js by task 1003206 (goal 1000079, the R03
+// de-monolith plan) to bring the control-plane CLI under the 1,500-line ratchet.
+// A STRUCTURAL move: bodies unchanged, provision.js requires every name back, so
+// the intent runner and its unit templates behave exactly as before.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { CONFIG, REPO_ROOT } = require('./provision-config.js');
+const { CORE_PKG_DIR, appUser, dbName, instanceDbRole, instanceStateDir, instanceUser, parseTargetRef, standaloneRoot } = require('./provision-repo.js');
+const { capDirectives } = require('./provision-caps.js');
+
+function serviceUnit(inst, { etcBase = CONFIG.etcBase } = {}) {
+  const envFile = path.posix.join(etcBase, inst.slug, 'web.env');
+  const user = instanceUser(inst), stateDir = instanceStateDir(inst);
+  const standalone = inst.hosting_shape === 'cloud-host';
+  const workDir = standalone ? standaloneRoot(inst) : REPO_ROOT;
+  const execStart = standalone
+    ? `/usr/bin/node ${CORE_PKG_DIR}/src/platform-server.js`
+    : `/usr/bin/node src/platform-server.js`;
+  return `[Unit]
+Description=Cloud Bongos instance — ${inst.slug} (provisioned by provision.js, ADR 0111)
+After=network-online.target postgresql.service
+Wants=network-online.target
+Requires=postgresql.service
+
+[Service]
+Type=simple
+# This instance's OWN unix account, never the shared app user (task 1003369, audit B3).
+# Co-tenant is the default shape, so a shared User= let every instance read every
+# sibling's /proc/<pid>/environ — GITHUB_APP_PRIVATE_KEY, the hub client secret, every
+# OAuth cred in the EnvironmentFile below. A distinct uid is what closes that: /proc
+# environ is readable only by the process's own uid.
+User=${user}
+Group=${user}
+WorkingDirectory=${workDir}
+# Read by PID 1 as root BEFORE the privilege drop, so 0600 root-owned stays correct —
+# the instance account itself never needs read on its own secrets file.
+EnvironmentFile=${envFile}
+# HOME is the state dir, NOT /home: the server writes inside its config home on first
+# boot (secret-box.js provisions builder-secret.key there) and ProtectHome below makes
+# /home read-only. Without this the instance comes up unable to hold a secret.
+Environment=HOME=${stateDir}
+Environment=PGDATABASE=${dbName(inst)}
+Environment=PORT=${inst.port}
+ExecStart=${execStart}
+Restart=always
+RestartSec=3
+StandardOutput=journal
+StandardError=journal
+NoNewPrivileges=true
+# The same hardening the sibling backup unit already carries. ReadWritePaths is the
+# whole allow-list under ProtectSystem=strict: the state dir, plus the instance's own
+# config/ (the modules toggle writes config/modules.json at runtime). The checkout the
+# service RUNS is deliberately not writable by it. The leading dash on config/ keeps a
+# shape that has none from failing to mount rather than failing to start.
+ProtectSystem=strict
+ProtectHome=read-only
+PrivateTmp=true
+ReadWritePaths=${stateDir} -${workDir}/config
+# Resource caps (task 1004414; the numbers and their reasons are in provision-caps.js).
+${capDirectives().join('\n')}
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function serviceUnitPath(inst) { return `/etc/systemd/system/${inst.slug}.service`; }
+
+// ── nightly DB backup: per-instance timer + service (task 2213) ─────────────
+// PRODUCTIZES the manual task-2210 fix: a newly-provisioned instance was born with
+// NO backups (dir absent, GDS_BACKUP_DB unset → the script fell back to the
+// nonexistent `example` default, and the repo's global gds-db-backup units
+// hardcode /home/lars/example — wrong for the consumer node_modules/@bongos/
+// core layout). These generators emit a PER-INSTANCE unit pair that fixes all three:
+//   • name  → `<slug>-db-backup.{service,timer}` so co-tenant instances on one box
+//             never collide (each dumps its OWN db; the script's retention prune is
+//             already `<db>-*.sql.gz`-scoped, so a shared backupDir is safe).
+//   • DB    → Environment=GDS_BACKUP_DB=<instance db>, set on the unit (not read from
+//             the web.env) so the dump targets the right database with no fallback.
+//   • path  → ExecStart resolves the canonical script INSIDE the instance's pinned
+//             @bongos/core (standalone) or this control-plane checkout (co-tenant),
+//             the SAME workDir/CORE_PKG_DIR split serviceUnit uses — never the old
+//             monorepo path.
+function backupUnitName(inst) { return `${inst.slug}-db-backup`; }
+function backupServicePath(inst) { return `/etc/systemd/system/${backupUnitName(inst)}.service`; }
+function backupTimerPath(inst) { return `/etc/systemd/system/${backupUnitName(inst)}.timer`; }
+// The consumer-layout-correct absolute path to db-backup-nightly.sh. Standalone runs
+// it from the instance's own pinned core; co-tenant from this checkout's
+// scripts/bongos/ — mirrors serviceUnit's execStart resolution so they can't diverge.
+function backupScriptPath(inst) {
+  const rel = 'scripts/bongos/db-backup-nightly.sh';
+  return inst.hosting_shape === 'cloud-host'
+    ? path.posix.join(standaloneRoot(inst), CORE_PKG_DIR, rel)
+    : path.posix.join(REPO_ROOT, rel);
+}
+function backupService(inst, { backupDir = CONFIG.backupDir } = {}) {
+  return `[Unit]
+Description=Nightly pg_dump of the ${inst.slug} GDS DB (provisioned by provision.js, task 2213)
+After=postgresql.service
+Requires=postgresql.service
+
+[Service]
+Type=oneshot
+User=${appUser()}
+# No Group=: systemd then uses the app user's primary group, whatever it is named.
+# The DB to dump + where dumps land — set on the unit (not via the instance web.env)
+# so the dump targets the right database with no fallback to a stale default (root
+# cause of the task-2210 breakage). db-backup-nightly.sh reads both as env.
+Environment=GDS_BACKUP_DB=${dbName(inst)}
+Environment=GDS_BACKUP_DIR=${backupDir}
+# Consumer-layout path: the canonical script inside this instance's pinned core.
+ExecStart=/bin/bash ${backupScriptPath(inst)}
+# Modest hardening — the script only needs read on the pg socket + write on the
+# backup dir. Mirrors the repo's gds-db-backup.service.
+NoNewPrivileges=true
+ProtectSystem=strict
+ReadWritePaths=${backupDir}
+ProtectHome=read-only
+PrivateTmp=true
+
+[Install]
+# Not socket-activated; the timer drives this. The timer's WantedBy is what enables.
+`;
+}
+function backupTimer(inst) {
+  return `[Unit]
+Description=Daily timer for the ${inst.slug} GDS DB pg_dump (provisioned by provision.js, task 2213)
+
+[Timer]
+# 04:00 UTC daily, mirroring the repo's gds-db-backup.timer (low-traffic window).
+OnCalendar=*-*-* 04:00:00 UTC
+# Catch up on next boot if the box was off when the timer was due.
+Persistent=true
+# Jitter so simultaneous timers don't dogpile the disk at exactly 04:00.
+RandomizedDelaySec=300
+Unit=${backupUnitName(inst)}.service
+
+[Install]
+WantedBy=timers.target
+`;
+}
+
+// The pack the provisioner reads to learn an instance's env-var PREFIX floor.
+//
+// It is NOT the pack the instance loads, and that distinction is the whole of task 1003740.
+// The original co-tenant model shared ONE checkout across every instance, differentiated only by
+// env, so provisioning pinned the pack to `config/branding.neutral.json` and let identity
+// ride ENV OVERRIDES. That model is gone: under ADR 0108 each co-tenant has its own checkout
+// (`WorkingDirectory=/srv/<base>/<slug>`, running `node_modules/@bongos/core`) and its own
+// `config/branding.json` written at init.
+//
+// The pin outlived it, and src/branding.js's ENV_OVERRIDES cover domains, auth.idp and landing —
+// never `identity.productName`. So every hosted instance kept serving the NEUTRAL pack's name:
+// GET /api/bongos/instance on hermeslines-marketing, mercury and demo all answered "Cloud Bongos"
+// while each instance's own pack on disk said otherwise, and `bongos login <instance>` greeted a
+// newcomer with the platform's name at the moment they were deciding whether to trust it.
+//
+// The instance now loads its own pack by src/branding.js's DEFAULT (INSTANCE_PATH =
+// <instanceRoot>/config/branding.json), which falls back to neutral when absent — so no
+// branding-file env line is written at all. Reading the neutral pack HERE is still correct: it is
+// the prefix floor an instance inherits unless its own pack overrides envPrefix, and every live
+// co-tenant pack pins `envPrefix: "CLOUDBONGOS"` explicitly.
+// ENV_PREFIX_PACK + provisionedEnvPrefix (and the task-1004573 pack checks) live in
+// pack-env-prefix.js — provision-repo.js needs them too, and it cannot require this file
+// (this file requires it). Re-exported below so every existing caller is unchanged.
+const { ENV_PREFIX_PACK, provisionedEnvPrefix, envPrefixMismatch, normalizePackEnvPrefix } = require('./pack-env-prefix.js');
+
+// The per-instance secrets file body (the standup runbook's /etc/<inst>/web.env).
+// The OAuth client id/secret are GUIDED/manual inputs (no GitHub create-API) — the
+// runner writes placeholders the owner fills, unless provided via the intent later.
+// A domain (bring-your-own or provisioned) drives the single-host origin overrides:
+// with them set, src/branding.js resolves the instance's REAL buildersOrigin, so the
+// core's single-host router (isBuildersHost === buildersOrigin host, task 1971) serves
+// the hall on this host + OAuth uses the real callback origin — without them the pack
+// stays at neutral localhost and the hall never loads (task 1972). No domain yet
+// (bring-your-own deferred, ADR 0111 §4) ⇒ origins stay neutral until one is set.
+function webEnvBody(inst, { clientId = '', clientSecret = '', appId = null, appPem = null, federation = null, ownerLogin = null, dbPassword = null } = {}) {
+  const prefix = provisionedEnvPrefix(), { settingsEnvLines } = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning')); // eslint-disable-line global-require
+  const origin = inst.domain ? `https://${inst.domain}` : '';
+  const originLines = origin
+    ? `# Single-host origins (task 1972): the hall serves on THIS host + OAuth/redirects
+# use the real address. Resolved by src/branding.js ENV_OVERRIDES under the pack's
+# ${prefix} envPrefix. A single-host instance has no dedicated builders./status.
+# subdomain, so all four point at the one host.
+${prefix}_PUBLIC_ORIGIN=${origin}
+${prefix}_BUILDERS_ORIGIN=${origin}
+${prefix}_STATUS_ORIGIN=${origin}
+${prefix}_OAUTH_ORIGIN=${origin}
+`
+    : `# No domain yet (bring-your-own-domain pending, ADR 0111 §4) — origins stay
+# neutral (localhost); add ${prefix}_{PUBLIC,BUILDERS,OAUTH}_ORIGIN once a domain
+# is set, or the hall won't load on the instance's host.
+`;
+  // The OAuth app creds are filled by ONE of two paths (task 2080): the GitHub App
+  // Manifest flow (placeManifestCreds fetches them control-plane-side + re-writes this
+  // file with clientId/clientSecret set), or the manual oauth-secret.js placement. On
+  // the first provision write they are blank placeholders the flow fills later.
+  const credComment = federation
+    ? `# Provisioned by scripts/bongos/provision.js (ADR 0111). This instance FEDERATES sign-in
+# through the Cloud Bongos hub (ADR 0141 §4) — it needs no GitHub app of its own, so the
+# GitHub client id/secret below stay blank; the ${prefix}_HUB_* block drives sign-in.`
+    : clientId || clientSecret
+    ? `# Provisioned by scripts/bongos/provision.js (ADR 0111). OAuth app creds placed via the
+# GitHub App Manifest flow (ADR 0133) — the owner clicked one link; no secret was pasted.`
+    : `# Provisioned by scripts/bongos/provision.js (ADR 0111). Fill the OAuth app creds via the
+# one-click GitHub App Manifest flow (ADR 0133), or manually (oauth-secret.js place):`;
+  // The founding owner (firstAdmin): the GitHub login src/bongos/auth.js seats as the
+  // instance's first Archon on first sign-in (maybeSeatFirstAdmin checks
+  // <prefix>_FIRST_ADMIN before branding.firstAdmin). WITHOUT it a provisioned instance
+  // has NO owner — first sign-in is refused / lands rankless and the owner can never
+  // claim their own instance (goal 35 / criterion 165 regression, caught live 2026-07-07:
+  // demo had every origin override but no FIRST_ADMIN, so the owner could not be seated).
+  // Derived from the instance repo owner (target_ref = "<owner>/<repo>"), the SAME source
+  // instanceInitSpec uses for the scaffold's branding.firstAdmin — so this env override and
+  // the scaffolded config/branding.json agree — and, like the spec, PREFERS the signed-in
+  // builder's login when the caller resolved one (ownerLoginOf). An org-owned repo's
+  // owner is the org, which is not a sign-in identity: seating it seats nobody (task 1003240).
+  const ownerRepo = parseTargetRef(inst.target_ref);
+  const firstAdmin = ownerLogin || (ownerRepo && ownerRepo.owner) || null;
+  const firstAdminLine = firstAdmin ? `${prefix}_FIRST_ADMIN=${firstAdmin}\n` : '';
+  // Cross-site identity federation block (ADR 0141 §4, task #1002109). Present only for
+  // a HOSTED (federated) instance: flips auth.idp ON via the env override branding.js
+  // reads (idpEnabled), and carries the hub origin, this instance's per-client secret
+  // (authenticates it TO the hub, server-to-server), and the hub's PUBLIC key (verifies
+  // the CLI's hub-signed assertion offline). All written straight to this chmod-600
+  // file — never through a browser or chat (the ADR 0133 secret-placement posture).
+  const fedLines = federation
+    ? `${prefix}_AUTH_IDP=true
+${prefix}_HUB_ORIGIN=${federation.hubOrigin}
+${prefix}_HUB_CLIENT_ID=${federation.clientId}
+${prefix}_HUB_CLIENT_SECRET=${federation.clientSecret}
+${prefix}_HUB_PUBLIC_KEY=${federation.hubPublicKey}
+`
+    : '';
+  // The publish credential (task 1003049, ADR 0055): the manifest-born App's id +
+  // private key, read BARE (no prefix) by modules/lifecycle/github-push.js. The
+  // pem is env-file-flattened to a single line with literal \n (the ADR 0055
+  // rotation convention; normalizePem restores it). The installation id is NOT
+  // written — the server discovers it from the repo once the owner installs the
+  // App (the onboarding app-install step).
+  const appLines = appId && appPem
+    ? `# Publish credential (ADR 0055): the sign-in GitHub App doubles as it. The server
+# mints short-lived installation tokens once the App is INSTALLED on the repo.
+GITHUB_APP_ID=${appId}
+GITHUB_APP_PRIVATE_KEY=${String(appPem).replace(/\r?\n/g, '\\n')}
+`
+    : '';
+  // The per-instance DB credential (task 1003369, audit B3). Present only once the
+  // runner has created the role — a first dry-run and any legacy caller omit it, and the
+  // instance then falls back to the peer auth it used before, so this can never brick a
+  // box mid-migration. src/bongos/pool.js reads both names explicitly.
+  const dbLines = dbPassword
+    ? `PGUSER=${instanceDbRole(inst)}\nPGPASSWORD=${dbPassword}\n`
+    : '';
+  // The pool cap (task 1003928, ADR 0285 §3): a co-located instance shares the box's
+  // Postgres with every sibling and the control plane, so its pool may not take pg's
+  // default 10 of the server's 97. src/bongos/pool.js reads it bare.
+  const poolLine = `PGPOOL_MAX=${CONFIG.instancePoolMax}\n`;
+  // Where this project's Update button goes (task 1004608) — see hubUpgradeEnvVarsFor.
+  const hubUpgradeLines = Object.entries(hubUpgradeEnvVarsFor(inst)).map(([k, v]) => `${k}=${v}\n`).join('');
+  return `# /etc/${inst.slug}/web.env — per-instance secrets (chmod 600, OUTSIDE the repo).
+${credComment}
+${prefix}_GITHUB_CLIENT_ID=${clientId || ''}
+${prefix}_GITHUB_CLIENT_SECRET=${clientSecret || ''}
+${firstAdminLine}${originLines}${appLines}PORT=${inst.port}
+PGDATABASE=${dbName(inst)}
+${poolLine}${dbLines}${fedLines}${hubUpgradeLines}${settingsEnvLines(inst, prefix)}`;
+}
+function webEnvPath(inst, { etcBase = CONFIG.etcBase } = {}) {
+  return path.posix.join(etcBase, inst.slug, 'web.env');
+}
+
+// The settings env vars the runner pushes to a RUNNING instance (task 1003140):
+// the module's settingsEnvVars under the prefix the instance actually resolves —
+// the same pair webEnvBody writes at standup, so standup and push cannot drift.
+// The four origin overrides web.env carries for an addressed instance — the
+// domain-dependent half of webEnvBody, on its own so domain-attach can patch
+// exactly those lines IN PLACE (task 1003237). A single-host instance has no
+// dedicated builders./status. subdomain, so all four point at the one host.
+// Empty for a domainless instance: there is no origin to assert, and writing
+// `=` over a real one would take the hall down. PURE.
+function originEnvVarsFor(inst) {
+  if (!inst || !inst.domain) return {};
+  const prefix = provisionedEnvPrefix(), origin = `https://${inst.domain}`;
+  return {
+    [`${prefix}_PUBLIC_ORIGIN`]: origin,
+    [`${prefix}_BUILDERS_ORIGIN`]: origin,
+    [`${prefix}_STATUS_ORIGIN`]: origin,
+    [`${prefix}_OAUTH_ORIGIN`]: origin,
+  };
+}
+
+// `envBody` is the web.env being patched; only the control-plane row reads it (see
+// selfEnvPrefix). Every other shape keeps the provisioned-instance prefix, unchanged.
+function settingsEnvVarsFor(inst, envBody) {
+  const { settingsEnvVars } = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning')); // eslint-disable-line global-require
+  const prefix = inst && inst.hosting_shape === 'control-plane' ? selfEnvPrefix({ envBody }) : provisionedEnvPrefix();
+  return { ...settingsEnvVars(inst, prefix), ...hubUpgradeEnvVarsFor(inst) };
+}
+
+// The env-var prefix the CONTROL PLANE's own web process resolves (task 1004334). The
+// self row is not a provisioned instance: it loads the pack src/branding.js loads, from
+// ITS instance root, so provisionedEnvPrefix() (the neutral pack's floor) is the wrong
+// question — a value written under a prefix the site does not resolve is read by
+// nothing, and the push would report success over a site that never changed.
+//
+// Precedence mirrors loadBranding: the instance pack is a <PREFIX>_BRANDING_FILE line in
+// the web.env being patched (the file the web service actually boots with) when there is
+// one, else <instanceRoot>/config/branding.json; under it sits the core's neutral pack,
+// then the fallback. The first that names an envPrefix wins. A wrong answer is not silent: the
+// leg's read-back (settingsConsumed) compares the live manifest after the restart and
+// records "still reports the OLD values".
+function selfEnvPrefix({ envBody = '', instanceRoot, readFile = (p) => fs.readFileSync(p, 'utf8') } = {}) {
+  const { FALLBACK_ENV_PREFIX, LEGACY_ENV_PREFIXES } = require('../../src/instance-config');
+  const root = instanceRoot || require('./provision-repo.js').selfInstanceRoot(); // eslint-disable-line global-require
+  const names = [FALLBACK_ENV_PREFIX, ...LEGACY_ENV_PREFIXES].map((p) => `${p}_BRANDING_FILE`);
+  const override = String(envBody || '').split(/\r?\n/)
+    .map((l) => /^([A-Z]+_BRANDING_FILE)=(.*)$/.exec(l.trim()))
+    .find((m) => m && names.includes(m[1]) && m[2].trim());
+  const candidates = [
+    override ? path.resolve(root, override[2].trim()) : path.join(root, 'config', 'branding.json'),
+    path.join(REPO_ROOT, ENV_PREFIX_PACK),
+  ];
+  for (const p of candidates) {
+    try {
+      const pack = JSON.parse(readFile(p));
+      if (pack && typeof pack.envPrefix === 'string' && pack.envPrefix) return pack.envPrefix;
+    } catch { /* absent or unreadable — the next candidate answers */ }
+  }
+  return FALLBACK_ENV_PREFIX;
+}
+
+// The instance's own public manifest — the settings read-back ADR 0190 names
+// (GET /api/bongos/instance → brand.project). Sibling of provision-net's healthzCmd:
+// same loopback + timeout, a different question ("did you READ it?").
+function instanceManifestCmd(inst) {
+  return `curl -sS --max-time 5 http://127.0.0.1:${inst.port}/api/bongos/instance`;
+}
+
+// Did the restarted instance CONSUME the pushed settings? Compares each key of
+// effectiveSettings(inst) against the manifest's brand.project (camelCase — the
+// src/branding.js ENV_OVERRIDES targets). true = every key matches; false = it
+// answers with a different value; null = unknown — the manifest carries no
+// project block (a core that predates task 1003139) or did not parse. PURE.
+function settingsConsumed(stdout, inst) {
+  const { effectiveSettings } = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning')); // eslint-disable-line global-require
+  let j;
+  try { j = JSON.parse(String(stdout || '').trim()); } catch { return null; }
+  const project = j && j.brand && j.brand.project;
+  if (!project || typeof project !== 'object') return null;
+  const camel = (k) => k.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+  return Object.entries(effectiveSettings(inst)).every(([k, v]) => project[camel(k)] === v);
+}
+
+// Upsert KEY=VALUE lines into an env-file body IN PLACE (task 1003140): an
+// existing `KEY=` line is replaced where it stands, a missing one is appended at
+// the end — every other line (creds, origins, the federation block, comments) is
+// untouched. This is how a setting reaches a RUNNING instance: the full-template
+// re-write webEnvBody produces would BLANK the OAuth creds placeManifestCreds
+// placed (this leg has no way to know them), so a live file is patched, never
+// regenerated. The oauth-secret.js fillOAuthEnv shape. PURE; keys are matched at
+// line start, exactly (a KEY that is a prefix of another never collides).
+function upsertEnvVars(body, vars) {
+  const esc = (k) => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  let text = String(body == null ? '' : body);
+  const missing = [];
+  for (const [key, value] of Object.entries(vars || {})) {
+    const re = new RegExp(`^${esc(key)}=.*$`, 'm');
+    if (re.test(text)) text = text.replace(re, () => `${key}=${value}`);
+    else missing.push(`${key}=${value}`);
+  }
+  if (missing.length) {
+    if (text.length && !text.endsWith('\n')) text += '\n';
+    text += `${missing.join('\n')}\n`;
+  }
+  return text;
+}
+
+// Env names a rename retired, carried forward ON THE BOX by the settings push (task
+// 1004395). The prelaunch-gate rename (task 1003152, ADR 0182) made PRELAUNCH_PASSWORD
+// primary and kept STEALTH_PASSWORD as an alias; the alias can only be dropped (task
+// 1003830) once every live web.env carries the new name, and before this the only way
+// to add it was the owner's SSH (blocker 1000147). [from, to] pairs.
+const ENV_RENAMES = Object.freeze([['STEALTH_PASSWORD', 'PRELAUNCH_PASSWORD']]);
+
+// Which renamed names does this web.env still hold ONLY under the old name? Returns
+// { vars, carried }: `vars` is the new name → the old line's right-hand side, copied
+// verbatim (quotes and all, so systemd reads the same value), for upsertEnvVars;
+// `carried` names the pairs and is the ONLY part that may reach a log or an event —
+// the value is a secret read on the box and it never leaves it. A new name that is
+// already set wins, even when it differs. The last line of a key counts, as systemd
+// reads it. PURE.
+function renamedEnvCarry(body) {
+  const lines = String(body == null ? '' : body).split(/\r?\n/);
+  const rhs = (key) => {
+    let v = null;
+    for (const l of lines) if (l.startsWith(`${key}=`)) v = l.slice(key.length + 1);
+    return v;
+  };
+  const isSet = (v) => v !== null && !['', '""', "''"].includes(v.trim());
+  const vars = {}, carried = [];
+  for (const [from, to] of ENV_RENAMES) {
+    const oldV = rhs(from);
+    if (isSet(oldV) && !isSet(rhs(to))) { vars[to] = oldV; carried.push(`${from} -> ${to}`); }
+  }
+  return { vars, carried };
+}
+
+// ── Cross-site identity: federate a hosted instance's sign-in through the hub ───
+// (ADR 0141 §4, task #1002109). The control plane IS the hub (cloudbongos.com), so
+// registration is a direct in-process call against the hub pool — no HTTP hop.
+
+// The hub's own public origin, written into each federated instance as
+// <PREFIX>_HUB_ORIGIN (what auth.js loadIdpConfig reads). Explicit PROVISION_HUB_ORIGIN
+// wins; otherwise the control plane's OWN public origin (<PREFIX>_PUBLIC_ORIGIN, the
+// env the hub already runs under). Null → not hub-configured → shouldFederate is false.
+function federationHubOrigin() {
+  const explicit = process.env.PROVISION_HUB_ORIGIN;
+  if (explicit) return String(explicit).replace(/\/+$/, '');
+  const own = process.env[`${provisionedEnvPrefix()}_PUBLIC_ORIGIN`];
+  return own ? String(own).replace(/\/+$/, '') : null;
+}
+
+// WHERE A HOSTED PROJECT'S UPDATE BUTTON GOES (task 1004608): the hub's deploy door for
+// THIS project, written as <PREFIX>_HUB_UPGRADE_URL. The hall used to learn the hub only
+// from the sign-in federation block, which only a co-tenant gets, so every cloud-host
+// project (and any that keeps its own GitHub app) told its owner to run `bongos upgrade`
+// on a server the platform runs. The door admits the owner of both tenant shapes
+// (modules/provisioning/core-upgrade-authz.js), so both get the address. Not a secret and
+// grants nothing: the door re-checks every request. Empty for the tenant shapes when no hub
+// origin resolves (a key that came and went would leave a stale line behind); absent for
+// every other shape, which has no door on this hub.
+const HUB_UPGRADE_SHAPES = new Set(['co-tenant', 'cloud-host']);
+function hubUpgradeEnvVarsFor(inst) {
+  if (!inst || !HUB_UPGRADE_SHAPES.has(inst.hosting_shape) || !inst.slug) return {};
+  const origin = federationHubOrigin();
+  return { [`${provisionedEnvPrefix()}_HUB_UPGRADE_URL`]: origin ? `${origin}/deploy?project=${encodeURIComponent(String(inst.slug))}` : '' };
+}
+
+module.exports = {
+  federationHubOrigin,
+  hubUpgradeEnvVarsFor,
+  ENV_PREFIX_PACK,
+  envPrefixMismatch,
+  normalizePackEnvPrefix,
+  backupScriptPath,
+  backupService,
+  backupServicePath,
+  backupTimer,
+  backupTimerPath,
+  backupUnitName,
+  instanceManifestCmd,
+  originEnvVarsFor,
+  provisionedEnvPrefix,
+  selfEnvPrefix,
+  serviceUnit,
+  serviceUnitPath,
+  settingsConsumed,
+  settingsEnvVarsFor,
+  renamedEnvCarry,
+  upsertEnvVars,
+  webEnvBody,
+  webEnvPath,
+};