@bongos/core 1.19.331 → 1.19.333

package/scripts/gds/provision-units.js

@@ -0,0 +1,262 @@
+// scripts/gds/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/gds/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 { APP_USER, CORE_PKG_DIR, dbName, parseTargetRef, standaloneRoot } = require('./provision-repo.js');
+
+function serviceUnit(inst, { etcBase = CONFIG.etcBase } = {}) {
+  const envFile = path.posix.join(etcBase, inst.slug, 'web.env');
+  const standalone = inst.hosting_shape === 'standalone';
+  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
+User=lars
+Group=lars
+WorkingDirectory=${workDir}
+EnvironmentFile=${envFile}
+Environment=PGDATABASE=${dbName(inst)}
+Environment=PORT=${inst.port}
+ExecStart=${execStart}
+Restart=always
+RestartSec=3
+StandardOutput=journal
+StandardError=journal
+NoNewPrivileges=true
+
+[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 `amazonprimea` default, and the repo's global gds-db-backup units
+// hardcode /home/lars/amazonprimea — 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/dedicated from this checkout's
+// scripts/gds/ — mirrors serviceUnit's execStart resolution so they can't diverge.
+function backupScriptPath(inst) {
+  const rel = 'scripts/gds/db-backup-nightly.sh';
+  return inst.hosting_shape === 'standalone'
+    ? 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=${APP_USER}
+Group=${APP_USER}
+# 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 branding pack a provisioned CO-TENANT instance loads: the shared, committed
+// neutral starter (the co-tenant model shares ONE checkout, differentiated only by
+// env — src/branding.js's GDS_BRANDING_FILE knob). Per-instance identity/domains
+// therefore ride ENV OVERRIDES, not a divergent pack. Kept as a constant so the
+// GDS_BRANDING_FILE line below and the env-var PREFIX (which must equal this pack's
+// envPrefix, or src/branding.js's ENV_OVERRIDES never fire) can't drift apart.
+const PROVISIONED_BRANDING_FILE = 'config/branding.neutral.json';
+
+// The env-var prefix a provisioned instance actually RESOLVES — i.e. the envPrefix
+// of the pack it loads (PROVISIONED_BRANDING_FILE). src/instance-config.resolveEnv
+// reads <envPrefix>_<SUFFIX>, and src/branding.resolveBranding applies
+// <envPrefix>_{PUBLIC,BUILDERS,…}_ORIGIN overrides — so a web.env var only takes
+// effect under THIS prefix. Read from the pack (fail-soft to the vanilla default)
+// so it stays in lockstep instead of a magic string. (The prior slug-based prefix
+// was a latent bug: it never matched the neutral pack's CLOUDBONGOS envPrefix, so
+// the OAuth creds were silently unreadable — task 1972.)
+function provisionedEnvPrefix() {
+  try {
+    const pack = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, PROVISIONED_BRANDING_FILE), 'utf8'));
+    return pack.envPrefix || 'CLOUDBONGOS';
+  } catch { return 'CLOUDBONGOS'; }
+}
+
+// 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 } = {}) {
+  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/gds/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/gds/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/gds/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. (Org-owned repo: the org login is not a
+  // sign-in identity, so it is left unset; the owner sets <prefix>_FIRST_ADMIN by hand.)
+  const ownerRepo = parseTargetRef(inst.target_ref);
+  const firstAdminLine = ownerRepo && ownerRepo.owner
+    ? `${prefix}_FIRST_ADMIN=${ownerRepo.owner}\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')}
+`
+    : '';
+  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}GDS_BRANDING_FILE=${PROVISIONED_BRANDING_FILE}
+${originLines}${appLines}PORT=${inst.port}
+PGDATABASE=${dbName(inst)}
+${fedLines}${settingsEnvLines(inst, prefix)}`;
+}
+function webEnvPath(inst, { etcBase = CONFIG.etcBase } = {}) {
+  return path.posix.join(etcBase, inst.slug, 'web.env');
+}
+
+// ── 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.
+
+module.exports = {
+  PROVISIONED_BRANDING_FILE,
+  backupScriptPath,
+  backupService,
+  backupServicePath,
+  backupTimer,
+  backupTimerPath,
+  backupUnitName,
+  provisionedEnvPrefix,
+  serviceUnit,
+  serviceUnitPath,
+  webEnvBody,
+  webEnvPath,
+};