@bongos/core 1.19.1073 → 1.19.1074

package/scripts/gds/package-core.js

@@ -103,6 +103,7 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..');
 // Reuse — never re-type. The core definition, the redaction, and the tree parser
 // all already exist and are unit-tested at their homes.
 const { isPublishable, PUBLISH_ALLOWLIST } = require(path.join(REPO_ROOT, 'scripts/gds/publish-manifest.js'));
+const { sha256hex, canonicalTreeHash, normalizeMode, octal, tarChecksum, ustarHeader, splitUstarName, buildTar } = require('./artifact-format');
 const {
   buildRedactionRules, collectSensitiveLiterals, findLeaks,
 } = require(path.join(REPO_ROOT, 'scripts/gds/mirror-redact.js'));
@@ -144,9 +145,6 @@ function coreVersion() {
 // Pure helpers (exported for tests — no I/O, no git, no network)
 // ---------------------------------------------------------------------------
 
-function sha256hex(buf) {
-  return crypto.createHash('sha256').update(buf).digest('hex');
-}
 
 // ---------------------------------------------------------------------------
 // CONSUMER-CORE extraction policy (task 1824) — the file-classification layer.
@@ -418,31 +416,8 @@ function prunePackageLock(sourceLock, { name, version, rootRanges, rootDepNames
   };
 }
 
-// The PIN. A canonical, compression-independent digest of the core tree: one
-// "path\0mode\0filesha256\n" line per file, byte-sorted by path. A consumer
-// recomputes this from the unpacked tree to prove an install matches the pin.
-// `files` = [{ path, mode, sha256 }]. Modes are normalized so the pin is stable
-// regardless of the checkout's umask.
-function canonicalTreeHash(files) {
-  const lines = (files || [])
-    .map((f) => `${f.path}\u0000${normalizeMode(f.mode)}\u0000${f.sha256}`)
-    .sort();
-  return sha256hex(Buffer.from(lines.join('\n') + '\n', 'utf8'));
-}
-
-// Collapse ANY mode form — git's 100644/100755, our canonical 0000644/0000755, or a
-// raw filesystem octal string like "755" — to two canonical tar modes, keyed only on
-// the executable bit. IDEMPOTENT (normalizeMode(normalizeMode(x)) === normalizeMode(x))
-// AND exec-aware, so the tree pin reproduces byte-identically whether a consumer
-// recomputes it from the manifest's files[] (already-canonical modes) or from the
-// unpacked tree's stat() modes. Expects a STRING (git mode / canonical mode / octal).
-function normalizeMode(mode) {
-  const s = String(mode);
-  if (s === '100755' || s === '0000755' || s === '755') return '0000755';
-  const n = parseInt(s, 8);
-  if (Number.isFinite(n) && (n & 0o111)) return '0000755';
-  return '0000644';
-}
+// The PIN (canonicalTreeHash) and normalizeMode live in scripts/gds/artifact-format.js
+// (task 1004271) — the module store verifies with the same functions.
 
 // The pin manifest (WITHOUT tarball.* — added by withTarballInfo for the side-car).
 function buildCoreManifest({
@@ -478,94 +453,8 @@ function tarballName(version) { return `${ARTIFACT_NAME}-${version}.tgz`; }
 function manifestName(version) { return `${ARTIFACT_NAME}-${version}.manifest.json`; }
 function stageDirName(version) { return `${ARTIFACT_NAME}-${version}`; }
 
-// ---- a minimal, correct, DETERMINISTIC ustar+gzip writer (node-only, #686) ----
-// Deterministic (fixed mtime/uid/gid, normalized mode, sorted entries) so the same
-// source yields byte-identical bytes — a bonus over the tree_sha256 pin. Long paths
-// use the ustar name/prefix split, falling back to a GNU 'L' longname entry (read
-// by GNU tar, bsdtar/macOS, and node-tar) for the rare path that won't split.
-
-function octal(n, width) {
-  // width-1 octal digits, zero-padded, then a NUL — the classic numeric field.
-  return Buffer.from(n.toString(8).padStart(width - 1, '0').slice(-(width - 1)) + '\0', 'ascii');
-}
-
-function tarChecksum(block) {
-  let sum = 0;
-  for (let i = 0; i < 512; i++) sum += (i >= 148 && i < 156) ? 0x20 : block[i];
-  return sum;
-}
-
-// Build one 512-byte ustar header. `name`/`prefix` must already fit (<=100 / <=155).
-function ustarHeader({ name, prefix = '', mode, size, typeflag }) {
-  const h = Buffer.alloc(512, 0);
-  h.write(name, 0, 100, 'utf8');
-  octal(mode, 8).copy(h, 100);
-  octal(0, 8).copy(h, 108);   // uid
-  octal(0, 8).copy(h, 116);   // gid
-  octal(size, 12).copy(h, 124);
-  octal(0, 12).copy(h, 136);  // mtime = 0 (determinism)
-  h.write(typeflag, 156, 1, 'ascii');
-  h.write('ustar\0', 257, 6, 'ascii');
-  h.write('00', 263, 2, 'ascii');
-  if (prefix) h.write(prefix, 345, 155, 'utf8');
-  // checksum field: 6 octal digits + NUL + space, computed with the field = spaces.
-  const cksum = tarChecksum(h);
-  h.write(cksum.toString(8).padStart(6, '0').slice(-6) + '\0 ', 148, 8, 'ascii');
-  return h;
-}
-
-// Split a >100-byte path into { name<=100, prefix<=155 } at a '/' boundary, or
-// return null if no split fits (→ caller uses the GNU longname fallback).
-function splitUstarName(fullPath) {
-  const bytes = Buffer.byteLength(fullPath, 'utf8');
-  if (bytes <= 100) return { name: fullPath, prefix: '' };
-  // Find the LAST '/' such that the tail (after it) is <=100 and the head <=155.
-  for (let i = fullPath.length - 1; i > 0; i--) {
-    if (fullPath[i] !== '/') continue;
-    const prefix = fullPath.slice(0, i);
-    const name = fullPath.slice(i + 1);
-    if (Buffer.byteLength(name, 'utf8') <= 100 && Buffer.byteLength(prefix, 'utf8') <= 155) {
-      return { name, prefix };
-    }
-  }
-  return null;
-}
-
-function padTo512(buf) {
-  const rem = buf.length % 512;
-  return rem === 0 ? buf : Buffer.concat([buf, Buffer.alloc(512 - rem, 0)]);
-}
-
-// GNU longname pseudo-entry: a header (typeflag 'L', name '././@LongLink') whose
-// BODY is the full path (incl. trailing NUL), immediately followed by the real
-// file entry. Read by GNU tar, bsdtar/macOS, and node-tar.
-function gnuLongName(fullPath) {
-  const payload = Buffer.from(fullPath + '\0', 'utf8');
-  const hdr = ustarHeader({ name: '././@LongLink', mode: 0o644, size: payload.length, typeflag: 'L' });
-  return Buffer.concat([hdr, padTo512(payload)]);
-}
-
-// entries: [{ name, mode, buf }] — `name` includes the TAR_ROOT prefix. Returns a
-// gzip'd tar Buffer. Pure + deterministic given sorted entries.
-function buildTar(entries) {
-  const sorted = [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-  const chunks = [];
-  for (const e of sorted) {
-    const mode = e.mode & 0o7777;
-    const split = splitUstarName(e.name);
-    if (split) {
-      chunks.push(ustarHeader({ name: split.name, prefix: split.prefix, mode, size: e.buf.length, typeflag: '0' }));
-    } else {
-      chunks.push(gnuLongName(e.name));
-      chunks.push(ustarHeader({ name: e.name.slice(0, 100), mode, size: e.buf.length, typeflag: '0' }));
-    }
-    chunks.push(padTo512(e.buf));
-  }
-  // two zero blocks terminate the archive
-  chunks.push(Buffer.alloc(1024, 0));
-  const tar = Buffer.concat(chunks);
-  return zlib.gzipSync(tar, { level: 9 });
-}
+// The ustar+gzip writer (buildTar and its header helpers) lives in
+// scripts/gds/artifact-format.js (task 1004271), shared with the module store.
 
 // ---- the git-LESS source: enumerate the working tree (task 1003995) --------
 //

package/scripts/gds/provision-config.js

@@ -83,7 +83,7 @@ const CONFIG = {
   tag: process.env.PROVISION_TAG || 'cloudbongos-instance',
   doToken: process.env.DO_API_TOKEN || null,
   sshKeyIds: (process.env.BOX_SSH_KEY_IDS || '').split(',').map((s) => s.trim()).filter(Boolean),
-  // The Cloudflare DNS hook (the SAME infra/box-dns-cloudflare.sh box.js uses).
+  // The Cloudflare DNS hook (the instance's infra/box-dns-cloudflare.sh).
   // P4 (#1945) formalizes the UPSERT: point the instance's domain at the target
   // public IP (below), in the domain's OWN Cloudflare zone, proxied=false (see
   // dnsUpsertEnv). No hook configured → DNS is skipped (a co-tenant instance is
@@ -179,7 +179,7 @@ const MANIFEST_VERIFY_TRIES = numEnv('PROVISION_MANIFEST_VERIFY_TRIES', 90);
 const MANIFEST_VERIFY_INTERVAL_MS = numEnv('PROVISION_MANIFEST_VERIFY_INTERVAL_MS', 2000);
 
 // ---------------------------------------------------------------------------
-// Lazy dep load (so --help / arg errors need no Postgres) — the box.js pattern.
+// Lazy dep load (so --help / arg errors need no Postgres).
 // ---------------------------------------------------------------------------
 let _deps;
 function loadDeps() {

package/scripts/gds/provision-net.js

@@ -130,8 +130,7 @@ function dnsUpsertEnv(inst, { publicIp, zone, proxied = false } = {}) {
 }
 
 // The RFC 5737 TEST-NET-1 sentinel a released hostname is parked at (task
-// 1003237) — the shape scripts/gds/box-infra.js proved for a torn-down box
-// (idea 309 / task 1234). 192.0.2.1 is reserved for documentation and is
+// 1003237, first proven in task 1234). 192.0.2.1 is reserved for documentation and is
 // GUARANTEED never routable, so a name parked here can never dial platform
 // infra or a recycled address.
 const DNS_BLACKHOLE_IP = '192.0.2.1';
@@ -141,7 +140,7 @@ const DNS_BLACKHOLE_IP = '192.0.2.1';
 // address UPSERTed at the platform's IP for a project that no longer answers
 // there — the ADR 0181 §2 leak — and this is how the runner lets it go.
 //
-// REPOINT, not delete, for the reason box-infra.js records: deleting a name
+// REPOINT, not delete (task 1234): deleting a name
 // opens an NXDOMAIN window that resolvers negative-cache for the zone's SOA
 // neg-TTL (~30 min, not editable), so a client that queried mid-gap stays
 // broken long after. A name that always resolves — to a guaranteed-dead host —

package/scripts/gds/provision.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // scripts/gds/provision.js — the INSTANCE-provisioning control-plane runner
-// (ADR 0111 §2/§3, BONGOS-V1 goal 32, task #1944). A sibling of box.js.
+// (ADR 0111 §2/§3, BONGOS-V1 goal 32, task #1944).
 //
 // WHAT IT IS. The trust-boundary-safe executor for the `provisioning` module.
 // The internet-facing web tier can only ENQUEUE a provision/teardown intent into
@@ -20,7 +20,7 @@
 //     → Caddy site block + reload
 //     → /healthz
 //
-// DESIGN — inherited from box.js / do-api.js:
+// DESIGN — shared with do-api.js:
 //   • DRY-RUN by DEFAULT. Without --apply, every step only PRINTS the command it
 //     WOULD run and mutates nothing (no DB writes, no shell, no cloud call). The
 //     LIVE leg is an explicit operator/timer `--apply`.
@@ -37,8 +37,8 @@
 //   • The step-command generators are PURE functions (exported) → the SAME command
 //     strings drive local exec (co-tenant) AND the dedicated droplet's cloud-init.
 //
-// This is control-plane ops tooling (scripts/), so — like box.js — it may require
-// the core + a module's data slice directly (a module may not, but a CLI may). It
+// This is control-plane ops tooling (scripts/), so it may require the core + a
+// module's data slice directly (a module may not, but a CLI may). It
 // reuses modules/provisioning/provisioning.js (the intent queue + state) and
 // scripts/gds/do-api.js (the shared DO client extracted in task #1943).
 
@@ -336,7 +336,7 @@ async function provisionInstance(inst, deps) {
   if (inst.hosting_shape === 'dedicated') {
     // Dedicated droplet: create it + settle its public IP via the shared DO client
     // (do-api, dry-run-default). The on-droplet app standup rides cloud-init
-    // user-data built from the SAME step commands below (mirrors box.js). For the
+    // user-data built from the SAME step commands below. For the
     // dry-run plan we surface the intent; --apply creates the droplet.
     const doApi = deps.doApi;
     log('  [server] dedicated droplet');
@@ -1249,8 +1249,8 @@ async function drainOAuthManifests(deps) {
 }
 
 // ---------------------------------------------------------------------------
-// run-intents — drain provisioning_intents (the systemd-timer entry point). The
-// box.js cmdRunIntents shape: dry-run lists the pending queue; --apply claims +
+// run-intents — drain provisioning_intents (the systemd-timer entry point).
+// Dry-run lists the pending queue; --apply claims +
 // executes each, with a poison-attempt cap. FOR UPDATE SKIP LOCKED (in
 // provisioning.claimNextIntent) makes overlapping ticks safe. It ALSO drains the
 // GitHub-App-Manifest conversion queue on the same tick (task 2080).
@@ -1324,8 +1324,8 @@ async function cmdRunIntents(deps) {
 
 // A light drift reconcile: surface instances stuck mid-flight (provisioning /
 // tearing_down) with no open intent — a runner died mid-op. Reports; --apply
-// re-enqueues a fresh intent so the next tick retries. (Full droplet-vs-DB drift,
-// the box.js reconcile-drift analogue, is a later hardening.)
+// re-enqueues a fresh intent so the next tick retries. (Full droplet-vs-DB drift
+// is a later hardening.)
 async function cmdReconcile(deps) {
   const { db, provisioning, log, apply } = deps;
   const { rows } = await db.query(

package/scripts/gds/publish-manifest.js

@@ -68,9 +68,8 @@ const PUBLISH_ALLOWLIST = [
   'modules/hall-ui/',
   'modules/status-ui/',
   'modules/public-landing/', // the front door (task 1003322, ADR 0218) — the repo-root public-landing/ entry this replaces was always here, and for the same reason: default:true, and it is the only thing an instance serves at its apex root. Omit it and a released core answers the game-less 404 tail on its own home page.
-  'modules/dev-box/',
   'modules/discord/',
-  'modules/provisioning/',   // instance-hosting control plane — CORE like its sibling dev-box (same do-api/cf-tunnel toolchain, all core). Reclassified IN so the core CLI scripts/gds/provision.js resolves it from the core package post-split, not a MODULE_NOT_FOUND (task 2135). default:false — shipped ≠ enabled.
+  'modules/provisioning/',   // instance-hosting control plane — CORE (its do-api toolchain is core). Reclassified IN so the core CLI scripts/gds/provision.js resolves it from the core package post-split, not a MODULE_NOT_FOUND (task 2135). default:false — shipped ≠ enabled.
   'modules/agents/',         // the declarative agent registry + spawn seam (goal 1000038) — CORE: its own manifest declares maintenance.status 'core-maintained', and it consumes the core `grade` port, so a released core without it cannot run the MAS machinery the methodology describes. default:false — shipped is not enabled (ADR 0083), exactly like provisioning + platform-identity below. Omitted at module-creation time (tasks 1002485/1002486): the omission was invisible until tests/agents_spawn.mjs became the first PUBLISHABLE file to import it and the R89 boundary guard caught it (task 1002489).
   'modules/npm-release/',    // the deploy page's "where is the work" + version history (task 1002622). default:false — on only in the hall that publishes the core. MUST be here: modules/hall-ui/ ships as one subtree, so a released core without this carries deploy.js's loader and the #nr-work mounts with no routes behind them — the copy-desk asymmetry above.
   'modules/platform-identity/', // hub identity provider (ADR 0141) — ships in core, enabled ONLY on the hub (cloudbongos.com). MUST be here or the hub's enabledModules() throws "unknown module" and provision.js's federation load MODULE_NOT_FOUNDs (task 1002235, same rationale as provisioning above). default:false — shipped ≠ enabled; a vanilla/self-hosted instance never turns it on.

package/scripts/gds/regen-instance-docs.js

@@ -3,7 +3,7 @@
 // regen-instance-docs.js — regenerate a STANDALONE instance's live navigation docs (task 1002314).
 //
 // THE GAP. On the monorepo, the gitignored whole-file navigation docs are regenerated at deploy by
-// scripts/deploy/deploy-prod.sh + infra/box-source-fetch.sh (ADR 0110 §2/§3). STANDALONE instances
+// scripts/deploy/deploy-prod.sh (ADR 0110 §2/§3). STANDALONE instances
 // (ADR 0108 — their own lean repo with @bongos/core vendored) never got that step: their bespoke
 // pull-deploy regenerated NOTHING, so a fresh instance shipped with an empty docs/ and nothing kept
 // the session-log index live. This script is the STANDALONE analogue of deploy-prod.sh's regen block

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

@@ -93,7 +93,7 @@ const INTEGRATION = new Set([
   // DB-free route test can only assert the shape of.
   'community_leaderboard_db',
   'asset_version', 'auth_flow_slice1', 'backfill_sessions', 'bfg', 'bfg_write',
-  'box_connect_e2e', 'box_onboard', 'boxes', 'cf_tunnel', 'cli_token_reissue',
+  'cli_token_reissue',
   // consumer_layout_boot builds the core .tgz, `npm install`s it, and boots a live
   // platform-server (task 2142), then installs the package from its own shipped lockfile,
   // migrates brand-new EMPTY databases and serves a database-backed route from one (task
@@ -398,20 +398,6 @@ function discoverModuleTests({ modulesDir = MODULES_DIR, isEnabled = isModuleEna
 // above, the real repair is for the test to establish the state it needs instead of
 // inheriting whatever ran before it.
 //
-// THE THREE DEV-BOX TESTS ARE PARKED, NOT DELETED, and that reverses a first pass
-// of this task. The owner ruled that dev-box work can go, and boxes / box_onboard /
-// box_connect_e2e were duly deleted — but modules/dev-box/ is still present, still
-// mounted and unmodified by that change, and those files carry the only regression
-// coverage for LIVE guards: the setBoxState column allowlist (SQL injection), the
-// rank/authz floors, the spoofed X-Forwarded-Host that must never reach the served
-// connect.sh, and the authorized_keys command= / embedded-newline rejections.
-// Deleting a security regression test for code that still runs is not retirement,
-// it is removing the alarm and leaving the door. modules/dev-box/CLAUDE.md also
-// still names boxes + box_onboard as that module's required suite, and
-// scripts/gds/smoke-box.sh still invokes all three by path — deleting the files
-// turned that script into an immediate MODULE_NOT_FOUND. They come out when the
-// module does, in the change that removes it.
-//
 // consumer_layout_boot LEFT THIS LIST under task 1002863. Its "missing core tarball" was
 // package-core's fail-closed leak gate reading the lane's throwaway database password (the
 // word postgres, present in hundreds of core files) as a leaked credential and refusing to
@@ -421,7 +407,7 @@ function discoverModuleTests({ modulesDir = MODULES_DIR, isEnabled = isModuleEna
 // now says out loud.
 const INTEGRATION_PARKED = new Set([
   'acclaim_feed_evidence_db',
-  'bfg', 'bfg_write', 'box_connect_e2e', 'box_onboard', 'boxes',
+  'bfg', 'bfg_write',
   'claim_gate_open_blocker', 'claim_gate_rebase',
   'clawback_confirmed_backlog', 'copy_desk_flags_db',
   'government_board_membership_db', 'handle_machinery', 'hub_profile_leak',