@connexum/ai-governance 1.0.0-beta.21 → 1.0.0-beta.22

package/dist/esm/cli/sync.js

@@ -0,0 +1,927 @@
+/**
+ * ai-governance sync — pull the server's signed governance bundle and
+ * re-materialize the local .governance.json to match.
+ *
+ * Design (Thomas, locked):
+ *   - SAFE BY DEFAULT: no arguments = dry-run. Shows diff, writes nothing.
+ *   - --apply (or interactive confirm) writes the new governance to disk.
+ *   - NOT at runtime, NOT at init — a deliberate standalone verb.
+ *   - Client PULLS from server. Server never calls out to the client (Invariant 10).
+ *   - Server unreachable → graceful message, local config unchanged (Invariant 2/3).
+ *   - Unsigned / tampered bundle → REJECTED, nothing written.
+ *
+ * Usage:
+ *   ai-governance sync                   Dry-run: show diff, no writes
+ *   ai-governance sync --apply           Apply the bundle to .governance.json
+ *   ai-governance sync --agent <id>      Sync a specific agent only
+ *   ai-governance sync --gov-server-url  Override gov server URL
+ *
+ * Source of per-agent identities: .governance.json agents[] written by TS-002
+ * (register-fleet + writePerAgentIdentities). Each entry has:
+ *   { localId, agentId, serviceToken, passportId, filePath }
+ * Plus top-level runtime block:
+ *   { govServerUrl, orgId, agentId, serviceToken }
+ *
+ * Follow-up slices (historic seams — see feat/effective-governance-projection-2026-06-08):
+ *   F1: serviceToken TTL reduced to 30d — DONE
+ *   F2: JTI added to minted tokens, persisted on metadata — DONE
+ *   F3: per-agent audit-logger.sh push rewiring (CXNI_AGENT_FILE resolver) — DONE
+ *   F4: serviceToken moved off curl argv via tmpfile — DONE (this file + audit-logger.sh)
+ *   F5: narrower AGENT_SELF role on server for tighter RBAC — DEFERRED (architectural)
+ *
+ * @connexum/ai-governance  TS-010 sync verb
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { spawnSync } from 'child_process';
+// ---------------------------------------------------------------------------
+// Verification helpers
+// ---------------------------------------------------------------------------
+/**
+ * Verify an Ed25519 signature using Node.js built-in crypto.
+ * Signature is base64url; message is the raw 32-byte SHA-256 digest;
+ * publicKey is the 32-byte raw Ed25519 key as base64url.
+ *
+ * Returns true iff the signature is valid.
+ * NEVER throws — returns false on any error (Invariant 2).
+ */
+function verifyEd25519(signatureB64Url, messageBytes, publicKeyB64Url) {
+    try {
+        const sigBytes = Buffer.from(signatureB64Url, 'base64url');
+        const pubKeyBytes = Buffer.from(publicKeyB64Url, 'base64url');
+        if (sigBytes.length !== 64 || pubKeyBytes.length !== 32)
+            return false;
+        // Import the raw 32-byte public key as an Ed25519 KeyObject.
+        // Node.js crypto.createPublicKey only accepts structured formats
+        // (SPKI/JWK). The raw 32 bytes need to be wrapped in an SPKI header.
+        // Ed25519 SPKI prefix (12 bytes): 30 2a 30 05 06 03 2b 65 70 03 21 00
+        const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+        const spkiDer = Buffer.concat([SPKI_PREFIX, pubKeyBytes]);
+        const publicKeyObj = crypto.createPublicKey({
+            key: spkiDer,
+            format: 'der',
+            type: 'spki',
+        });
+        return crypto.verify(null, Buffer.from(messageBytes), publicKeyObj, sigBytes);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * RFC 8785 JSON Canonicalization Scheme — inline minimal implementation.
+ * Used only for verification (matching what the server produced). This avoids
+ * importing from the trust-api package, keeping the CLI self-contained.
+ *
+ * NOTE: for the CLI's verification use-case this is equivalent to the server's
+ * jcsCanonicalize. The test suite verifies byte-identity between the server-side
+ * contentHash and the client-side re-derivation.
+ */
+function jcsCanonicalizeMinimal(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error('jcs: non-finite number');
+        if (value === 0)
+            return '0';
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        // RFC 8785 §3.2.2.2: minimal escaping
+        let out = '"';
+        for (let i = 0; i < value.length; i++) {
+            const c = value.charCodeAt(i);
+            if (c === 0x08) {
+                out += '\\b';
+                continue;
+            }
+            if (c === 0x09) {
+                out += '\\t';
+                continue;
+            }
+            if (c === 0x0a) {
+                out += '\\n';
+                continue;
+            }
+            if (c === 0x0c) {
+                out += '\\f';
+                continue;
+            }
+            if (c === 0x0d) {
+                out += '\\r';
+                continue;
+            }
+            if (c === 0x22) {
+                out += '\\"';
+                continue;
+            }
+            if (c === 0x5c) {
+                out += '\\\\';
+                continue;
+            }
+            if (c < 0x20) {
+                out += '\\u' + c.toString(16).padStart(4, '0');
+                continue;
+            }
+            out += value[i];
+        }
+        return out + '"';
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(jcsCanonicalizeMinimal).join(',') + ']';
+    }
+    if (typeof value === 'object') {
+        const obj = value;
+        const keys = Object.keys(obj).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        const parts = [];
+        for (const k of keys) {
+            const v = obj[k];
+            if (v === undefined)
+                continue;
+            parts.push(jcsCanonicalizeMinimal(k) + ':' + jcsCanonicalizeMinimal(v));
+        }
+        return '{' + parts.join(',') + '}';
+    }
+    throw new Error(`jcs: unsupported type ${typeof value}`);
+}
+// ---------------------------------------------------------------------------
+// Bundle fetch (HTTPS-only via curl — same pattern as rotate-token)
+// ---------------------------------------------------------------------------
+/**
+ * Fetch the governance bundle from the server using curl.
+ * Returns the parsed bundle, or null with a human-readable error.
+ *
+ * Invariant 2/3: server unreachable → returns null gracefully; local config
+ * is NEVER modified on a fetch failure.
+ *
+ * F4 (SECURITY 2026-06-09): serviceToken is passed via a 0600 temp file
+ * (curl -H @<tmpfile>) so it never appears on the process argv (visible in
+ * `ps aux`). The tmpfile is removed immediately after spawnSync returns.
+ * Falls back gracefully when mkdtemp/tmp is unavailable (non-blocking per
+ * Invariant 2) — but logs a warning since the fallback IS less secure.
+ */
+function fetchBundle(govServerUrl, agentId, serviceToken, timeoutSec = 10) {
+    const url = `${govServerUrl.replace(/\/$/, '')}/api/v1/agents/${encodeURIComponent(agentId)}/governance-bundle`;
+    // F4 (SECURITY 2026-06-09): write the Authorization header to a 0600 temp
+    // file so the serviceToken never appears on the process argv. Falls back
+    // gracefully to inline argv header if the tmpfile can't be created (Invariant 2).
+    let authTmpFile = null;
+    try {
+        const tmpDir = process.env['TMPDIR'] || process.env['TMP'] || process.env['TEMP'] || '/tmp';
+        const tmpPath = path.join(tmpDir, `gov-sync-auth-${crypto.randomBytes(8).toString('hex')}.hdr`);
+        fs.writeFileSync(tmpPath, `Authorization: Bearer ${serviceToken}\n`, { mode: 0o600 });
+        try {
+            fs.chmodSync(tmpPath, 0o600);
+        }
+        catch { /* best-effort on Windows */ }
+        authTmpFile = tmpPath;
+    }
+    catch {
+        // CONDITION-2 (Shield 2026-06-09): emit an operator-visible warning so
+        // the degraded path is not silent. The token-on-argv path is functional
+        // but less secure (token visible in `ps aux` to local users).
+        // Non-fatal per Invariant 2 — sync continues.
+        console.warn('[gov-sync] WARNING: auth tmpfile write failed; falling back to token-on-argv (less secure). Check TMPDIR permissions.');
+        authTmpFile = null;
+    }
+    // Build curl args: prefer @tmpfile for Authorization, fall back to inline header.
+    const authArgs = authTmpFile
+        ? ['-H', `@${authTmpFile}`]
+        : ['-H', `Authorization: Bearer ${serviceToken}`];
+    // F4: wrap in try/finally so the tmpfile is always cleaned up, even on
+    // early returns. The token must not persist on disk after the request.
+    try {
+        const result = spawnSync('curl', [
+            '--silent',
+            '--show-error',
+            '--max-time', String(timeoutSec),
+            '--connect-timeout', '5',
+            '--fail-with-body',
+            ...authArgs,
+            '-H', 'Accept: application/json',
+            url,
+        ], { encoding: 'utf8', timeout: (timeoutSec + 5) * 1000 });
+        if (result.status !== 0) {
+            const detail = result.stderr?.trim() || `curl exit ${result.status}`;
+            return { bundle: null, error: `Server request failed: ${detail}` };
+        }
+        if (!result.stdout) {
+            return { bundle: null, error: 'Empty response from server.' };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout);
+        }
+        catch {
+            return { bundle: null, error: 'Could not parse server response as JSON.' };
+        }
+        if (typeof parsed !== 'object' || parsed === null) {
+            return { bundle: null, error: 'Server response is not a JSON object.' };
+        }
+        const obj = parsed;
+        if (typeof obj['error'] === 'string') {
+            return { bundle: null, error: `Server error: ${obj['error']}` };
+        }
+        return { bundle: obj };
+    }
+    catch (err) {
+        return { bundle: null, error: `Request failed: ${err.message}` };
+    }
+    finally {
+        // F4: always clean up the auth tmpfile (contains the serviceToken).
+        if (authTmpFile) {
+            try {
+                fs.unlinkSync(authTmpFile);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}
+/**
+ * Fetch the live per-agent serviceTokens for the org's ACTIVE agents.
+ *
+ * register-fleet DEFERS per-agent token issuance (3c HIGH-2); activate-fleet mints
+ * the tokens after the customer Confirms + pays. This calls the server with the
+ * INSTALL/org serviceToken (the runtime block's token, ORG_SERVICE/org-scoped) to
+ * retrieve the now-minted tokens. SCANNED (pre-payment) agents are not returned —
+ * runtime push for them stays unavailable until Confirm.
+ *
+ * Same security posture as fetchBundle: HTTPS via curl, Authorization in a 0600
+ * tmpfile (never on argv), and NEVER throws (Invariant 2/3 — server unreachable
+ * leaves local config unchanged).
+ */
+function fetchAgentTokens(govServerUrl, installToken, timeoutSec = 10) {
+    const url = `${govServerUrl.replace(/\/$/, '')}/api/v1/cli/agent-tokens`;
+    let authTmpFile = null;
+    try {
+        const tmpDir = process.env['TMPDIR'] || process.env['TMP'] || process.env['TEMP'] || '/tmp';
+        const tmpPath = path.join(tmpDir, `gov-tok-auth-${crypto.randomBytes(8).toString('hex')}.hdr`);
+        fs.writeFileSync(tmpPath, `Authorization: Bearer ${installToken}\n`, { mode: 0o600 });
+        try {
+            fs.chmodSync(tmpPath, 0o600);
+        }
+        catch { /* best-effort on Windows */ }
+        authTmpFile = tmpPath;
+    }
+    catch {
+        console.warn('[gov-sync] WARNING: auth tmpfile write failed; falling back to token-on-argv (less secure). Check TMPDIR permissions.');
+        authTmpFile = null;
+    }
+    const authArgs = authTmpFile
+        ? ['-H', `@${authTmpFile}`]
+        : ['-H', `Authorization: Bearer ${installToken}`];
+    try {
+        const result = spawnSync('curl', [
+            '--silent', '--show-error',
+            '--max-time', String(timeoutSec),
+            '--connect-timeout', '5',
+            '--fail-with-body',
+            '-X', 'POST',
+            ...authArgs,
+            '-H', 'Content-Type: application/json',
+            '-H', 'Accept: application/json',
+            '--data', '{}',
+            url,
+        ], { encoding: 'utf8', timeout: (timeoutSec + 5) * 1000 });
+        if (result.status !== 0) {
+            const detail = result.stderr?.trim() || `curl exit ${result.status}`;
+            return { tokens: null, error: `Token fetch failed: ${detail}` };
+        }
+        if (!result.stdout)
+            return { tokens: null, error: 'Empty response from server.' };
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout);
+        }
+        catch {
+            return { tokens: null, error: 'Could not parse token response as JSON.' };
+        }
+        const obj = parsed;
+        if (typeof obj?.['error'] === 'string')
+            return { tokens: null, error: `Server error: ${obj['error']}` };
+        if (!Array.isArray(obj?.['tokens']))
+            return { tokens: null, error: 'Server response missing tokens[].' };
+        const tokens = [];
+        for (const t of obj['tokens']) {
+            const e = t;
+            if (typeof e?.['agentId'] === 'string' && typeof e?.['serviceToken'] === 'string') {
+                tokens.push({
+                    agentId: e['agentId'],
+                    serviceToken: e['serviceToken'],
+                    passportId: typeof e['passportId'] === 'string' ? e['passportId'] : null,
+                });
+            }
+        }
+        return { tokens };
+    }
+    catch (err) {
+        return { tokens: null, error: `Request failed: ${err.message}` };
+    }
+    finally {
+        if (authTmpFile) {
+            try {
+                fs.unlinkSync(authTmpFile);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Org public key pinning (trusted init-time fetch)
+// ---------------------------------------------------------------------------
+/**
+ * Fetch the org's Ed25519 public key from the governance server and write it
+ * into .governance.json under `orgPublicKey`.
+ *
+ * SECURITY: this must be called at `ai-governance init` time, BEFORE the first
+ * sync. The key is fetched over authenticated TLS from the same gov-server that
+ * issued the serviceToken. Subsequent syncs verify bundle signatures against
+ * this pinned key — they NEVER trust the key embedded in the bundle itself.
+ *
+ * The endpoint `GET /api/v1/orgs/:orgId/public-key` is unauthenticated (public
+ * keys are public, per Locked Invariant 4). We call it over the same
+ * govServerUrl + orgId that the exchange just returned, giving us a trusted
+ * source: the same TLS channel that authenticated the exchange.
+ *
+ * Returns the pinned key (base64url) on success, or null on failure.
+ * NEVER throws — on failure the caller logs the advisory and continues;
+ * the subsequent sync will fail closed (no pinned key = bundle rejected).
+ *
+ * DEPENDENCY NOTE (2026-06-08 prod incident): the org signing key is currently
+ * in-memory and regenerates on every gov-server deploy. With key-pinning, every
+ * post-deploy sync hits the rotation path until the key is made durable. That
+ * durability fix is the separate incident runbook — this function is still
+ * correct and required (rotation-as-explicit-event is the safe behavior).
+ */
+export function fetchAndPinOrgPublicKey(govServerUrl, orgId, configPath, timeoutSec = 10) {
+    const url = `${govServerUrl.replace(/\/$/, '')}/api/v1/orgs/${encodeURIComponent(orgId)}/public-key`;
+    try {
+        const result = spawnSync('curl', [
+            '--silent',
+            '--show-error',
+            '--max-time', String(timeoutSec),
+            '--connect-timeout', '5',
+            '--fail-with-body',
+            '-H', 'Accept: application/json',
+            url,
+        ], { encoding: 'utf8', timeout: (timeoutSec + 5) * 1000 });
+        if (result.status !== 0) {
+            return null;
+        }
+        if (!result.stdout) {
+            return null;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(result.stdout);
+        }
+        catch {
+            return null;
+        }
+        const obj = parsed;
+        // The endpoint returns `publicKeyPem` (base64url, 43 chars for 32-byte Ed25519 key).
+        const publicKeyB64 = typeof obj['publicKeyPem'] === 'string' ? obj['publicKeyPem'] : null;
+        if (!publicKeyB64 || publicKeyB64.length === 0) {
+            return null;
+        }
+        // Sanity check: must decode to 32 bytes (Ed25519 raw public key).
+        const raw = Buffer.from(publicKeyB64, 'base64url');
+        if (raw.length !== 32) {
+            return null;
+        }
+        // Write the pinned key into .governance.json with mode 0o600.
+        let config = {};
+        if (fs.existsSync(configPath)) {
+            try {
+                config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            }
+            catch { /* fresh */ }
+        }
+        config['orgPublicKey'] = publicKeyB64;
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+        try {
+            fs.chmodSync(configPath, 0o600);
+        }
+        catch { /* best-effort on Windows */ }
+        return publicKeyB64;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Bundle verification
+// ---------------------------------------------------------------------------
+/**
+ * Verify a governance bundle's Ed25519 signature.
+ *
+ * The signed payload is the JCS-canonical serialization of:
+ *   { agentId, bundleVersion, governance, issuedAt, orgId }
+ * The contentHash is SHA-256(canonical_bytes), hex-encoded.
+ * The signature is Ed25519(raw_sha256_digest_bytes) by the org signing key.
+ *
+ * KEY-TRUST SECURITY (Shield TS-010 remediation):
+ *   `pinnedPublicKeyB64` is the PINNED org public key read from the LOCAL
+ *   .governance.json (written at trusted init time). It is the SOLE key used
+ *   for signature verification. bundle['publicKeyB64'] is NEVER used as the
+ *   verification key — doing so would allow a MITM/rogue server to substitute
+ *   their own key alongside a tampered bundle and have it pass verification.
+ *
+ *   When `pinnedPublicKeyB64` is undefined (no pinned key on disk), the bundle
+ *   is REJECTED (fail closed). Re-running `ai-governance init` pins the key.
+ *
+ *   KEY ROTATION: if bundle['publicKeyB64'] differs from the pinned key, the
+ *   bundle is REJECTED with a rotation message. Key rotation is an EXPLICIT
+ *   operator event — re-run `ai-governance init` to accept the new key over an
+ *   authenticated TLS channel and re-pin it.
+ *
+ * Returns the verified SyncedGovernance on success, or an error string.
+ *
+ * SAFE BY DEFAULT: any failure (missing fields, bad sig, tampered, missing/
+ * mismatched pinned key) returns an error string; the caller MUST NOT apply.
+ */
+export function verifyBundle(bundle, pinnedPublicKeyB64) {
+    // KEY-TRUST: fail closed when no pinned key is available.
+    if (!pinnedPublicKeyB64) {
+        return {
+            ok: false,
+            error: 'No pinned org public key found in .governance.json. ' +
+                'Cannot verify bundle authenticity. ' +
+                'Re-run `ai-governance init` to pin the org public key from a trusted server exchange.',
+        };
+    }
+    // Structural checks
+    const requiredFields = [
+        'agentId', 'orgId', 'bundleVersion', 'issuedAt',
+        'governance', 'contentHash', 'signature', 'publicKeyB64',
+    ];
+    for (const f of requiredFields) {
+        if (bundle[f] === undefined) {
+            return { ok: false, error: `Bundle missing required field: ${f}` };
+        }
+    }
+    const agentId = bundle['agentId'];
+    const orgId = bundle['orgId'];
+    const bundleVersion = bundle['bundleVersion'];
+    const issuedAt = bundle['issuedAt'];
+    const governance = bundle['governance'];
+    const contentHash = bundle['contentHash'];
+    const signature = bundle['signature'];
+    // bundle['publicKeyB64'] is informational (audit record only).
+    // NEVER used as the verification key — see security note above.
+    const bundlePublicKeyB64 = bundle['publicKeyB64'];
+    if (typeof agentId !== 'string' ||
+        typeof orgId !== 'string' ||
+        typeof bundleVersion !== 'string' ||
+        typeof issuedAt !== 'string' ||
+        typeof contentHash !== 'string' || contentHash.length !== 64 ||
+        typeof signature !== 'string' ||
+        typeof bundlePublicKeyB64 !== 'string' ||
+        typeof governance !== 'object' || governance === null) {
+        return { ok: false, error: 'Bundle has invalid field types.' };
+    }
+    // KEY ROTATION GUARD: if the bundle embeds a key different from the pinned
+    // key, reject — this is either a MITM attack or a genuine server-side key
+    // rotation. Either way, automatic acceptance is unsafe. The operator must
+    // re-run `ai-governance init` to explicitly accept the new key over TLS.
+    if (bundlePublicKeyB64 !== pinnedPublicKeyB64) {
+        return {
+            ok: false,
+            error: 'Bundle public key does not match the pinned org public key in .governance.json. ' +
+                'This may indicate a key rotation or a MITM attack. ' +
+                'Re-run `ai-governance init` to accept the new key from a trusted server exchange, ' +
+                'then re-run `ai-governance sync`.',
+        };
+    }
+    // Re-derive the canonical payload (must match server's buildGovernanceBundle).
+    // JCS sorts object keys — same order as the server's jcsCanonicalize.
+    const payload = {
+        agentId,
+        bundleVersion,
+        governance,
+        issuedAt,
+        orgId,
+    };
+    let canonicalBytes;
+    try {
+        canonicalBytes = Buffer.from(jcsCanonicalizeMinimal(payload), 'utf8');
+    }
+    catch (e) {
+        return { ok: false, error: `Cannot canonicalize bundle payload: ${e.message}` };
+    }
+    const hashBytes = crypto.createHash('sha256').update(canonicalBytes).digest();
+    const expectedHash = hashBytes.toString('hex');
+    if (contentHash !== expectedHash) {
+        return {
+            ok: false,
+            error: `Bundle contentHash mismatch. Expected ${expectedHash}, got ${contentHash}. Bundle may be tampered.`,
+        };
+    }
+    // Verify Ed25519 signature against the PINNED key (not the bundle-embedded key).
+    const sigValid = verifyEd25519(signature, new Uint8Array(hashBytes), pinnedPublicKeyB64);
+    if (!sigValid) {
+        return { ok: false, error: 'Bundle signature is invalid. Rejecting tampered bundle.' };
+    }
+    // Extract governance fields
+    const gov = governance;
+    const syncedGovernance = {
+        packs: Array.isArray(gov['boundPacks'])
+            ? gov['boundPacks'].filter((p) => typeof p === 'string')
+            : [],
+        ruleOverrides: Array.isArray(gov['ruleOverrides']) ? [...gov['ruleOverrides']] : [],
+        declaredApprovalGates: Array.isArray(gov['declaredApprovalGates']) ? [...gov['declaredApprovalGates']] : [],
+        declaredForbiddenCapabilities: Array.isArray(gov['declaredForbiddenCapabilities'])
+            ? gov['declaredForbiddenCapabilities'].filter((c) => typeof c === 'string')
+            : [],
+        bundleIssuedAt: issuedAt,
+        contentHash: contentHash,
+        // signerPublicKeyB64 records the PINNED key used for verification (audit trail).
+        signerPublicKeyB64: pinnedPublicKeyB64,
+    };
+    return { ok: true, governance: syncedGovernance };
+}
+// ---------------------------------------------------------------------------
+// Diff computation
+// ---------------------------------------------------------------------------
+/** Produce a human-readable unified-style diff between two SyncedGovernance objects. */
+export function computeGovernanceDiff(previous, next) {
+    const lines = [];
+    const prevPacks = previous?.packs ?? [];
+    const nextPacks = next.packs;
+    const addedPacks = nextPacks.filter((p) => !prevPacks.includes(p));
+    const removedPacks = prevPacks.filter((p) => !nextPacks.includes(p));
+    if (addedPacks.length > 0) {
+        for (const p of addedPacks)
+            lines.push(`+ packs: ${p}`);
+    }
+    if (removedPacks.length > 0) {
+        for (const p of removedPacks)
+            lines.push(`- packs: ${p}`);
+    }
+    const prevOverrides = (previous?.ruleOverrides ?? []);
+    const nextOverrides = next.ruleOverrides;
+    if (JSON.stringify(prevOverrides) !== JSON.stringify(nextOverrides)) {
+        if (prevOverrides.length === 0 && nextOverrides.length > 0) {
+            lines.push(`+ ruleOverrides: ${nextOverrides.length} override(s) added`);
+        }
+        else if (nextOverrides.length === 0 && prevOverrides.length > 0) {
+            lines.push(`- ruleOverrides: ${prevOverrides.length} override(s) removed (now 0)`);
+        }
+        else {
+            lines.push(`~ ruleOverrides: ${prevOverrides.length} → ${nextOverrides.length} override(s)`);
+        }
+    }
+    const prevGates = (previous?.declaredApprovalGates ?? []);
+    const nextGates = next.declaredApprovalGates;
+    if (JSON.stringify(prevGates) !== JSON.stringify(nextGates)) {
+        lines.push(`~ declaredApprovalGates: ${prevGates.length} → ${nextGates.length}`);
+    }
+    const prevForbidden = previous?.declaredForbiddenCapabilities ?? [];
+    const nextForbidden = next.declaredForbiddenCapabilities;
+    const addedForbidden = nextForbidden.filter((c) => !prevForbidden.includes(c));
+    const removedForbidden = prevForbidden.filter((c) => !nextForbidden.includes(c));
+    for (const c of addedForbidden)
+        lines.push(`+ declaredForbiddenCapabilities: ${c}`);
+    for (const c of removedForbidden)
+        lines.push(`- declaredForbiddenCapabilities: ${c}`);
+    const prevBundleAt = previous?.bundleIssuedAt ?? '(none)';
+    if (prevBundleAt !== next.bundleIssuedAt) {
+        lines.push(`~ bundleIssuedAt: ${prevBundleAt} → ${next.bundleIssuedAt}`);
+    }
+    if (lines.length === 0) {
+        lines.push('  (no governance changes)');
+    }
+    return lines;
+}
+// ---------------------------------------------------------------------------
+// .governance.json re-materialisation
+// ---------------------------------------------------------------------------
+/**
+ * Apply the synced governance to the local .governance.json.
+ *
+ * Rules:
+ *   1. NEVER silently clobber a hand-edited file. If the local `packs` field
+ *      diverges from what `lastSync[agentId].governance.packs` recorded (i.e.
+ *      the user hand-edited it since the last sync), surface that in the diff
+ *      output. The --apply write still proceeds but the divergence is logged.
+ *   2. Write mode 0o600 — serviceTokens are present in the same file.
+ *   3. The `packs` top-level field is updated only when it is the first sync
+ *      or when --apply is passed. It is the union of all agents' packs.
+ *   4. `lastSync[agentId]` is updated unconditionally on --apply.
+ *
+ * Returns a list of warnings (non-fatal) about hand-edit divergences.
+ */
+export function applyGovernanceToLocal(configPath, agentId, newGovernance) {
+    const warnings = [];
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch { /* fresh */ }
+    }
+    // Detect divergence: was the local `packs` hand-edited since the last sync?
+    const lastSyncMap = config['lastSync'] ?? {};
+    const prevSync = lastSyncMap[agentId];
+    const lastSyncedPacks = prevSync?.governance?.packs ?? null;
+    const localPacks = Array.isArray(config['packs'])
+        ? config['packs'].filter((p) => typeof p === 'string')
+        : [];
+    if (lastSyncedPacks !== null) {
+        // Check if local packs diverged from what we last synced
+        const localSet = new Set(localPacks);
+        const lastSyncedSet = new Set(lastSyncedPacks);
+        const handAdded = localPacks.filter((p) => !lastSyncedSet.has(p));
+        const handRemoved = lastSyncedPacks.filter((p) => !localSet.has(p));
+        if (handAdded.length > 0 || handRemoved.length > 0) {
+            const detail = [
+                ...(handAdded.map((p) => `+ ${p}`)),
+                ...(handRemoved.map((p) => `- ${p}`)),
+            ].join(', ');
+            warnings.push(`[sync] Divergence detected for agent ${agentId}: ` +
+                `local packs were hand-edited since last sync (${detail}). ` +
+                `Applying server governance will overwrite local edits.`);
+        }
+    }
+    // Update packs: use server's packs for this agent. For multi-agent projects,
+    // merge with other agents' already-synced packs (union, deduplicated).
+    const serverPacks = new Set(newGovernance.packs);
+    // Preserve packs from other agents' last-sync snapshots
+    for (const [otherId, otherSync] of Object.entries(lastSyncMap)) {
+        if (otherId === agentId)
+            continue;
+        const other = otherSync;
+        if (Array.isArray(other?.governance?.packs)) {
+            for (const p of other.governance.packs)
+                serverPacks.add(p);
+        }
+    }
+    config['packs'] = [...serverPacks].sort();
+    // Update lastSync snapshot
+    const updatedLastSync = {
+        agentId,
+        syncedAt: new Date().toISOString(),
+        governance: newGovernance,
+    };
+    config['lastSync'] = {
+        ...lastSyncMap,
+        [agentId]: updatedLastSync,
+    };
+    // Write atomically with mode 0o600 (serviceTokens present)
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+    try {
+        fs.chmodSync(configPath, 0o600);
+    }
+    catch { /* best-effort on Windows */ }
+    return { warnings };
+}
+// ---------------------------------------------------------------------------
+// Main sync command
+// ---------------------------------------------------------------------------
+/**
+ * Parse the args array and run the sync command.
+ *
+ * @param args   Slice of process.argv after 'sync'
+ * @param projectDir  Absolute path to the project directory (default: cwd)
+ * @param options.fetchBundleFn  Override the fetch function for testing
+ * @returns exit code: 0 = success (or dry-run with no errors), 1 = some errors
+ */
+export async function runSyncCommand(args, projectDir = process.cwd(), options = {}) {
+    const applyFlag = args.includes('--apply');
+    const agentFilter = (() => {
+        const idx = args.indexOf('--agent');
+        return idx >= 0 ? args[idx + 1] : undefined;
+    })();
+    const govServerUrlOverride = (() => {
+        const idx = args.indexOf('--gov-server-url');
+        return idx >= 0 ? args[idx + 1] : undefined;
+    })();
+    const log = options.silent ? () => { } : (s) => process.stdout.write(s + '\n');
+    const err = options.silent ? () => { } : (s) => process.stderr.write(s + '\n');
+    // Read .governance.json
+    const configPath = path.join(projectDir, '.governance.json');
+    if (!fs.existsSync(configPath)) {
+        err('No .governance.json found. Run `ai-governance init` first.');
+        return { dryRun: !applyFlag, diffs: [], applied: 0, errors: 1 };
+    }
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+    catch (e) {
+        err(`Failed to parse .governance.json: ${e.message}`);
+        return { dryRun: !applyFlag, diffs: [], applied: 0, errors: 1 };
+    }
+    // Resolve gov server URL: cli flag > .governance.json runtime block > default
+    const runtime = config['runtime'] ?? {};
+    const govServerUrl = (govServerUrlOverride ??
+        (typeof runtime['govServerUrl'] === 'string' ? runtime['govServerUrl'] : null) ??
+        'https://api.my-cc.io');
+    // Collect agents to sync from agents[] (per-agent identity, TS-002)
+    const agentsArr = Array.isArray(config['agents'])
+        ? config['agents']
+        : [];
+    // Fall back to the single-agent runtime block when agents[] is empty
+    // (pre-TS-002 installs that only have runtime.agentId)
+    const singleAgentFallback = agentsArr.length === 0 &&
+        typeof runtime['agentId'] === 'string' &&
+        typeof runtime['serviceToken'] === 'string'
+        ? {
+            localId: String(runtime['agentId']),
+            agentId: String(runtime['agentId']),
+            serviceToken: String(runtime['serviceToken']),
+            passportId: null,
+            filePath: undefined,
+        }
+        : null;
+    const allAgents = agentsArr.length > 0 ? agentsArr : singleAgentFallback ? [singleAgentFallback] : [];
+    if (allAgents.length === 0) {
+        err('No agents found in .governance.json. ' +
+            'Run `ai-governance init --agent-dir <path>` to register agents first.');
+        return { dryRun: !applyFlag, diffs: [], applied: 0, errors: 1 };
+    }
+    // Filter to requested agent if --agent was passed
+    const toSync = agentFilter
+        ? allAgents.filter((a) => a.agentId === agentFilter || a.localId === agentFilter)
+        : allAgents;
+    if (toSync.length === 0) {
+        err(`No agent matching --agent ${agentFilter} found in .governance.json.`);
+        return { dryRun: !applyFlag, diffs: [], applied: 0, errors: 1 };
+    }
+    if (!applyFlag) {
+        log(`[sync] Dry-run mode (default). Use --apply to write changes.`);
+    }
+    log(`[sync] Server: ${govServerUrl}`);
+    log(`[sync] Agents: ${toSync.length}`);
+    const fetchFn = options.fetchBundleFn ?? fetchBundle;
+    const fetchTokensFn = options.fetchAgentTokensFn ?? fetchAgentTokens;
+    // Slice 3d: per-agent tokens are DEFERRED to payment activation (3c). Any agent
+    // still missing a serviceToken was detected pre-payment; once the customer
+    // Confirms + pays, activate-fleet mints the tokens. Fetch them here using the
+    // install/org token from the runtime block and merge them into agents[]. Agents
+    // that are still scanned (not returned) keep a null token → "push unavailable
+    // until Confirm" below. Never throws (Invariant 2/3): a failed fetch leaves the
+    // tokens null and the loop reports them honestly.
+    const installToken = typeof runtime['serviceToken'] === 'string' ? runtime['serviceToken'] : null;
+    if (toSync.some((a) => !a.serviceToken) && installToken) {
+        log('[sync] Fetching activated per-agent tokens...');
+        const { tokens, error: tokenErr } = fetchTokensFn(govServerUrl, installToken);
+        if (tokens && tokens.length > 0) {
+            const byId = new Map(tokens.map((t) => [t.agentId, t]));
+            let merged = 0;
+            // Merge into the persisted agents[] (so the tokens survive across runs) and
+            // into the in-memory toSync entries (so this run uses them immediately).
+            const persistedAgents = Array.isArray(config['agents']) ? config['agents'] : [];
+            for (const a of persistedAgents) {
+                const t = byId.get(a.agentId);
+                if (t && !a.serviceToken) {
+                    a.serviceToken = t.serviceToken;
+                    if (t.passportId)
+                        a.passportId = t.passportId;
+                    merged++;
+                }
+            }
+            for (const a of toSync) {
+                const t = byId.get(a.agentId);
+                if (t && !a.serviceToken) {
+                    a.serviceToken = t.serviceToken;
+                    if (t.passportId)
+                        a.passportId = t.passportId;
+                }
+            }
+            // Persist the tokens only on --apply (dry-run writes nothing). The in-memory
+            // merge above still lets a dry-run fetch bundles + show the diff this run.
+            if (merged > 0 && applyFlag) {
+                config['agents'] = persistedAgents;
+                try {
+                    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+                    try {
+                        fs.chmodSync(configPath, 0o600);
+                    }
+                    catch { /* best-effort on Windows */ }
+                }
+                catch { /* advisory: in-memory tokens still used this run */ }
+            }
+            log(`[sync] Activated ${merged} agent token(s)${applyFlag ? '' : ' (dry-run — not written; re-run with --apply)'}.`);
+        }
+        else if (tokenErr) {
+            // Non-fatal: the agents without tokens fall through to the message below.
+            err(`[sync] Could not fetch activated tokens: ${tokenErr}`);
+        }
+    }
+    const diffs = [];
+    let applied = 0;
+    let errors = 0;
+    for (const agent of toSync) {
+        const { agentId, serviceToken, filePath } = agent;
+        if (!serviceToken) {
+            // Slice 3d (Decision 4): a token-less agent is still SCANNED — the customer
+            // has not Confirmed + paid, so it has no runnable identity yet. This is the
+            // fail-safe, not an error to fix by re-running init.
+            const d = {
+                agentId,
+                filePath,
+                bundle: null,
+                newGovernance: null,
+                previousGovernance: null,
+                diffLines: [],
+                error: 'Runtime push unavailable until Confirm — this agent is detected but not yet activated. ' +
+                    'Confirm + pay in the dashboard, then re-run `ai-governance sync`.',
+            };
+            diffs.push(d);
+            err(`[sync] agent ${agentId}: ${d.error}`);
+            errors++;
+            continue;
+        }
+        // Fetch bundle (Invariant 2/3: server unreachable → graceful no-op)
+        log(`[sync] Fetching bundle for agent ${agentId}...`);
+        const { bundle, error: fetchError } = fetchFn(govServerUrl, agentId, serviceToken);
+        if (!bundle || fetchError) {
+            const d = {
+                agentId,
+                filePath,
+                bundle: null,
+                newGovernance: null,
+                previousGovernance: null,
+                diffLines: [],
+                error: fetchError ?? 'Could not fetch bundle.',
+            };
+            diffs.push(d);
+            err(`[sync] agent ${agentId}: ${d.error}`);
+            err(`[sync] Server unreachable or request failed — local config unchanged.`);
+            errors++;
+            continue;
+        }
+        // KEY-TRUST: read the PINNED org public key from the local config.
+        // This was written at `ai-governance init` time over authenticated TLS.
+        // Do NOT use bundle['publicKeyB64'] — that is the attack vector.
+        const pinnedPublicKeyB64 = typeof config['orgPublicKey'] === 'string'
+            ? config['orgPublicKey']
+            : undefined;
+        // Verify signature against the PINNED key — REJECT if no pinned key or
+        // if the bundle key differs (rotation guard, see verifyBundle doc).
+        const verifyResult = verifyBundle(bundle, pinnedPublicKeyB64);
+        if (!verifyResult.ok) {
+            const d = {
+                agentId,
+                filePath,
+                bundle,
+                newGovernance: null,
+                previousGovernance: null,
+                diffLines: [],
+                error: verifyResult.error,
+            };
+            diffs.push(d);
+            err(`[sync] agent ${agentId}: REJECTED — ${verifyResult.error}`);
+            err(`[sync] Local config unchanged.`);
+            errors++;
+            continue;
+        }
+        const newGovernance = verifyResult.governance;
+        // Read previous sync snapshot for diff
+        const lastSyncMap = config['lastSync'] ?? {};
+        const prevSync = lastSyncMap[agentId];
+        const previousGovernance = prevSync?.governance ?? null;
+        // Compute diff
+        const diffLines = computeGovernanceDiff(previousGovernance, newGovernance);
+        const d = {
+            agentId,
+            filePath,
+            bundle,
+            newGovernance,
+            previousGovernance,
+            diffLines,
+        };
+        diffs.push(d);
+        // Print diff
+        log(`\n[sync] agent ${agentId}${filePath ? ` (${filePath})` : ''}:`);
+        for (const line of diffLines) {
+            log(`  ${line}`);
+        }
+        if (applyFlag) {
+            const { warnings } = applyGovernanceToLocal(configPath, agentId, newGovernance);
+            // Re-read config after write so subsequent agents see the updated state
+            try {
+                config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            }
+            catch { /* advisory */ }
+            for (const w of warnings) {
+                err(w);
+            }
+            log(`[sync] agent ${agentId}: applied.`);
+            applied++;
+        }
+    }
+    if (!applyFlag && diffs.some((d) => d.newGovernance !== null)) {
+        log(`\n[sync] Dry-run complete. Re-run with --apply to write changes.`);
+    }
+    else if (applyFlag) {
+        log(`\n[sync] Applied ${applied}/${toSync.length} agent(s). Errors: ${errors}.`);
+    }
+    return { dryRun: !applyFlag, diffs, applied, errors };
+}
+//# sourceMappingURL=sync.js.map