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

package/dist/esm/cli/index.js

@@ -22,7 +22,9 @@ import { JwtValidator } from '../license/index.js';
 import { BUILT_IN_PACKS } from '../governed-agent.js';
 import { scanAgentDirectory } from './agent-dir-scanner.js';
 import { normalizeAgentDir } from './normalize-agent-dir.js';
-import { writeWrapShims } from './wrap-shim-generator.js';
+import { writeWrapShims, regenerateShimAgentIds } from './wrap-shim-generator.js';
+// Identity RFC B1 (per-folder identity files) — Pass-1 wiring (init --link).
+import { writePerFolderIdentities, buildPerFolderIdentityInputs } from './per-folder-identity.js';
 import { preflightAgents } from './preflight.js';
 import { formatPreflightReport } from './preflight-report.js';
 /**
@@ -1208,6 +1210,25 @@ async function interactiveInit(projectDir, opts = {}) {
         writeVendorCodeToConfig(projectDir, '', true);
         process.stdout.write('Offline mode recorded in .governance.json\n');
     }
+    // TS-010 KEY-TRUST: pin the org public key from the server into
+    // .governance.json immediately after the config is written.
+    // The key is fetched over authenticated TLS from the same gov-server that
+    // issued the serviceToken. Subsequent `ai-governance sync` calls verify
+    // bundle signatures against this pinned key (never the bundle-embedded key).
+    // Non-fatal: advisory if unavailable (Invariant 2), but sync will fail
+    // closed (bundle rejected) until the key is pinned.
+    if (opts.runtime?.govServerUrl && opts.runtime?.orgId) {
+        const { fetchAndPinOrgPublicKey } = require('./sync.js');
+        const pinned = fetchAndPinOrgPublicKey(opts.runtime.govServerUrl, opts.runtime.orgId, configPath);
+        if (pinned) {
+            process.stdout.write(`Org public key pinned for offline bundle verification.\n`);
+        }
+        else {
+            process.stderr.write('WARNING: could not fetch org public key for pinning. ' +
+                '`ai-governance sync` will reject bundles until the key is pinned. ' +
+                'Re-run `ai-governance init` when the server is reachable.\n');
+        }
+    }
     // Install hooks
     const { installed, errors } = installHooks(projectDir, config);
     process.stdout.write(`Hooks installed: ${installed}\n`);
@@ -1689,6 +1710,109 @@ export function writeGovernanceMcpSuggest(projectDir, tenantId) {
     ].join('\n'));
     return path.relative(projectDir, mcpSuggestPath);
 }
+/**
+ * TS-002 CLI half — consume the registered[] list returned by register-fleet
+ * and write a per-agent identity block into the project's .governance.json.
+ *
+ * Shape written:
+ * ```json
+ * {
+ *   "agents": [
+ *     { "localId": "auto-...", "agentId": "srv-uuid", "passportId": "pp-...",
+ *       "serviceToken": "eyJ...", "filePath": "src/agents/billing.py" }
+ *   ],
+ *   "runtime": {
+ *     "agentId": "<first-registered-agentId>",
+ *     "serviceToken": "<first-registered-serviceToken>",
+ *     ...rest of existing runtime block
+ *   }
+ * }
+ * ```
+ *
+ * Back-compat guarantee: runtime.agentId + runtime.serviceToken are updated to
+ * the first registered agent so the existing audit-logger.sh → /cluster-events
+ * push path (which reads these two flat fields) continues to work for the
+ * single-agent case. The per-agent `agents[]` array is the source of truth for
+ * multi-agent deployments; future per-agent attribution reads from there.
+ *
+ * Null-passport and null-serviceToken entries are written without throwing
+ * (Invariant 2 — advisory, never blocking). A null serviceToken from agent N
+ * does NOT overwrite the runtime.serviceToken that was already set.
+ *
+ * Idempotent: calling twice with the same input upserts by localId — does not
+ * duplicate entries.
+ *
+ * @param projectDir  Absolute path to the directory containing .governance.json
+ * @param registered  Array from register-fleet response.registered[]
+ * @param localAgents Locally scanned DetectedAgent list (used to resolve filePath by localId)
+ */
+export function writePerAgentIdentities(projectDir, registered, localAgents, opts = {}) {
+    if (registered.length === 0)
+        return;
+    const configPath = path.join(projectDir, '.governance.json');
+    // Read existing config — must preserve all existing keys (packs, hooks, etc.)
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch { /* fresh config — start empty */ }
+    }
+    // Build a quick-lookup: localId → filePath from the local scan.
+    // For entries where localId is absent, fall back to agentId as key.
+    const filePathByLocalId = new Map();
+    for (const la of localAgents) {
+        filePathByLocalId.set(la.agentId, la.filePath);
+    }
+    // Build the new per-agent entries.
+    const newEntries = registered.map((r) => {
+        const key = r.localId ?? r.agentId;
+        return {
+            localId: key,
+            agentId: r.agentId,
+            passportId: r.passportId,
+            serviceToken: r.serviceToken,
+            filePath: filePathByLocalId.get(key),
+        };
+    });
+    // Upsert into existing agents[] (idempotent — replace by localId).
+    const existingEntries = Array.isArray(config['agents'])
+        ? config['agents']
+        : [];
+    const merged = [...existingEntries];
+    for (const entry of newEntries) {
+        const idx = merged.findIndex((e) => e.localId === entry.localId);
+        if (idx >= 0) {
+            merged[idx] = entry;
+        }
+        else {
+            merged.push(entry);
+        }
+    }
+    config['agents'] = merged;
+    // Back-compat: update runtime.agentId + runtime.serviceToken to the first
+    // registered agent so the audit-logger.sh single-agent push path keeps working.
+    // Only update runtime.serviceToken if the first agent's token is non-null
+    // (do not overwrite a valid existing token with null).
+    const first = newEntries[0];
+    if (first) {
+        const runtime = config['runtime'] ?? {};
+        runtime['agentId'] = first.agentId;
+        if (first.serviceToken !== null) {
+            runtime['serviceToken'] = first.serviceToken;
+        }
+        if (opts.agentDir) {
+            runtime['agentDir'] = opts.agentDir;
+        }
+        config['runtime'] = runtime;
+    }
+    // Write atomically — mode 0o600 (service tokens are secrets, Invariant 10).
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+    try {
+        fs.chmodSync(configPath, 0o600);
+    }
+    catch { /* best-effort on Windows */ }
+}
 // --- Non-interactive init (CI mode) ---
 export async function nonInteractiveInit(projectDir, opts) {
     const licenseKey = opts.license || 'free';
@@ -2437,6 +2561,10 @@ Usage:
     [--archive-dir <dir>]                    Archive destination (else delete)
     [--dry-run]                              Report without acting
     [--json]                                 Machine-readable output
+  ai-governance sync                         Pull server governance bundle to local .governance.json
+    [--apply]                              Write changes (default: dry-run, shows diff only)
+    [--agent <id>]                         Sync a specific agent only
+    [--gov-server-url <url>]               Override gov server URL
   ai-governance rotate-token                 Rotate the runtime service token
                                              Reads .governance.json runtime.serviceToken,
                                              requests a fresh token from the gov-server,
@@ -2762,7 +2890,74 @@ if (isDirectRun) {
                 if (runtimeConfig?.serviceToken && runtimeConfig?.govServerUrl && detectedAgents.length > 0) {
                     try {
                         const { spawnSync } = require('node:child_process');
+                        // TS-009: capture project identity so the server can link agents to
+                        // the customer's actual project for audit roll-up in the portal.
+                        //
+                        // projectId: deterministic hash of the agent-dir absolute path.
+                        //   Uses SHA-256(resolvedAgentDir) → first 16 hex chars. Stable across
+                        //   re-runs on the same machine for the same project. If the customer
+                        //   moves the repo, a new projectId is generated (a new project entity).
+                        //
+                        // projectName: basename of resolvedAgentDir (human-readable). If git
+                        //   is available and resolvedAgentDir is inside a repo, use the repo
+                        //   name (basename of the top-level). Falls back to dir basename.
+                        //
+                        // origin: git remote 'origin' URL, read locally by the CLI from the
+                        //   customer's repo. The client's CLI reads its own git remote — we
+                        //   NEVER scan or poll their infrastructure (Invariant 10: push-receive).
+                        //   Only sent when git is available and the remote is set; never fails.
+                        //
+                        // Advisory (Invariant 2): any failure in this block produces null
+                        // values — the fleet payload is always sent and registration never
+                        // fails because of a missing project block.
+                        const captureProjectIdentity = () => {
+                            let origin;
+                            let projectName = path.basename(resolvedAgentDir);
+                            let gitRootDir;
+                            // Attempt to read git remote origin and repo name (client reads
+                            // its own git — Invariant 10 respected).
+                            try {
+                                const gitRemote = spawnSync('git', ['-C', resolvedAgentDir, 'remote', 'get-url', 'origin'], { encoding: 'utf8', timeout: 3000 });
+                                if (gitRemote.status === 0 && gitRemote.stdout) {
+                                    origin = gitRemote.stdout.trim();
+                                    // Derive projectName from the repo name embedded in the origin URL.
+                                    // Works for both SSH (git@github.com:org/repo.git) and HTTPS
+                                    // (https://github.com/org/repo.git). Strip trailing .git.
+                                    const match = origin.match(/[\/:]([\w.-]+?)(?:\.git)?$/);
+                                    if (match && match[1]) {
+                                        projectName = match[1];
+                                    }
+                                }
+                            }
+                            catch { /* git not available or not a git repo — use dir basename */ }
+                            try {
+                                // Best-effort: get the git top-level for a more stable projectId
+                                const gitRoot = spawnSync('git', ['-C', resolvedAgentDir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', timeout: 3000 });
+                                if (gitRoot.status === 0 && gitRoot.stdout) {
+                                    gitRootDir = gitRoot.stdout.trim();
+                                    // Override projectName with repo root basename when git is available
+                                    const rootBasename = path.basename(gitRootDir);
+                                    if (rootBasename)
+                                        projectName = rootBasename;
+                                }
+                            }
+                            catch { /* best-effort */ }
+                            // projectId: deterministic hash of the absolute project root dir
+                            // (git root when available, otherwise resolvedAgentDir). This gives
+                            // all register-fleet runs from the same repo the same projectId.
+                            const hashInput = gitRootDir ?? resolvedAgentDir;
+                            const projectId = 'proj-' + crypto.createHash('sha256').update(hashInput).digest('hex').slice(0, 16);
+                            return { projectId, projectName, ...(origin ? { origin } : {}) };
+                        };
+                        let projectIdentity;
+                        try {
+                            projectIdentity = captureProjectIdentity();
+                        }
+                        catch {
+                            // Advisory: project identity capture failure must never block fleet registration.
+                        }
                         const fleetPayload = {
+                            ...(projectIdentity ? { project: projectIdentity } : {}),
                             agents: detectedAgents.map((a) => ({
                                 localId: a.agentId,
                                 name: a.name ?? undefined,
@@ -2774,6 +2969,17 @@ if (isDirectRun) {
                                 // so the platform's OWASP/ASI analysis grades real tool surface.
                                 tools: a.tools && a.tools.length > 0 ? a.tools : undefined,
                                 mcpServers: a.mcpServers && a.mcpServers.length > 0 ? a.mcpServers : undefined,
+                                // TS-008 lossless capture (ticket A2): the scanner already
+                                // parses these from manifest.json; sending them closes the
+                                // model/version/vertical/allowed_domains/toolDetails/
+                                // max_concurrent_actions = null gap on the registered agent
+                                // (server validates + persists them — FleetAgentInput).
+                                model_identifier: a.model_identifier,
+                                version: a.version,
+                                vertical: a.vertical,
+                                allowed_domains: a.allowed_domains && a.allowed_domains.length > 0 ? a.allowed_domains : undefined,
+                                toolDetails: a.toolDetails && a.toolDetails.length > 0 ? a.toolDetails : undefined,
+                                max_concurrent_actions: a.max_concurrent_actions,
                             })),
                         };
                         const fleetResult = spawnSync('curl', [
@@ -2792,9 +2998,109 @@ if (isDirectRun) {
                                 const resp = JSON.parse(fleetResult.stdout);
                                 if (typeof resp.registeredCount === 'number') {
                                     fleetRegistered = true;
-                                    process.stdout.write(`\n✅ Registered ${resp.registeredCount} agent(s) on the platform` +
+                                    process.stdout.write(`\n✅ Detected ${resp.registeredCount} agent(s) on the platform` +
                                         (resp.skippedCount ? ` (${resp.skippedCount} already registered, skipped)` : '') +
-                                        ` — check your dashboard.\n`);
+                                        ` — check your dashboard.\n` +
+                                        // Slice 3c/3d (Decision 4): passports + runtime tokens are issued
+                                        // at payment activation, not at detection. Tell the customer that
+                                        // runtime push is unavailable until they Confirm + pay, and how to
+                                        // activate it afterward.
+                                        `   ⏳ Runtime governance push is UNAVAILABLE until you Confirm + pay in the dashboard\n` +
+                                        `      (detected agents are not yet activated). After you Confirm, run\n` +
+                                        `      \`ai-governance sync --apply\` to activate each agent's runtime push.\n`);
+                                    // TS-002 CLI half: persist per-agent identities into .governance.json.
+                                    // Each agent gets its own serviceToken (sub=agent:<agentId>) so future
+                                    // per-agent audit pushes carry the correct identity. The runtime block
+                                    // is updated to the first agent for single-agent backward-compat.
+                                    // Non-fatal (Invariant 2): if this write fails governance still runs.
+                                    // Ghost-fix (#1717) fail-loud: print WHY any agent failed to
+                                    // register — a bare count hid the b60d6cbc-class failures.
+                                    if (Array.isArray(resp.failures) && resp.failures.length > 0) {
+                                        for (const f of resp.failures) {
+                                            process.stderr.write(`   ❌ ${f.name}: registration failed — ${f.reason}\n`);
+                                        }
+                                        process.stderr.write('   Re-run the install command to retry the failed agent(s).\n');
+                                    }
+                                    if (typeof resp.healedGhostCount === 'number' && resp.healedGhostCount > 0) {
+                                        process.stdout.write(`   ♻ Healed ${resp.healedGhostCount} previously-stuck agent registration(s).\n`);
+                                    }
+                                    if (Array.isArray(resp.registered) && resp.registered.length > 0) {
+                                        try {
+                                            // Shield F1 (#1720, MEDIUM): server agentIds are BAKED into
+                                            // executable shim files via raw template interpolation and
+                                            // into URL paths — gate them against the canonical format
+                                            // at the trust boundary before ANY downstream use. A
+                                            // non-matching id from a compromised/MITM'd response is
+                                            // dropped with a visible WARN, never interpolated.
+                                            const SAFE_SERVER_AGENT_ID = /^agent-[0-9a-f]{8}$/;
+                                            const safeRegistered = resp.registered.filter((r) => {
+                                                if (SAFE_SERVER_AGENT_ID.test(r.agentId))
+                                                    return true;
+                                                process.stderr.write(`   [WARN] server returned a non-canonical agentId (${JSON.stringify(r.agentId).slice(0, 60)}) — entry dropped.\n`);
+                                                return false;
+                                            });
+                                            const localRefs = detectedAgents.map((a) => ({
+                                                agentId: a.agentId,
+                                                filePath: a.filePath,
+                                            }));
+                                            // Persist the scan root so sync passes can resolve the
+                                            // SCAN-ROOT-relative agents[].filePath to real folders.
+                                            const agentDirRel = path.relative(projectDir, resolvedAgentDir) || '.';
+                                            writePerAgentIdentities(projectDir, safeRegistered, localRefs, {
+                                                agentDir: path.isAbsolute(agentDirRel) ? resolvedAgentDir : agentDirRel,
+                                            });
+                                            process.stdout.write(`[CLI] per-agent identities written to .governance.json ` +
+                                                `(${safeRegistered.length} agent(s)).\n`);
+                                            // Identity RFC B1 (Pass 1): land each agent's identity in
+                                            // ITS OWN folder — <agent>/.connexum/identity.json. No
+                                            // secret at this pass (tokens are minted at payment
+                                            // activation), so this writes metadata regardless of git
+                                            // state. Folder root = the SCAN root, not projectDir.
+                                            const folderInputs = buildPerFolderIdentityInputs(safeRegistered, localRefs, {
+                                                installationId: resp.installationId,
+                                                signingKeyId: resp.signingKeyId,
+                                                govServerUrl: resp.govServerUrl ?? runtimeConfig.govServerUrl,
+                                                orgId: resp.orgId ?? runtimeConfig.orgId,
+                                            }, new Date().toISOString());
+                                            const folderRes = writePerFolderIdentities(resolvedAgentDir, folderInputs, {
+                                                warn: (m) => process.stderr.write(m + '\n'),
+                                            });
+                                            process.stdout.write(`[CLI] per-folder identity files: ${folderRes.written.length} written` +
+                                                (folderRes.skipped.length > 0 ? `, ${folderRes.skipped.length} skipped` : '') + '.\n');
+                                            // Identity RFC C1 (Option B): regenerate each shim with
+                                            // the SERVER agentId. Without this every shim keeps the
+                                            // baked local auto-* id and all runtime signals collapse
+                                            // onto ids the platform never issued. Pristine shims are
+                                            // rebaked; edited shims get a VISIBLE warn (never a
+                                            // silent skip — Stern BLOCK-2).
+                                            const serverIdByLocalId = new Map();
+                                            for (const r of safeRegistered) {
+                                                if (r.localId)
+                                                    serverIdByLocalId.set(r.localId, r.agentId);
+                                            }
+                                            const regenResults = regenerateShimAgentIds(detectedAgents, serverIdByLocalId, resolvedAgentDir, (msg) => process.stdout.write(msg + '\n'));
+                                            const rebaked = regenResults.filter((r) => r.status === 'regenerated' || r.status === 'verified').length;
+                                            const stuck = regenResults.filter((r) => r.status === 'skipped-edited' || r.status === 'failed');
+                                            process.stdout.write(`[CLI] shim identity rebake: ${rebaked} on server ids` +
+                                                (stuck.length > 0 ? `, ${stuck.length} NEED ATTENTION (listed above)` : '') + '.\n');
+                                            if (stuck.length > 0) {
+                                                // Stern F1 (#1720): the recovery path must be in the
+                                                // operator-facing summary, not buried in per-file WARNs.
+                                                process.stderr.write('⚠️  The agent(s) listed above still emit their LOCAL id at runtime — their\n' +
+                                                    '   signals will not attach to the registered platform identity until fixed.\n' +
+                                                    '   Recovery: if you did NOT edit the .governed file yourself, DELETE it and\n' +
+                                                    '   re-run this install command — it will be regenerated with the correct id.\n' +
+                                                    '   If you did edit it, set its AGENT_ID to the server id shown above.\n');
+                                            }
+                                        }
+                                        catch (identityErr) {
+                                            // Non-fatal — fleet is registered on the platform; local identity
+                                            // write failure must not undo that success (Invariant 2).
+                                            process.stderr.write(`[CLI] per-agent identity write failed (non-fatal): ` +
+                                                `${identityErr.message}. ` +
+                                                `Agents are registered on the platform; re-run init to retry the write.\n`);
+                                        }
+                                    }
                                 }
                                 else if (resp.error) {
                                     process.stderr.write(`[CLI] register-fleet: server error: ${resp.error}\n`);
@@ -2885,6 +3191,27 @@ if (isDirectRun) {
                 runtime: runtimeConfig,
                 agentDir: agentDirArg,
             });
+            // TS-010 KEY-TRUST: pin the org public key from the server into
+            // .governance.json immediately after init writes the config file.
+            // This is the trusted pinning event — the key is fetched over the same
+            // authenticated TLS channel that issued the runtimeConfig exchange.
+            // Subsequent `ai-governance sync` calls verify bundle signatures against
+            // this pinned key. Non-fatal: advisory if unavailable (Invariant 2), but
+            // sync will fail closed until the key is pinned.
+            if (runtimeConfig?.govServerUrl && runtimeConfig?.orgId) {
+                // fetchAndPinOrgPublicKey is imported from sync.ts
+                const { fetchAndPinOrgPublicKey } = require('./sync.js');
+                const configPath = path.join(projectDir, '.governance.json');
+                const pinned = fetchAndPinOrgPublicKey(runtimeConfig.govServerUrl, runtimeConfig.orgId, configPath);
+                if (pinned) {
+                    process.stderr.write(`[CLI] org public key pinned to .governance.json (${pinned.slice(0, 8)}...).\n`);
+                }
+                else {
+                    process.stderr.write('[CLI] WARNING: could not fetch org public key for pinning. ' +
+                        '`ai-governance sync` will fail closed until the key is pinned. ' +
+                        'Re-run `ai-governance init` when the server is reachable to pin the key.\n');
+                }
+            }
         }
         else if (!agentDirFlag) {
             interactiveInit(projectDir, { vendorCodeFlag, offlineFlag, licenseServerUrl, runtime: runtimeConfig }).catch(err => {
@@ -2987,6 +3314,19 @@ if (isDirectRun) {
             });
         });
     }
+    else if (command === 'sync') {
+        // TS-010: pull server governance bundle and re-materialize local .governance.json.
+        // Safe by default — no --apply = dry-run (shows diff, writes nothing).
+        // See src/cli/sync.ts.
+        import('./sync.js').then(({ runSyncCommand }) => {
+            runSyncCommand(args.slice(1), projectDir).then((result) => {
+                process.exit(result.errors > 0 ? 1 : 0);
+            }).catch((e) => {
+                process.stderr.write(`Error: ${e.message}\n`);
+                process.exit(2);
+            });
+        });
+    }
     else if (command === 'scan') {
         // A-2 (2026-05-19): customer-side OWASP Agentic Top 10 scan. Replaces
         // the deprecated W-03 server-side Git-clone flow. Source code stays on