@bongos/core 1.17.0

package/scripts/gds/hooks/pre-push.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// scripts/gds/hooks/pre-push.js — client-side push gate (SEC #863).
+//
+// Installed as .git/hooks/pre-push by scripts/gds/install-git-hooks.js (run from
+// /builder-setup). This is LAYER 1 of the #863 fix — fast, cooperative, blocks
+// the honest builder before a bad push ever leaves the machine. It is NOT a
+// trust boundary on its own (a builder can `git push --no-verify` or delete the
+// hook); the authoritative net is the post-push main audit + the deploy-side
+// gate (scripts/gds/main-audit.js, LAYER 3), which read the REAL git history and
+// REAL builder ranks server-side. Layer 1 exists so the common case never even
+// gets that far.
+//
+// Two rules:
+//   1. NOBODY pushes refs/heads/main directly. Under Option A (ADR 0043) the
+//      GDS lands graded work; a builder pushing main bypasses the grader, the
+//      confirm gate, parallel-safety, and credits — exactly the #863 incident.
+//      Override for the server/operator deploy identity only: OTB_ALLOW_MAIN_PUSH=1.
+//   2. A builder BELOW Metic may not push a diff that touches a permission-
+//      sensitive path (rank / permission / ship-grade / deploy / migration
+//      machinery — see src/bongos/permission-path-check.js).
+//
+// git invokes pre-push with argv: <remoteName> <remoteURL>, and feeds the refs
+// being pushed on STDIN, one per line: "<localRef> <localSha> <remoteRef> <remoteSha>".
+
+'use strict';
+
+const { execSync } = require('node:child_process');
+const path = require('node:path');
+
+const ppc = require(path.join(__dirname, '..', '..', '..', 'src', 'bongos', 'permission-path-check.js'));
+const { apiCall } = require(path.join(__dirname, '..', 'cli-lib.js'));
+
+const ZERO = /^0+$/;
+const MAIN_REF = 'refs/heads/main';
+
+function git(args) {
+  try {
+    return execSync(`git ${args}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch (_) {
+    return '';
+  }
+}
+
+// Files changed in a push line. New-branch pushes (remoteSha all-zero) diff
+// against origin/main so we see what the branch ADDS, not its whole history.
+function changedFilesFor(localSha, remoteSha) {
+  if (ZERO.test(localSha)) return []; // branch deletion — nothing to inspect
+  let range;
+  if (ZERO.test(remoteSha)) {
+    const base = git('rev-parse --verify --quiet origin/main') || git('rev-parse --verify --quiet main');
+    range = base ? `${base}...${localSha}` : localSha;
+  } else {
+    range = `${remoteSha}..${localSha}`;
+  }
+  const out = git(`diff --name-only ${range}`);
+  return out ? out.split('\n').map((s) => s.trim()).filter(Boolean) : [];
+}
+
+// #863-followup (finding #15): cli-lib's apiCall uses a bare fetch with no
+// timeout, so a slow/hung GDS API would block EVERY legit push that touches a
+// protected path (the hook awaits liveRank before deciding). Cap it: if /me
+// doesn't answer within LIVE_RANK_TIMEOUT_MS, treat rank as unknown — the
+// caller then warns-and-allows (the post-push main audit is the fail-closed
+// net), so a flaky API degrades to "audit catches it" rather than "nobody can
+// push."
+const LIVE_RANK_TIMEOUT_MS = 4000;
+
+async function liveRank() {
+  try {
+    const timeout = new Promise((resolve) => setTimeout(() => resolve('__timeout__'), LIVE_RANK_TIMEOUT_MS));
+    const res = await Promise.race([
+      apiCall('GET', '/api/gds/me', null, { allowUnauthenticated: true }),
+      timeout,
+    ]);
+    if (res === '__timeout__') {
+      console.error(`\n\x1b[33m⚠ permission gate: GDS /me did not respond within ${LIVE_RANK_TIMEOUT_MS}ms — treating rank as unknown.\x1b[0m`);
+      return null;
+    }
+    if (res && res.ok) return res.data?.builder?.rank ?? null;
+  } catch (_) { /* offline / no session */ }
+  return null;
+}
+
+function block(lines) {
+  console.error('\n\x1b[31m✖ push blocked by the Off the Boats permission gate (SEC #863)\x1b[0m');
+  for (const l of lines) console.error('  ' + l);
+  console.error('');
+  process.exit(1);
+}
+
+async function run() {
+  // The operator / server deploy identity is the ONLY thing allowed to push
+  // main, and it sets this env explicitly. (Belt-and-braces; under full Option A
+  // builders never push main at all.)
+  const allowMain = process.env.OTB_ALLOW_MAIN_PUSH === '1';
+
+  const stdin = require('node:fs').readFileSync(0, 'utf8');
+  const refs = stdin.split('\n').map((l) => l.trim()).filter(Boolean).map((l) => {
+    const [localRef, localSha, remoteRef, remoteSha] = l.split(/\s+/);
+    return { localRef, localSha, remoteRef, remoteSha };
+  });
+  if (refs.length === 0) process.exit(0); // nothing to push
+
+  // Rule 1: no direct push to main.
+  if (!allowMain) {
+    for (const r of refs) {
+      if (r.remoteRef === MAIN_REF && !ZERO.test(r.localSha)) {
+        block([
+          'Direct pushes to `main` are not allowed.',
+          'The GDS lands graded work for you: run `/builder-ship` on your claimed task.',
+          'A direct push to main skips the grader, the confirm gate, parallel-safety, and',
+          'credits — this is exactly the breach SEC #863 closes (ADR 0043).',
+          '',
+          '(Operator/deploy identity only: set OTB_ALLOW_MAIN_PUSH=1 to override.)',
+        ]);
+      }
+    }
+  }
+
+  // Rule 2: a sub-Metic builder may not push permission-sensitive paths.
+  const allChanged = new Set();
+  for (const r of refs) {
+    for (const f of changedFilesFor(r.localSha, r.remoteSha)) allChanged.add(f);
+  }
+  const changedFiles = [...allChanged];
+  const protectedHits = ppc.matchProtected(changedFiles);
+  if (protectedHits.length === 0) process.exit(0); // nothing sensitive — fast path
+
+  const rank = await liveRank();
+  if (rank === null) {
+    // Couldn't resolve rank (offline / no session). Warn but allow — the
+    // post-push main audit (layer 3) re-checks with the real DB rank and is the
+    // fail-closed enforcement. We do NOT hard-block here to avoid bricking a
+    // Metic/Archon working offline.
+    console.error('\n\x1b[33m⚠ permission gate: could not confirm your rank (offline or no GDS session).\x1b[0m');
+    console.error('  This push touches permission-sensitive paths:');
+    for (const h of protectedHits.slice(0, 10)) console.error(`    - ${h.file}`);
+    console.error('  Allowing the push; the server-side audit will re-check with your real rank.\n');
+    process.exit(0);
+  }
+
+  const result = ppc.checkPermissionPaths({ changedFiles, builderRank: rank });
+  if (result.hardFail) {
+    block([
+      `Your rank '${rank}' is below Metic and may not modify permission-sensitive surfaces:`,
+      ...protectedHits.slice(0, 12).map((h) => `  - ${h.file}  (matches ${h.glob})`),
+      '',
+      'These files define the rank ladder, the trust boundary, the ship/grade gates,',
+      'the deploy path, and DB migrations. If a change here is genuinely needed,',
+      'raise it with an Archon — do not edit it from a sandbox/newcomer rank (ADR 0016, ADR 0043).',
+    ]);
+  }
+  process.exit(0);
+}
+
+// Only run when invoked directly (the husky wrapper does `node pre-push.js`).
+// Requiring this file (e.g. a test importing matchProtected logic) must NOT
+// read stdin or call process.exit.
+if (require.main === module) {
+  run().catch((e) => {
+    // A hook crash must not silently allow a bad push of protected paths, but it
+    // also must not brick all pushes on an unrelated bug. Fail OPEN with a loud
+    // warning — the post-push audit remains the fail-closed net.
+    console.error(`\n⚠ permission pre-push hook errored (${e.message}); allowing push. The server-side audit still applies.\n`);
+    process.exit(0);
+  });
+}
+
+module.exports = { run };

package/scripts/gds/http-api-client.js

@@ -0,0 +1,88 @@
+// scripts/gds/http-api-client.js — the shared skeleton behind the control plane's
+// two JSON-over-HTTP clients: scripts/gds/do-api.js (DoApi, DigitalOcean) and
+// scripts/gds/cf-tunnel.js (CfTunnelApi, Cloudflare). Both are thin, injectable-
+// transport, dry-run-by-default wrappers with a byte-identical request skeleton
+// (do-api.js's design note: the box subsystem keeps "ONE shape for every external
+// API"). This base IS that one shape.
+//
+// The genuine per-API differences stay in the subclasses via three small hooks:
+//   - the constructor's OWN live-mode validation (the "missing X" messages and the
+//     order they fire in differ, and tests assert both);
+//   - requestInit() — extra fetch options (Cloudflare pins an IPv4 dispatcher,
+//     #771; DigitalOcean sends none);
+//   - detectError() — what counts as a failure + how the message is extracted
+//     (DigitalOcean = non-2xx → message/id; Cloudflare also fails the {success:false}
+//     envelope and joins errors[]).
+//
+// Behaviour-neutral extraction: pinned by tests/boxes.mjs (DoApi) and
+// tests/cf_tunnel.mjs (CfTunnelApi).
+
+// Build a distinct, named API-error class. Each client makes its own so the
+// `instanceof` checks the tests rely on (DoApiError vs CfApiError) stay meaningful
+// and the `.name` / `.code` carried on every thrown error survive unchanged.
+function makeApiError(name, code) {
+  return class ApiError extends Error {
+    constructor(message, { status, body } = {}) {
+      super(message);
+      this.name = name;
+      this.code = code;
+      this.status = status ?? null;
+      this.body = body ?? null;
+    }
+  };
+}
+
+class JsonHttpApi {
+  // opts: { token, dryRun=true, fetchImpl=globalThis.fetch, base, log }
+  // config: { base, logTag, ErrorClass } — per-client constants supplied by super().
+  // Subclasses run their OWN live-mode validation AFTER super().
+  constructor(opts = {}, { base, logTag, ErrorClass } = {}) {
+    this.dryRun = opts.dryRun !== false; // default ON — live requires opt-in
+    this.token = opts.token || null;
+    this.base = opts.base || base;
+    this.fetchImpl = opts.fetchImpl || globalThis.fetch;
+    this.log = opts.log || (() => {});
+    this._logTag = logTag;
+    this._ErrorClass = ErrorClass;
+  }
+
+  // Extra fetch init merged into every LIVE request. Base sends none; CfTunnelApi
+  // overrides to pin the IPv4 dispatcher (its token is IP-locked, #771).
+  requestInit() { return {}; }
+
+  // Inspect a completed response. Return an error MESSAGE string to throw, or null
+  // to accept. Base fails on a non-2xx HTTP status (DigitalOcean surfaces
+  // message/id); CfTunnelApi also fails the Cloudflare {success:false} envelope.
+  detectError(res, json) {
+    if (!res.ok) return (json && (json.message || json.id)) || `HTTP ${res.status}`;
+    return null;
+  }
+
+  // Core request. In dry-run, never touches the network: log what we WOULD send
+  // and return the caller's synthetic `{ dryRun:true, ...dryRunResult }`.
+  async _req(method, path, body, { dryRunResult } = {}) {
+    if (this.dryRun) {
+      this.log(`[dry-run] ${this._logTag} ${method} ${path}${body ? ' ' + JSON.stringify(body) : ''}`);
+      return { dryRun: true, ...(dryRunResult || {}) };
+    }
+    const res = await this.fetchImpl(`${this.base}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        'Content-Type': 'application/json',
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      ...this.requestInit(),
+    });
+    const text = await res.text();
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON */ }
+    const errMsg = this.detectError(res, json);
+    if (errMsg !== null) {
+      throw new this._ErrorClass(`${this._logTag} ${method} ${path} failed: ${errMsg}`, { status: res.status, body: json });
+    }
+    return json;
+  }
+}
+
+module.exports = { JsonHttpApi, makeApiError };