@bongos/core 1.17.3 → 1.18.3

package/scripts/gds/provision.js

@@ -47,6 +47,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const cp = require('node:child_process');
+const crypto = require('node:crypto');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
@@ -98,6 +99,11 @@ const CONFIG = {
   // <slug>.caddy file (idempotent overwrite, no fragile append to a shared file);
   // the main Caddyfile carries a one-time `import <dir>/*.caddy` (operator setup).
   caddySnippetDir: process.env.PROVISION_CADDY_SNIPPET_DIR || '/etc/caddy/sites',
+  // Where nightly pg_dump backups land (db-backup-nightly.sh's GDS_BACKUP_DIR
+  // default). Shared across co-tenant instances on one box — dumps are named
+  // `<db>-<ts>.sql.gz`, so each instance's files + retention prune stay scoped to
+  // its own DB. Owned by the app user, mode 0750. (task 2213, productizes 2210.)
+  backupDir: process.env.PROVISION_BACKUP_DIR || '/var/backups/gds',
   // Dedicated-droplet defaults (only used for hosting_shape='dedicated').
   region: process.env.PROVISION_REGION || 'nyc3',
   baseImage: process.env.PROVISION_BASE_IMAGE || 'ubuntu-24-04-x64',
@@ -175,7 +181,23 @@ function loadDeps() {
   const provisioning = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning'));
   // eslint-disable-next-line global-require
   const { DoApi } = require(path.join(REPO_ROOT, 'scripts/gds/do-api'));
-  _deps = { pool, provisioning, DoApi };
+  // Cross-site identity (ADR 0141 §4, task #1002109). Resolve the hub-side module by a
+  // VARIABLE key, gated on isModuleEnabled — the module-loader's own dynamic-dispatch
+  // pattern (the run-unit-tests.js precedent), NOT a static 'modules/platform-identity/'
+  // literal that would couple this publishable core file to an instance-EXCLUDED module
+  // (fitness Check 16b / task 2135). A vanilla core that neither ships nor enables the
+  // module never resolves it → no MODULE_NOT_FOUND on a fresh boot. Null here → federation
+  // dormant (shouldFederate skips) → the instance owns its auth, byte-identical to today.
+  let platformIdentity = null, hubKeys = null;
+  const PI_KEY = 'platform-identity';
+  let piEnabled = false;
+  try { piEnabled = require(path.join(REPO_ROOT, 'src/modules')).isModuleEnabled(PI_KEY); } catch { piEnabled = false; }
+  if (piEnabled) {
+    const piBase = path.join(REPO_ROOT, 'modules', PI_KEY);
+    try { platformIdentity = require(path.join(piBase, 'platform-identity')); hubKeys = require(path.join(piBase, 'hub-keys')); }
+    catch { platformIdentity = null; hubKeys = null; }
+  }
+  _deps = { pool, provisioning, DoApi, platformIdentity, hubKeys };
   return _deps;
 }
 
@@ -252,6 +274,10 @@ function seedFirstVersionCmd(inst, { privileged = false } = {}) {
 // It is the ADR 0108 DESTINATION model; these generators make provision.js drive the
 // scripts/deploy/deploy-instance.sh runbook API-driven instead of by hand.
 const CORE_PKG_DIR = 'node_modules/@bongos/core';
+// The unix account the instance's Node process + its backup timer run as. Mirrors
+// serviceUnit's hardcoded `User=lars`/`Group=lars` (the droplet's app user); kept as
+// one constant so the backup dir owner + the backup unit's User= can't drift from it.
+const APP_USER = 'lars';
 function standaloneRoot(inst, { base = CONFIG.standaloneBase } = {}) { return path.posix.join(base, inst.slug); }
 // Sync the instance's own repo (host content + the core pin). Mirrors deploy-instance.sh
 // step 1 — assumes the repo is already cloned at standaloneRoot (initial clone is a
@@ -447,6 +473,80 @@ 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
@@ -479,7 +579,7 @@ function provisionedEnvPrefix() {
 // 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 = '' } = {}) {
+function webEnvBody(inst, { clientId = '', clientSecret = '', federation = null } = {}) {
   const prefix = provisionedEnvPrefix();
   const origin = inst.domain ? `https://${inst.domain}` : '';
   const originLines = origin
@@ -500,7 +600,11 @@ ${prefix}_OAUTH_ORIGIN=${origin}
   // 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 = clientId || clientSecret
+  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
@@ -519,6 +623,20 @@ ${prefix}_OAUTH_ORIGIN=${origin}
   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}
+`
+    : '';
   return `# /etc/${inst.slug}/web.env — per-instance secrets (chmod 600, OUTSIDE the repo).
 ${credComment}
 ${prefix}_GITHUB_CLIENT_ID=${clientId || ''}
@@ -526,12 +644,88 @@ ${prefix}_GITHUB_CLIENT_SECRET=${clientSecret || ''}
 ${firstAdminLine}GDS_BRANDING_FILE=${PROVISIONED_BRANDING_FILE}
 ${originLines}PORT=${inst.port}
 PGDATABASE=${dbName(inst)}
-`;
+${fedLines}`;
 }
 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.
+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;
+}
+
+// Whether provisioning should federate this instance's sign-in through the hub.
+// Dormant-by-default: true ONLY when the control plane is hub-configured (the
+// platform-identity module is present, a signing key is loadable, AND a hub origin
+// resolves), the instance is a CO-TENANT (the mothership-hosted shape whose web.env is
+// written locally — a `standalone` is owner-hosted and keeps its own GitHub app, the
+// self-hosted path; a `dedicated` droplet has no local web.env write yet, same gap the
+// ADR 0133 manifest flow leaves — see placeManifestCreds), and it has a public domain
+// (the origin the hub binds the CLI mint audience to — the #1002108 account-takeover
+// fix). Returns { federate, reason } so the caller can log WHY it skipped. PURE-ish
+// (reads env + the injected module handles; no DB, no I/O).
+function shouldFederate(inst, deps) {
+  const { platformIdentity, hubKeys } = deps;
+  if (!platformIdentity || !hubKeys) return { federate: false, reason: 'platform-identity module not present (control plane is not the hub)' };
+  if (!hubKeys.hubSigningConfigured()) return { federate: false, reason: 'hub signing key not configured (<PREFIX>_HUB_SIGNING_KEY unset)' };
+  if (!federationHubOrigin()) return { federate: false, reason: 'hub origin not resolvable (set PROVISION_HUB_ORIGIN or <PREFIX>_PUBLIC_ORIGIN)' };
+  if (inst.hosting_shape !== 'co-tenant') return { federate: false, reason: `${inst.hosting_shape} keeps its own GitHub app (not the co-tenant hosted path)` };
+  if (!inst.domain) return { federate: false, reason: 'no domain yet — federation needs the instance public origin' };
+  return { federate: true, reason: null };
+}
+
+// Register this hosted instance as an sso_clients row on the HUB (fresh per-client
+// secret) and return the federation block to bake into its web.env (ADR 0141 §4).
+// SECURITY: `origin` MUST be the instance's EXACT public origin — the hub binds the
+// CLI-federation mint audience to it (the #1002108 fix), so a mismatch would break
+// device sign-in (and a wrong origin would be a takeover vector). client_id is the
+// (unique, DNS-safe) slug, so a re-provision rotates the SAME row's secret via
+// registerClient's ON CONFLICT rather than orphaning a client. redirect_uri lists both
+// callback prefixes the core may emit (/api/gds is what auth.js builds today) so the
+// hub's exact-match allow-list accepts the browser leg. --apply gates the real hub
+// write; dry-run returns a placeholder block (so webEnvBody can still be composed) + logs.
+async function federateInstance(inst, deps) {
+  const { db, platformIdentity, hubKeys, log, apply } = deps;
+  const origin = `https://${inst.domain}`;
+  const clientId = inst.slug;
+  const hubOrigin = federationHubOrigin();
+  const hubPublicKey = hubKeys.hubPublicKeyB64();
+  if (!hubPublicKey) throw new Error('hub signing key is set but unreadable — cannot derive HUB_PUBLIC_KEY');
+  const redirectUris = [
+    `${origin}/api/gds/auth/web/callback`,
+    `${origin}/api/bongos/auth/web/callback`,
+  ];
+  if (!apply) {
+    log(`  [federate] would register client '${clientId}' on the hub (origin ${origin}) + write ${provisionedEnvPrefix()}_HUB_* + AUTH_IDP into web.env`);
+    return { hubOrigin, clientId, clientSecret: '0'.repeat(43), hubPublicKey };
+  }
+  const clientSecret = crypto.randomBytes(32).toString('base64url');
+  // Best-effort owner github_id — nice for the hub catalog's ownership link, but
+  // nullable in registerClient, so a lookup miss must never fail the provision.
+  let ownerGithubId = null;
+  try {
+    const { rows } = await db.query('SELECT github_id FROM builders WHERE id = $1', [inst.owner_builder_id]);
+    ownerGithubId = rows[0] ? rows[0].github_id : null;
+  } catch { /* non-fatal */ }
+  await platformIdentity.registerClient(
+    { clientId, secret: clientSecret, name: inst.slug, redirectUris, origin, ownerGithubId },
+    { pool: db },
+  );
+  log(`  [federate] registered client '${clientId}' on the hub (origin ${origin})`);
+  return { hubOrigin, clientId, clientSecret, hubPublicKey };
+}
+
 // The Cloudflare zone a hostname's A record lives in. Cloudflare zones are
 // registrable domains, which for the common case is the last two DNS labels
 // (mercury.example.com → example.com; apex example.com → example.com). Multi-part
@@ -842,6 +1036,28 @@ async function provisionInstance(inst, deps) {
   if (apply) await provisioning.setInstanceStatus(db, inst.id, 'provisioning');
   const patch = {};
 
+  // ── cross-site identity: register hub federation (ADR 0141 §4, task #1002109) ──
+  // Computed BEFORE the shape steps so the co-tenant web.env write (step 3) bakes it
+  // in — the instance comes up already federated, no post-hoc restart. Dormant unless
+  // the control plane is hub-configured AND the shape/domain qualify (shouldFederate);
+  // otherwise the instance owns its auth (direct GitHub), byte-identically to today.
+  let federation = null;
+  {
+    const fed = shouldFederate(inst, deps);
+    if (fed.federate) {
+      federation = await federateInstance(inst, deps);
+      log(`  [federate] ${inst.slug} → hub sign-in (auth.idp on) — no GitHub app of its own`);
+      if (apply) {
+        await provisioning.recordEvent(db, {
+          instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'federated',
+          detail: `sign-in federated to the hub (client ${inst.slug}, origin https://${inst.domain})`, actor: 'runner',
+        }).catch(() => {});
+      }
+    } else {
+      log(`  [federate] skipped (${fed.reason}) — instance owns its auth (direct GitHub)`);
+    }
+  }
+
   // ── step 1: server ───────────────────────────────────────────────────────
   // The A-record target for step 5's DNS UPSERT:
   //   • co-tenant  → PROVISION_PUBLIC_IP (the box it runs on — under remote-exec that
@@ -939,7 +1155,7 @@ async function provisionInstance(inst, deps) {
 
   // ── step 3: config + per-instance secrets ─────────────────────────────────
   log('  [config] per-instance web.env');
-  if (local) boxWriteFile(webEnvPath(inst), webEnvBody(inst), { mode: 0o600, sudo: true });
+  if (local) boxWriteFile(webEnvPath(inst), webEnvBody(inst, { federation }), { mode: 0o600, sudo: true });
   else log('    (baked into cloud-init)');
 
   // ── step 4: systemd unit + enable ─────────────────────────────────────────
@@ -950,6 +1166,21 @@ async function provisionInstance(inst, deps) {
     boxExec(`${sudoP}systemctl enable --now ${inst.slug}`);
   } else { log('    (unit baked into cloud-init)'); }
 
+  // ── step 4b: nightly DB backup — dir + consumer-layout timer/service (task 2213) ──
+  // Every instance must be born WITH backups (the task-2210 gap: cloudbongos was
+  // provisioned without any). Create the app-user-owned backup dir, install the
+  // per-instance timer/service (correct db + consumer-layout script path), enable
+  // the timer. Idempotent: `install -d` no-ops on an existing dir, unit writes are
+  // overwrites, `enable --now` is idempotent. Dedicated bakes the same into cloud-init.
+  log('  [backup] create backup dir + install + enable nightly DB backup timer');
+  if (local) {
+    boxExec(`${sudoP}install -d -o ${APP_USER} -g ${APP_USER} -m 0750 ${CONFIG.backupDir}`);
+    boxWriteFile(backupServicePath(inst), backupService(inst), { mode: 0o644, sudo: true });
+    boxWriteFile(backupTimerPath(inst), backupTimer(inst), { mode: 0o644, sudo: true });
+    boxExec(`${sudoP}systemctl daemon-reload`);
+    boxExec(`${sudoP}systemctl enable --now ${backupUnitName(inst)}.timer`);
+  } else { log('    (backup dir + units baked into cloud-init)'); }
+
   // ── step 5: DNS — Cloudflare A-record UPSERT for the instance's domain (P4) ──
   // Formalized in P4 (#1945): the shared box-dns-cloudflare.sh hook UPSERTs an A
   // record pointing the domain at its target IP (recordIp), in the domain's own
@@ -1009,12 +1240,28 @@ async function provisionInstance(inst, deps) {
 // SAME pure command generators so local + dedicated never diverge.
 function dedicatedUserData(inst) {
   const i = { ...inst, db_name: inst.db_name || inst.slug };
+  // task 2213: a dedicated droplet gets the same nightly backup as local shapes —
+  // write the per-instance unit pair (base64-encoded to sidestep YAML block-scalar
+  // escaping of the multi-line bodies), create the app-user-owned backup dir, and
+  // enable the timer alongside the web unit. Mirrors provisionInstance's step 4b.
+  const svcB64 = Buffer.from(backupService(i), 'utf8').toString('base64');
+  const timerB64 = Buffer.from(backupTimer(i), 'utf8').toString('base64');
   return `#cloud-config
+write_files:
+  - path: ${backupServicePath(i)}
+    encoding: b64
+    permissions: '0644'
+    content: ${svcB64}
+  - path: ${backupTimerPath(i)}
+    encoding: b64
+    permissions: '0644'
+    content: ${timerB64}
 runcmd:
   - [ bash, -lc, "${dbCreateCmd(i)} || true" ]
   - [ bash, -lc, "cd ${REPO_ROOT} && ${migrateCmd(i)}" ]
   - [ bash, -lc, "${seedFirstVersionCmd(i)}" ]
-  - [ bash, -lc, "systemctl daemon-reload && systemctl enable --now ${i.slug}" ]
+  - [ bash, -lc, "install -d -o ${APP_USER} -g ${APP_USER} -m 0750 ${CONFIG.backupDir}" ]
+  - [ bash, -lc, "systemctl daemon-reload && systemctl enable --now ${i.slug} ${backupUnitName(i)}.timer" ]
 `;
 }
 
@@ -1034,10 +1281,16 @@ async function teardownInstance(inst, deps) {
   if (inst.hosting_shape !== 'dedicated') {
     boxExec(`${sudoP}systemctl disable --now ${inst.slug}`, { allowFail: true });
     boxExec(`${sudoP}rm -f ${serviceUnitPath(inst)}`, { allowFail: true });
+    // Stop + remove the nightly backup units too (task 2213). The backup DIR + its
+    // dumps are left in place — like the DB below, they are precious data a teardown
+    // must not silently destroy.
+    boxExec(`${sudoP}systemctl disable --now ${backupUnitName(inst)}.timer`, { allowFail: true });
+    boxExec(`${sudoP}rm -f ${backupServicePath(inst)} ${backupTimerPath(inst)}`, { allowFail: true });
     boxExec(`${sudoP}systemctl daemon-reload`, { allowFail: true });
-    // DB + Caddy block are left for an explicit operator (data is precious; a
-    // teardown should not silently dropdb). We log the manual follow-ups.
-    log(`  (left for the operator: dropdb ${dbName(inst)}, remove the Caddy block for ${inst.slug})`);
+    // DB + Caddy block + backup dumps are left for an explicit operator (data is
+    // precious; a teardown should not silently dropdb or delete backups). Log the
+    // manual follow-ups.
+    log(`  (left for the operator: dropdb ${dbName(inst)}, remove the Caddy block for ${inst.slug}, prune ${CONFIG.backupDir}/${dbName(inst)}-*.sql.gz)`);
   } else if (apply && deps.doApi && inst.droplet_id) {
     await deps.doApi.deleteDroplet(inst.droplet_id);
   }
@@ -1356,8 +1609,8 @@ async function main() {
   const slug = args[1] && !args[1].startsWith('--') ? args[1] : null;
   if ((cmd === 'provision' || cmd === 'teardown') && !slug) { console.error(`${cmd} needs a <slug>`); process.exit(2); }
 
-  let pool, provisioning, DoApi;
-  try { ({ pool, provisioning, DoApi } = loadDeps()); }
+  let pool, provisioning, DoApi, platformIdentity, hubKeys;
+  try { ({ pool, provisioning, DoApi, platformIdentity, hubKeys } = loadDeps()); }
   catch (e) { console.error(`cannot load DB layer (run this on the control plane): ${e.message}`); process.exit(1); }
 
   // Box-target executor (remote over SSH when PROVISION_REMOTE_HOST is set, else
@@ -1372,6 +1625,9 @@ async function main() {
     writeFile: makeWriteFile({ apply, privileged: CONFIG.privileged, exec, remoteHost: CONFIG.remoteHost }),
     controlWriteFile: makeWriteFile({ apply, privileged: CONFIG.privileged, exec: controlExec }),
     doApi: DoApi ? new DoApi({ dryRun: !apply, token: CONFIG.doToken, log: (m) => console.log('    ' + m) }) : null,
+    // Cross-site identity (ADR 0141 §4). Null on a non-hub control plane → federation
+    // dormant; shouldFederate() then skips and the instance owns its auth (as today).
+    platformIdentity, hubKeys,
   };
 
   let result;
@@ -1396,6 +1652,7 @@ module.exports = {
   CONFIG, MAX_INTENT_ATTEMPTS,
   // pure step generators (tested directly)
   dbName, dbCreateCmd, migrateCmd, seedFirstVersionCmd, serviceUnit, serviceUnitPath, webEnvBody, webEnvPath,
+  backupUnitName, backupServicePath, backupTimerPath, backupScriptPath, backupService, backupTimer,
   standaloneRoot, standalonePullCmd, standaloneInstallCmd, standaloneMigrateCmd,
   // standalone scaffold (ADR 0108 / 0125, task 2055)
   parseTargetRef, instanceRepoRemote, instanceInitSpec, scaffoldStandaloneRepo, coreVersionSafe,
@@ -1406,4 +1663,6 @@ module.exports = {
   cmdRunIntents, cmdReconcile, cmdStatus,
   // GitHub App Manifest flow (task 2080, ADR 0133)
   convertManifestCode, placeManifestCreds, drainOAuthManifests, MANIFEST_UA,
+  // cross-site identity federation (ADR 0141 §4, task #1002109)
+  federationHubOrigin, shouldFederate, federateInstance,
 };

package/scripts/gds/publish-manifest.js

@@ -250,6 +250,21 @@ const INSTANCE_EXCLUDE = [
   'docs/design/container-exterior-tiles.md',
   'docs/design/container-interior.md',
   'docs/design/world-map-scroll.md',
+  // instance-HISTORY ADRs (task 1002219 / audit H5). These record THIS platform-family's own
+  // migration + identity history (the amazonprimea→cloudbongos lift, the standalone reprovision,
+  // the cloudbongos identity hub) — they are inherently full of the prior instance's name/owner and
+  // genericize to nothing (unlike a portable methodology ADR). docs/adr/ is allowlisted wholesale for
+  // the portable decision records; these three stay in this repo and never ship in the core, mirroring
+  // the instance-recipe / game-design carve-outs above. (The portable ADRs + the README index still publish.)
+  'docs/adr/0139-platform-history-migration-to-cloudbongos.md',
+  'docs/adr/0140-cloudbongos-standalone-reprovision.md',
+  'docs/adr/0141-cross-site-identity-federated-hub-idp.md',
+  // hall-preview FIXTURES (task 1002219 / audit H5) — the local hall-UI preview harness's sample
+  // data is a snapshot of THIS instance's builders/goals/tasks (owner login, world name, prior
+  // instance name), pure instance identity. The harness code stays portable; only the OTB data is
+  // carved out, so a consumer core never ships customer-zero's directory. (Fixtures remain in-repo
+  // for local dev — this only affects what package-core publishes.)
+  'scripts/hall-preview/fixtures/',
   'blockers/',
   'limitations/',
   'generative-ideas.md',

package/scripts/gds/run-unit-tests.js

@@ -31,6 +31,10 @@ const { isModuleEnabled } = require('../../src/modules');
 const TESTS_DIR = path.resolve(__dirname, '..', '..', 'tests');
 const MODULES_DIR = path.resolve(__dirname, '..', '..', 'modules');
 const PER_TEST_TIMEOUT_MS = 90_000;
+// Integration tests (package build + `npm install` + a spawned server) are far heavier than a
+// DB-free unit file, so the `--integration` gate (task 1002221 / audit H1) gives each one a much
+// longer budget than the 90s unit cap.
+const INTEGRATION_TIMEOUT_MS = 300_000;
 
 // Feature-module test sets (R59 / task 1198). A test that exercises a feature
 // MODULE runs only when this instance enables that module — a vanilla Cloud
@@ -128,31 +132,50 @@ function discoverModuleTests({ modulesDir = MODULES_DIR, isEnabled = isModuleEna
 }
 
 function main() {
+  // Two gates from one runner (task 1002221 / audit H1):
+  //   default        — the DB-free UNIT gate: every test file MINUS the integration set (+ known-
+  //                     failing / support / disabled-module). Fast, runs in a clean checkout / per PR.
+  //   --integration  — the standing INTEGRATION-SMOKE gate: ONLY the integration set (package build +
+  //                     `npm install` + live boot etc.). Heavier, longer per-test budget; run per
+  //                     release / on a schedule in an env that provides the services (DB/network). This
+  //                     is what promotes tests/consumer_layout_boot.mjs from "excluded + ad-hoc" to a
+  //                     first-class gate a release step can invoke with one command.
+  const integrationMode = process.argv.includes('--integration');
+  const perTestTimeout = integrationMode ? INTEGRATION_TIMEOUT_MS : PER_TEST_TIMEOUT_MS;
+
   const files = fs
     .readdirSync(TESTS_DIR)
     .filter((f) => f.endsWith('.mjs'))
     .map((f) => f.replace(/\.mjs$/, ''))
-    .filter((name) => !INTEGRATION.has(name) && !KNOWN_FAILING.has(name)
-      && !SUPPORT_MODULES.has(name) && !MODULE_DISABLED.has(name))
+    .filter((name) => integrationMode
+      ? (INTEGRATION.has(name) && !KNOWN_FAILING.has(name) && !SUPPORT_MODULES.has(name))
+      : (!INTEGRATION.has(name) && !KNOWN_FAILING.has(name) && !SUPPORT_MODULES.has(name) && !MODULE_DISABLED.has(name)))
     .sort();
 
-  const { included: moduleTests, skippedDisabled: moduleTestsSkipped } = discoverModuleTests();
-
-  const moduleNote = MODULE_DISABLED.size
-    ? ` + ${MODULE_DISABLED.size} disabled-module (${[...MODULE_DISABLED].sort().join(', ')})`
-    : '';
-  const modOwnedSkipNote = moduleTestsSkipped.length
-    ? ` + ${moduleTestsSkipped.length} module-owned test(s) skipped (module disabled: ${[...new Set(moduleTestsSkipped.map((t) => t.key))].sort().join(', ')})`
-    : '';
+  // Module-owned tests are DB-free unit tests — only the default gate runs them.
+  const { included: moduleTests, skippedDisabled: moduleTestsSkipped } = integrationMode
+    ? { included: [], skippedDisabled: [] }
+    : discoverModuleTests();
+
+  if (integrationMode) {
+    console.log(`run-unit-tests --integration: ${files.length} integration-smoke test file(s) (${files.join(', ') || 'none found'}); per-test budget ${INTEGRATION_TIMEOUT_MS / 1000}s`);
+  } else {
+    const moduleNote = MODULE_DISABLED.size
+      ? ` + ${MODULE_DISABLED.size} disabled-module (${[...MODULE_DISABLED].sort().join(', ')})`
+      : '';
+    const modOwnedSkipNote = moduleTestsSkipped.length
+      ? ` + ${moduleTestsSkipped.length} module-owned test(s) skipped (module disabled: ${[...new Set(moduleTestsSkipped.map((t) => t.key))].sort().join(', ')})`
+      : '';
+    console.log(`run-unit-tests: ${files.length + moduleTests.length} DB-free unit test file(s) (${files.length} core + ${moduleTests.length} module-owned; excluded ${INTEGRATION.size} integration + ${KNOWN_FAILING.size} known-failing${moduleNote}${modOwnedSkipNote})`);
+  }
   const total = files.length + moduleTests.length;
-  console.log(`run-unit-tests: ${total} DB-free unit test file(s) (${files.length} core + ${moduleTests.length} module-owned; excluded ${INTEGRATION.size} integration + ${KNOWN_FAILING.size} known-failing${moduleNote}${modOwnedSkipNote})`);
 
   const failures = [];
   const runOne = (displayName, filePath) => {
     try {
       execFileSync(process.execPath, [filePath], {
         stdio: ['ignore', 'ignore', 'pipe'],
-        timeout: PER_TEST_TIMEOUT_MS,
+        timeout: perTestTimeout,
         env: { ...process.env, NODE_ENV: 'test' },
       });
       console.log(`  ok    ${displayName}`);
@@ -168,12 +191,13 @@ function main() {
   for (const name of files) runOne(name, path.join(TESTS_DIR, `${name}.mjs`));
   for (const { key, name, file } of moduleTests) runOne(`${key}/${name}`, file);
 
+  const label = integrationMode ? 'run-unit-tests --integration' : 'run-unit-tests';
   console.log('');
   if (failures.length === 0) {
-    console.log(`run-unit-tests: all ${total} passed.`);
+    console.log(`${label}: all ${total} passed.`);
     process.exit(0);
   }
-  console.log(`run-unit-tests: ${failures.length} FAILED — ${failures.join(', ')}`);
+  console.log(`${label}: ${failures.length} FAILED — ${failures.join(', ')}`);
   process.exit(1);
 }
 

package/scripts/gds/setup.js

@@ -378,6 +378,47 @@ async function promptOnboardingConsent() {
     }
   }
 
+  // Federation (ADR 0141 §1, task #1002108): a HOSTED instance has no GitHub app of
+  // its own — it federates sign-in through the Cloud Bongos hub. If the instance
+  // manifest advertises auth.idp, run the hub device flow + assertion exchange via
+  // the shared login.js runDeviceFlow, then the SAME onboarding prompts. The direct
+  // GitHub device flow below (auth.idp unset) is untouched — the self-hosted default.
+  let idpCfg = null;
+  try {
+    const m = await fetch(`${API_BASE}/api/gds/instance`);
+    const mj = m.ok ? await m.json() : null;
+    idpCfg = (mj && mj.auth && mj.auth.idp) || null;
+  } catch (_) { /* manifest unreachable → fall through to the direct flow */ }
+  if (idpCfg) {
+    console.log('Signing in via the Cloud Bongos platform (hub)...');
+    const { runDeviceFlow } = require('./login');
+    const flow = await runDeviceFlow(API_BASE, { log: console.log, idp: idpCfg });
+    if (flow.state === 'not_approved') {
+      console.error('');
+      console.error('This GitHub account has not been approved yet.');
+      console.error('An Archon must approve your access request before you can enroll.');
+      console.error('  → Ask an Archon to invite you, then re-run /builder-setup.');
+      process.exit(1);
+    }
+    if (flow.state !== 'ok') {
+      console.error(`\nSign-in did not complete (${flow.state}). Re-run /builder-setup.`);
+      process.exit(1);
+    }
+    const { token, builder } = flow;
+    await saveSession({ token, builder, api_base: API_BASE });
+    console.log('');
+    console.log(`Authenticated as ${builder.github_login} (#${builder.id}). Session saved to ${SESSION_PATH}.`);
+    try {
+      const { activate } = require('./install-git-hooks');
+      activate();
+    } catch (_) { /* hook activation is best-effort */ }
+    await promptGeminiKey();
+    await promptAnthropicLink();
+    await promptDisciplines();
+    await promptOnboardingConsent();
+    process.exit(0);
+  }
+
   console.log('Starting GitHub Device Flow...');
   const start = await (await cliClient()).auth.postAuthDeviceStart();
   if (!start.ok) {