mindforge-cc 11.9.2 → 11.9.3

package/bin/governance/approval-record.js

@@ -0,0 +1,147 @@
+'use strict';
+/**
+ * Canonical approval-record integrity, shared by the writer and every verifier.
+ *
+ * WHY THIS EXISTS — what the old record actually proved: nothing.
+ *
+ * bin/governance/approve.js stamped
+ *     signature = sha256(`${id}:${reason}:${timestamp}:${os.hostname()}`)
+ * and called it a signature. Three problems, all measured:
+ *
+ *   1. It is NOT a signature. Nothing signs it; there is no key and no asymmetry. Anyone who
+ *      can write the file can compute the value.
+ *   2. It is UNVERIFIABLE by design. `os.hostname()` is part of the preimage but is NOT a field
+ *      of the record, so a verifier holding the record cannot reproduce the digest. CI never
+ *      could have checked it.
+ *   3. Nothing checked it anyway. control-plane.yml asserted `!rec.signature` — presence only.
+ *
+ * So the field was simultaneously misnamed, uncheckable and unchecked. It is replaced by
+ * `record_checksum`: a plain SHA-256 over the record's OWN canonical fields, which any holder
+ * can recompute. That makes it a real tamper-check on the record's contents — and nothing more,
+ * which is why it is not called a signature.
+ *
+ * WHAT THIS DOES NOT PROVIDE. A checksum over a git-tracked file is an INTEGRITY control, never
+ * an AUTHORIZATION one: anyone with push access can mint a fresh record with a valid checksum.
+ * Authorization on this repo comes from branch protection (a required PR plus required status
+ * checks on main and develop), not from a file. Verified live before this was written:
+ * `branches/{main,develop}/protection` returned 404 and `rulesets` was empty, so for the whole
+ * period this record format existed there was no enforcement layer of any kind behind it.
+ *
+ * The construction deliberately mirrors bin/governance/audit-hash.js — twelve lines, one
+ * function, used by writer and verifier alike. That module's discipline ("MUST be the single
+ * source of truth for both") is exactly what kept the audit chain honest while this record rotted,
+ * so it is copied rather than reinvented.
+ */
+
+const crypto = require('crypto');
+
+/** Field written last and excluded from its own digest. */
+const CHECKSUM_FIELD = 'record_checksum';
+
+/** Current record schema. A record without it is a pre-v2 record and is not accepted. */
+const SCHEMA = 'mindforge.approval/v2';
+
+/** How long a recorded acknowledgement stays current. */
+const TTL_HOURS = 72;
+
+/**
+ * SHA-256 over the record's own fields, with the checksum field removed.
+ *
+ * Determinism note: like audit-hash.js this relies on JSON.stringify emitting keys in insertion
+ * order, which is why writer and verifier MUST both go through this function. A verifier that
+ * rebuilt the object literal in a different order would compute a different digest and reject
+ * every valid record — so do not inline this construction anywhere, including in YAML.
+ *
+ * @param {object} record
+ * @returns {string} `sha256:<hex>`
+ */
+function checksumRecord(record) {
+  const material = { ...record };
+  delete material[CHECKSUM_FIELD];
+  return `sha256:${crypto.createHash('sha256').update(JSON.stringify(material)).digest('hex')}`;
+}
+
+/** ISO timestamp `hours` after `fromIso`. */
+function expiryFrom(fromIso, hours = TTL_HOURS) {
+  return new Date(new Date(fromIso).getTime() + hours * 3600 * 1000).toISOString();
+}
+
+const REQUIRED_FIELDS = ['schema', 'id', 'project', 'version', 'tier', 'approved_by', 'timestamp', 'expires_at', 'reason', 'identity_verification'];
+
+/**
+ * Check one approval record's integrity and currency.
+ *
+ * This answers "is this record intact, and is it about the release being built?" It does NOT
+ * answer "was this change authorized" — see the header.
+ *
+ * The currency checks are the ones that matter in practice. A record with no expiry and no
+ * version binding satisfied the old gate in perpetuity: the committed approval was minted
+ * 2026-06-11 for version 11.5.1 and was still accepted 67 days and 286 commits later, against
+ * 11.9.2, because the gate read only the directory's contents.
+ *
+ * @param {object} record
+ * @param {{currentVersion:string, now?:Date}} ctx
+ * @returns {{ok:boolean, problems:string[], stale:boolean}}
+ */
+function verifyRecord(record, ctx) {
+  const problems = [];
+  let stale = false;
+
+  if (!record || typeof record !== 'object') {
+    return { ok: false, problems: ['record is not a JSON object'], stale: false };
+  }
+
+  if (record.schema !== SCHEMA) {
+    problems.push(
+      record.signature && !record.schema
+        ? 'pre-v2 record (has the removed `signature` field, no `schema`). Its digest included ' +
+          'os.hostname(), which is not a field of the record, so it can never be verified. Re-mint it.'
+        : `unknown schema ${JSON.stringify(record.schema)} — expected ${SCHEMA}`);
+  }
+
+  for (const f of REQUIRED_FIELDS) {
+    if (record[f] === undefined || record[f] === null || record[f] === '') {
+      problems.push(`missing required field \`${f}\``);
+    }
+  }
+
+  if (record[CHECKSUM_FIELD]) {
+    const expected = checksumRecord(record);
+    if (record[CHECKSUM_FIELD] !== expected) {
+      problems.push(`${CHECKSUM_FIELD} does not match the record contents — it has been edited since minting`);
+    }
+  } else {
+    problems.push(`missing \`${CHECKSUM_FIELD}\``);
+  }
+
+  const iv = record.identity_verification;
+  const isVerified = iv && iv.verified === true;
+  const isAckedUnverified = iv && iv.verified === false
+    && iv.method === 'git_identity_unverified' && iv.unverified_ack === true;
+  if (!isVerified && !isAckedUnverified) {
+    problems.push('identity is neither GPG-verified nor an explicitly acknowledged unverified ' +
+      'approval (verified:false + method git_identity_unverified + unverified_ack:true)');
+  }
+
+  // Currency. Reported separately from malformedness because a stale record is a correctly-made
+  // record that has simply stopped applying — a different thing from a corrupt one.
+  if (record.version && ctx.currentVersion && record.version !== ctx.currentVersion) {
+    stale = true;
+    problems.push(`records version ${record.version} but the build is ${ctx.currentVersion} — ` +
+      'an approval does not carry forward to a later release');
+  }
+  const now = ctx.now || new Date();
+  if (record.expires_at) {
+    const exp = new Date(record.expires_at);
+    if (Number.isNaN(exp.getTime())) problems.push(`expires_at is not a valid date: ${record.expires_at}`);
+    else if (exp <= now) {
+      stale = true;
+      const ageH = Math.round((now - exp) / 3600000);
+      problems.push(`expired ${ageH}h ago (expires_at ${record.expires_at})`);
+    }
+  }
+
+  return { ok: problems.length === 0, problems, stale };
+}
+
+module.exports = { checksumRecord, verifyRecord, expiryFrom, CHECKSUM_FIELD, SCHEMA, TTL_HOURS, REQUIRED_FIELDS };

package/bin/governance/approve.js

@@ -8,9 +8,8 @@
 
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
-const crypto = require('crypto');
 const { execFileSync } = require('child_process');
+const { checksumRecord, expiryFrom, SCHEMA } = require('./approval-record');
 
 const ROOT = path.resolve(__dirname, '../../');
 const APPROVALS_DIR = path.join(ROOT, '.planning/approvals');
@@ -90,21 +89,27 @@ function approve(opts = {}) {
   // Verify approver identity — THROWS fail-closed if unverifiable (before any write).
   const identityVerification = verifyApproverIdentity(approver);
 
-  const signature = crypto.createHash('sha256')
-    .update(`${id}:${reason}:${timestamp}:${os.hostname()}`)
-    .digest('hex');
-
+  // The old `signature` field was sha256(id:reason:timestamp:os.hostname()). It was not a
+  // signature (nothing signs it), it could not be verified by anyone holding the record
+  // (hostname is not a field of it), and the only consumer asserted its PRESENCE. Replaced by a
+  // recomputable checksum over the record's own fields — see bin/governance/approval-record.js.
+  //
+  // `expires_at` is new and load-bearing: without it, the record committed on 2026-06-11 for
+  // version 11.5.1 still satisfied the Tier-3 gate 67 days and 286 commits later, against
+  // 11.9.2. An acknowledgement now stops applying, and it does not carry to a later release.
   const record = {
+    schema: SCHEMA,
     id,
     project: pkg.name,
     version: pkg.version,
     tier: 3,
     approved_by: approver,
     timestamp,
+    expires_at: expiryFrom(timestamp),
     reason,
-    signature: `sha256:${signature}`,
     identity_verification: identityVerification
   };
+  record.record_checksum = checksumRecord(record);
 
   if (!fs.existsSync(approvalsDir)) fs.mkdirSync(approvalsDir, { recursive: true });
   const filename = `approval-${id.toLowerCase()}.json`;

package/bin/governance/policy-engine.js

@@ -74,7 +74,17 @@ class PolicyEngine {
           
           // [PQAS] v7: Hardened Biometric Bypass for Risk > 95
           if (impactScore > 95) {
-            const gateResult = await policyGate.evaluateBypass(intent, impactScore);
+            // The gate looks up the attestation by `intent.requestId`, which this method never
+            // set — it generated `requestId` as a local and passed the bare intent, so the lookup
+            // always received undefined. Measured: orbital-guardian returns
+            // {verified:false, reason:"missing requestId"}, so the attestation path could NEVER
+            // approve, even immediately after a successful recordBypass(). The gate was stuck
+            // closed, which is safe but means the whole hardware-attestation feature only ever
+            // denied. tests/v8-orbital-governance.test.js passes an object that DOES carry
+            // requestId, which is why the contract looked satisfied.
+            //
+            // A new object rather than a mutation: the caller's intent is not ours to modify.
+            const gateResult = await policyGate.evaluateBypass({ ...intent, requestId }, impactScore);
             if (gateResult.status === 'WAIT_FOR_BIOMETRIC' || gateResult.status === 'WAIT_FOR_ORBITAL') {
               verdict = { 
                 verdict: 'DENY', 
@@ -86,8 +96,28 @@ class PolicyEngine {
               this.logAudit(intent, impactScore, verdict);
               return verdict;
             }
-            console.log(`[PQAS-GATE] [${requestId}] Biometric signature verified. Proceeding with high-risk mutation.`);
-            verdict = { verdict: 'PERMIT', reason: `Authorized via Biometric Bypass [${gateResult.signature || 'WEB-AUTHN-DEX'}]`, requestId };
+            // Only claim an attestation when one was actually verified. evaluateBypass has TWO
+            // non-WAIT returns, and they mean opposite things: an attestation verified in the
+            // enclave (carries attestation_id), or "Impact within standard threshold" — which
+            // states that no attestation was required. The old code logged "Biometric signature
+            // verified" and recorded the audit reason "Authorized via Biometric Bypass
+            // [WEB-AUTHN-DEX]" for BOTH, so the audit trail would assert a biometric verification
+            // for an operation the gate had explicitly waved through unchecked. That is the audit
+            // equivalent of a gate printing success without running.
+            const attested = Boolean(gateResult.attestation_id);
+            if (attested) {
+              console.log(`[PQAS-GATE] [${requestId}] Hardware attestation ${gateResult.attestation_id} verified. Proceeding with high-risk mutation.`);
+            } else {
+              console.log(`[PQAS-GATE] [${requestId}] Gate returned ${gateResult.status} without an attestation: ${gateResult.reason}. NOT recording this as attested.`);
+            }
+            verdict = {
+              verdict: 'PERMIT',
+              reason: attested
+                ? `Authorized via hardware attestation [${gateResult.attestation_id}]`
+                : `Permitted without attestation: ${gateResult.reason || gateResult.status}`,
+              requestId,
+              attested,
+            };
             this.logAudit(intent, impactScore, verdict);
             return verdict;
           }

package/bin/governance/policy-gate-hardened.js

@@ -12,7 +12,42 @@ const configManager = require('../governance/config-manager');
 class PolicyGateHardened {
   constructor() {
     // bypasses.json deprecated in favor of orbital.attestations table (v8)
-    this.criticalThreshold = configManager.get('governance.critical_drift_threshold', 95); 
+    // Impact scores are 0-100. This used to read `governance.critical_drift_threshold` with a
+    // default of 95 — but that key is a DRIFT RATIO, read by bin/engine/logic-drift-detector.js:23
+    // with a default of 0.50, and the shipped config sets it to 0.5. One key, two incompatible
+    // scales: the drift detector was correct and this gate silently received 0.5 where it expected
+    // ~95, making the "within standard threshold" branch below permanently dead.
+    //
+    // Dead was the SAFE direction, but it is one plausible edit from the unsafe one: raising that
+    // key to 95 to "fix" this gate would return ALLOWED for every high-risk score AND break drift
+    // detection, and policy-engine.js would then log "Biometric signature verified" for an
+    // operation where no attestation was ever attempted. Hence a dedicated key, plus a range guard
+    // so a ratio can never be mistaken for a score again.
+    this.criticalThreshold = this.resolveImpactThreshold();
+  }
+
+  /**
+   * The impact score (0-100) at or below which no hardware attestation is demanded.
+   *
+   * Rejects anything that is not on the 0-100 scale rather than trusting it. A value of 0.5 is a
+   * ratio that somebody has pointed at the wrong knob, and silently accepting it is how this gate
+   * came to compare a drift ratio against an impact score.
+   *
+   * @returns {number}
+   */
+  resolveImpactThreshold(fallback = 95) {
+    const raw = configManager.get('governance.critical_impact_threshold', fallback);
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 1 || value > 100) {
+      // Deliberately loud: a mis-scaled threshold changes whether high-risk mutations demand
+      // attestation at all, so it must not be absorbed quietly.
+      console.warn(
+        `[ORBITAL-GATE] governance.critical_impact_threshold=${JSON.stringify(raw)} is not an ` +
+        'impact score on the 0-100 scale (a value below 1 is usually a drift RATIO pointed at the ' +
+        `wrong key). Using ${fallback}.`);
+      return fallback;
+    }
+    return value;
   }
 
   /**

package/bin/governance/verify-approvals.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Verify the integrity of every committed approval record, and disclose Tier-3 changes.
+ *
+ * Usage:
+ *   node bin/governance/verify-approvals.js [--tier N] [--dir <path>] [--json]
+ *
+ * Exit 0 = every record is intact and current (or there are none).
+ * Exit 1 = at least one record is malformed, tampered with, or stale.
+ *
+ * WHAT REPLACED WHAT, and why the contract changed.
+ *
+ * The previous gate lived inline in control-plane.yml and asked: "does .planning/approvals/
+ * contain at least one file that clears an identity bar?" Measured, that question has three
+ * fatal properties:
+ *
+ *   * It is a pure function of the DIRECTORY, not of the change. Running the identical script in
+ *     a temp dir containing only the committed approval — with no git repository at all — exited
+ *     0 with the same success message.
+ *   * It therefore granted approval in perpetuity. One record, committed 2026-06-11 for version
+ *     11.5.1, satisfied it for 67 days and 286 commits, against 11.9.2.
+ *   * It was committed in c6ec9a9 — the SAME commit that relaxed the gate to accept it.
+ *
+ * So the old step could not distinguish an approved change from an unapproved one. This script
+ * does not try to fix that by making the file mean more, because a git-tracked file cannot carry
+ * authorization: anyone who can push can write one, and MINDFORGE_ALLOW_UNVERIFIED_APPROVAL=1
+ * makes minting a one-liner. Verified live: before branch protection was enabled,
+ * `branches/{main,develop}/protection` returned 404 and `rulesets` was empty, so nothing stood
+ * behind the gate at all.
+ *
+ * The honest split, and what each half is worth:
+ *
+ *   INTEGRITY (enforced here, can fail). Records must be well-formed, checksum-consistent,
+ *   honestly marked as to identity, bound to the release being built, and unexpired. This is
+ *   what stops a record being edited after the fact or recycled across releases, and it runs on
+ *   EVERY build rather than only Tier-3 ones — a corrupt record is corrupt regardless of tier.
+ *
+ *   AUTHORIZATION (not enforced here, deliberately). Enforced by branch protection: a required
+ *   pull request plus required status checks on main and develop. On a Tier-3 change with no
+ *   current acknowledgement this script DISCLOSES loudly and exits 0, rather than blocking. That
+ *   is a deliberate choice: 28% of recent commits touch the trust surface, and blocking them
+ *   behind a self-issued file would add friction proportional to nothing. Overstating a check is
+ *   how the previous gate came to be trusted for two months while proving nothing.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { verifyRecord } = require('./approval-record');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+function parseArgs(argv) {
+  const out = { tier: null, dir: path.join(ROOT, '.planning', 'approvals'), json: false };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--tier') out.tier = String(argv[++i] ?? '').trim();
+    else if (argv[i] === '--dir') out.dir = argv[++i];
+    else if (argv[i] === '--json') out.json = true;
+  }
+  return out;
+}
+
+/** GitHub Actions annotations when running there; plain text otherwise. */
+const inActions = () => Boolean(process.env.GITHUB_ACTIONS);
+function notice(msg) { console.log(inActions() ? `::notice::${msg}` : msg); }
+function error(msg) { console.error(inActions() ? `::error::${msg}` : msg); }
+function summary(lines) {
+  const f = process.env.GITHUB_STEP_SUMMARY;
+  if (!f) return;
+  try { fs.appendFileSync(f, `${lines.join('\n')}\n`); } catch { /* summary is best-effort */ }
+}
+
+function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  const currentVersion = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version;
+
+  let files = [];
+  try {
+    files = fs.readdirSync(args.dir).filter((f) => f.endsWith('.json'));
+  } catch {
+    files = []; // an absent directory is not an error — it means no acknowledgements exist
+  }
+
+  const results = [];
+  for (const f of files) {
+    const p = path.join(args.dir, f);
+    let rec;
+    try { rec = JSON.parse(fs.readFileSync(p, 'utf8')); }
+    catch (e) {
+      results.push({ file: f, ok: false, stale: false, problems: [`not valid JSON: ${e.message}`] });
+      continue;
+    }
+    results.push({ file: f, ...verifyRecord(rec, { currentVersion }) });
+  }
+
+  const broken = results.filter((r) => !r.ok);
+  const valid = results.filter((r) => r.ok);
+
+  if (args.json) {
+    console.log(JSON.stringify({ currentVersion, tier: args.tier, results }, null, 2));
+  } else {
+    for (const r of broken) {
+      error(`approval ${r.file} is not usable:`);
+      for (const p of r.problems) console.error(`    - ${p}`);
+    }
+    for (const r of valid) notice(`approval ${r.file} is intact and current (${currentVersion}).`);
+  }
+
+  if (broken.length) {
+    error(`${broken.length} approval record(s) rejected. Remove the stale file, or re-mint with ` +
+      '`node bin/governance/approve.js "<reason>"`. A record does not carry forward to a later release.');
+    summary([
+      '## 🔴 Approval record integrity failed',
+      '',
+      ...broken.flatMap((r) => [`**${r.file}**`, ...r.problems.map((p) => `- ${p}`), '']),
+    ]);
+    return 1;
+  }
+
+  if (!results.length) notice('No approval records present — nothing to verify.');
+
+  // Tier-3 disclosure. Never blocks — see the header.
+  if (args.tier === '3') {
+    if (valid.length) {
+      notice(`Tier 3 change with ${valid.length} current acknowledgement(s) on record.`);
+      summary([
+        '## ⚖️ Tier 3 change — acknowledged',
+        '',
+        ...valid.map((r) => `- \`${r.file}\``),
+        '',
+        'Recorded acknowledgement only. Authorization is enforced by branch protection ' +
+        '(required PR + required checks), not by this file.',
+      ]);
+    } else {
+      notice('Tier 3 change with NO recorded acknowledgement. Not blocking — see the summary.');
+      summary([
+        '## ⚖️ Tier 3 change — touches the trust surface',
+        '',
+        'This change modifies a sensitive path (auth/payment/security, `bin/governance/`, ',
+        '`bin/security/`, hook registration, workflows or the approval records themselves) ',
+        'and there is **no current acknowledgement** in `.planning/approvals/`.',
+        '',
+        '**This check does not block it, on purpose.** A git-tracked approval file cannot carry ',
+        'authorization: anyone who can push can write one.',
+        '',
+        'Authorization comes from branch protection — a required pull request plus required ',
+        'status checks on `main` and `develop`.',
+        '',
+        'To record a human acknowledgement (integrity-checked, 72h, bound to this release):',
+        '',
+        '```bash',
+        'node bin/governance/approve.js "what you reviewed and why it is safe"',
+        '```',
+      ]);
+    }
+  }
+
+  return 0;
+}
+
+module.exports = { main, parseArgs };
+
+if (require.main === module) process.exit(main());