nexarch 0.12.22 → 0.12.23

package/dist/commands/init-agent.js

@@ -2,6 +2,7 @@ import { arch, homedir, hostname, platform, release, type as osType, userInfo }
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
 import { basename, join, resolve } from "path";
 import * as readline from "node:readline/promises";
+import { createHash } from "node:crypto";
 import process from "process";
 import { requireCredentials } from "../lib/credentials.js";
 import { fetchAgentRegistryOrThrow } from "../lib/agent-registry.js";
@@ -19,6 +20,10 @@ const CLI_VERSION = (() => {
 })();
 const AGENT_ENTITY_TYPE = "agent";
 const TECH_COMPONENT_ENTITY_TYPE = "technology_component";
+/** Hashes the exact managed-section text a trust attestation will be minted for — see ADR-0112. */
+function sha256Hex(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
 function parseFlag(args, flag) {
     return args.includes(flag);
 }
@@ -337,7 +342,13 @@ function canonicalTargetKey(filePath) {
     const abs = resolve(filePath);
     return process.platform === "win32" || process.platform === "darwin" ? abs.toLowerCase() : abs;
 }
-function injectAgentConfigs(registry, runtimeCodes) {
+/**
+ * `dryRun: true` computes what WOULD happen (status + the exact section body,
+ * so a caller can hash it) without touching any file. Callers must resolve
+ * consent from the dry-run result before calling again with `dryRun: false`
+ * to actually write — see the ADR-0112 note at the call site.
+ */
+function injectAgentConfigs(registry, runtimeCodes, dryRun) {
     const templateByCode = new Map(registry.instructionTemplates.map((t) => [t.code, t]));
     const sortedTargets = [...registry.instructionTargets]
         .filter((target) => target.matchMode === "exact")
@@ -356,8 +367,9 @@ function injectAgentConfigs(registry, runtimeCodes) {
         const sectionMarker = target.sectionMarker ?? sectionHeading;
         const managedBody = wrapManagedSection("agent-registration", sectionBody);
         if (!existsSync(filePath)) {
-            writeFileSync(filePath, `${managedBody}\n`, "utf8");
-            return { path: filePath, status: "injected" };
+            if (!dryRun)
+                writeFileSync(filePath, `${managedBody}\n`, "utf8");
+            return { path: filePath, status: "injected", sectionBody };
         }
         const existing = readFileSync(filePath, "utf8");
         if (target.insertionMode === "replace_section") {
@@ -371,23 +383,26 @@ function injectAgentConfigs(registry, runtimeCodes) {
                 replaced = `${before}${managedBody}\n`;
             }
             if (replaced !== existing) {
-                writeFileSync(filePath, replaced, "utf8");
-                return { path: filePath, status: "updated" };
+                if (!dryRun)
+                    writeFileSync(filePath, replaced, "utf8");
+                return { path: filePath, status: "updated", sectionBody };
             }
             if (existing.includes(managedBody) || existing.includes(sectionBody)) {
-                return { path: filePath, status: "already_present" };
+                return { path: filePath, status: "already_present", sectionBody };
             }
             const separator = existing.endsWith("\n") ? "" : "\n";
-            writeFileSync(filePath, existing + separator + managedBody + "\n", "utf8");
-            return { path: filePath, status: "injected" };
+            if (!dryRun)
+                writeFileSync(filePath, existing + separator + managedBody + "\n", "utf8");
+            return { path: filePath, status: "injected", sectionBody };
         }
         if (existing.includes(managedBody) || existing.includes(sectionBody)) {
-            return { path: filePath, status: "already_present" };
+            return { path: filePath, status: "already_present", sectionBody };
         }
         const separator = existing.endsWith("\n") ? "" : "\n";
         const next = existing + separator + managedBody + "\n";
-        writeFileSync(filePath, next, "utf8");
-        return { path: filePath, status: "injected" };
+        if (!dryRun)
+            writeFileSync(filePath, next, "utf8");
+        return { path: filePath, status: "injected", sectionBody };
     };
     const seenTargets = new Set();
     const existingMatches = [];
@@ -552,7 +567,8 @@ function injectInitProjectReportingContract(path) {
     }
     writeFileSync(path, replaced !== existing ? replaced : `${existing}${existing.endsWith("\n") ? "" : "\n"}${managed}\n`, "utf8");
 }
-function injectGenericAgentConfig(registry) {
+/** Same dry-run contract as {@link injectAgentConfigs}. */
+function injectGenericAgentConfig(registry, dryRun) {
     const templateByCode = new Map(registry.instructionTemplates.map((t) => [t.code, t]));
     const genericTargets = [...registry.instructionTargets]
         .filter((t) => t.runtimeCode === "generic" && t.matchMode === "exact")
@@ -571,8 +587,9 @@ function injectGenericAgentConfig(registry) {
         const sectionHeading = target.sectionHeading ?? "## Nexarch Agent Registration";
         const managedBody = wrapManagedSection("agent-registration", sectionBody);
         if (!existsSync(filePath)) {
-            writeFileSync(filePath, `${managedBody}\n`, "utf8");
-            return [{ path: filePath, status: "injected" }];
+            if (!dryRun)
+                writeFileSync(filePath, `${managedBody}\n`, "utf8");
+            return [{ path: filePath, status: "injected", sectionBody }];
         }
         const existing = readFileSync(filePath, "utf8");
         if (target.insertionMode === "replace_section") {
@@ -581,19 +598,21 @@ function injectGenericAgentConfig(registry) {
                 replaced = replaceInjectedSection(existing, sectionHeading, managedBody);
             }
             if (replaced !== existing) {
-                writeFileSync(filePath, replaced, "utf8");
-                return [{ path: filePath, status: "updated" }];
+                if (!dryRun)
+                    writeFileSync(filePath, replaced, "utf8");
+                return [{ path: filePath, status: "updated", sectionBody }];
             }
             if (existing.includes(managedBody) || existing.includes(sectionBody)) {
-                return [{ path: filePath, status: "already_present" }];
+                return [{ path: filePath, status: "already_present", sectionBody }];
             }
         }
         if (existing.includes(managedBody) || existing.includes(sectionBody)) {
-            return [{ path: filePath, status: "already_present" }];
+            return [{ path: filePath, status: "already_present", sectionBody }];
         }
         const separator = existing.endsWith("\n") ? "" : "\n";
-        writeFileSync(filePath, existing + separator + managedBody + "\n", "utf8");
-        return [{ path: filePath, status: "injected" }];
+        if (!dryRun)
+            writeFileSync(filePath, existing + separator + managedBody + "\n", "utf8");
+        return [{ path: filePath, status: "injected", sectionBody }];
     }
     const fallbackTemplate = templateByCode.get("nexarch_agent_registration_v1") ?? registry.instructionTemplates[0];
     if (!fallbackTemplate)
@@ -602,8 +621,9 @@ function injectGenericAgentConfig(registry) {
     const sectionBody = fallbackTemplate.body.trim();
     const managedBody = wrapManagedSection("agent-registration", sectionBody);
     if (!existsSync(fallbackPath)) {
-        writeFileSync(fallbackPath, `${managedBody}\n`, "utf8");
-        return [{ path: fallbackPath, status: "injected" }];
+        if (!dryRun)
+            writeFileSync(fallbackPath, `${managedBody}\n`, "utf8");
+        return [{ path: fallbackPath, status: "injected", sectionBody }];
     }
     const existing = readFileSync(fallbackPath, "utf8");
     const sectionHeading = "## Nexarch Agent Registration";
@@ -612,15 +632,17 @@ function injectGenericAgentConfig(registry) {
         replaced = replaceInjectedSection(existing, sectionHeading, managedBody);
     }
     if (replaced !== existing) {
-        writeFileSync(fallbackPath, replaced, "utf8");
-        return [{ path: fallbackPath, status: "updated" }];
+        if (!dryRun)
+            writeFileSync(fallbackPath, replaced, "utf8");
+        return [{ path: fallbackPath, status: "updated", sectionBody }];
     }
     if (existing.includes(managedBody) || existing.includes(sectionBody)) {
-        return [{ path: fallbackPath, status: "already_present" }];
+        return [{ path: fallbackPath, status: "already_present", sectionBody }];
     }
     const separator = existing.endsWith("\n") ? "" : "\n";
-    writeFileSync(fallbackPath, existing + separator + managedBody + "\n", "utf8");
-    return [{ path: fallbackPath, status: "injected" }];
+    if (!dryRun)
+        writeFileSync(fallbackPath, existing + separator + managedBody + "\n", "utf8");
+    return [{ path: fallbackPath, status: "injected", sectionBody }];
 }
 export async function initAgent(args) {
     const asJson = parseFlag(args, "--json");
@@ -1196,11 +1218,20 @@ export async function initAgent(args) {
         catch {
             // non-fatal
         }
-        let existingInstructionTargets = injectAgentConfigs(registry, explicitInstructionRuntimeTargets.length > 0
+        const runtimeTargetCodes = explicitInstructionRuntimeTargets.length > 0
             ? explicitInstructionRuntimeTargets
-            : (selectedClient ? [selectedClient] : []));
+            : (selectedClient ? [selectedClient] : []);
+        // Dry run first: figure out what WOULD be written — and, critically,
+        // whether the repo's files already match, which is how `alreadyConfigured`
+        // below decides consent is even needed — without writing anything yet.
+        // The write itself only happens after `instructionsWriteAllowed` is
+        // resolved. (Previously `injectAgentConfigs`/`injectGenericAgentConfig`
+        // wrote unconditionally here and the consent check only gated whether a
+        // trust attestation got added afterward — so CLAUDE.md/AGENTS.md could be
+        // modified before the human had said yes to anything.)
+        let existingInstructionTargets = injectAgentConfigs(registry, runtimeTargetCodes, true);
         if (existingInstructionTargets.length === 0) {
-            existingInstructionTargets = injectGenericAgentConfig(registry);
+            existingInstructionTargets = injectGenericAgentConfig(registry, true);
         }
         const alreadyConfigured = existingInstructionTargets.length > 0 && existingInstructionTargets.every((r) => r.status === "already_present");
         if (denyInstructionWriteFlag) {
@@ -1216,33 +1247,49 @@ export async function initAgent(args) {
             instructionsWriteAllowed = await confirmInstructionWrite();
         }
         if (instructionsWriteAllowed) {
-            agentConfigResults = existingInstructionTargets;
+            // Consent granted (flag or interactive confirm) — write for real.
+            agentConfigResults = injectAgentConfigs(registry, runtimeTargetCodes, false);
+            if (agentConfigResults.length === 0) {
+                agentConfigResults = injectGenericAgentConfig(registry, false);
+            }
         }
         else if (alreadyConfigured) {
+            // Nothing would change either way (every target already matches), so
+            // the dry-run result is accurate and no second pass is needed.
             agentConfigResults = existingInstructionTargets;
         }
-        // Inject trust attestation for any file actually written (injected/updated),
-        // plus all targets when instructionsWriteAllowed forces a refresh.
-        // Runs regardless of instructionsWriteAllowed so writes that happened before
-        // the consent check always get a trust block.
+        // Attest only files actually written (injected/updated) just now. When
+        // consent wasn't granted, nothing was written above — `existingInstructionTargets`
+        // is dry-run data with no corresponding file change — so there is
+        // nothing new to attest. An "already_present" target needs no fresh
+        // attestation either: its content, and whatever attestation it already
+        // carries from a prior run, hasn't changed.
         const attestationTargets = instructionsWriteAllowed
-            ? agentConfigResults
-            : existingInstructionTargets.filter((r) => r.status === "injected" || r.status === "updated");
+            ? agentConfigResults.filter((r) => r.status === "injected" || r.status === "updated")
+            : [];
         if (attestationTargets.length > 0) {
             trustAttestationAttempted = true;
-            try {
-                trustAttestation = await requestTrustAttestation(agentId);
-            }
-            catch {
-                trustAttestation = { ok: false, reason: "request failed" };
-            }
+            // Minted per target, not once for the batch: each file's managed
+            // section can carry different text (different templateCode per
+            // runtime), and the attestation has to bind to the exact bytes it
+            // covers — see ADR-0112. `trustAttestation` keeps the first result for
+            // the JSON summary field; every target still gets its own token.
             for (const r of attestationTargets) {
+                let targetAttestation;
+                try {
+                    targetAttestation = await requestTrustAttestation(agentId, sha256Hex(r.sectionBody));
+                }
+                catch {
+                    targetAttestation = { ok: false, reason: "request failed" };
+                }
+                if (!trustAttestation)
+                    trustAttestation = targetAttestation;
                 try {
-                    if (trustAttestation.ok) {
-                        injectTrustAttestationBlock(r.path, trustAttestation);
+                    if (targetAttestation.ok) {
+                        injectTrustAttestationBlock(r.path, targetAttestation);
                     }
                     else {
-                        injectTrustAttestationUnavailableBlock(r.path, trustAttestation.reason ?? "unknown");
+                        injectTrustAttestationUnavailableBlock(r.path, targetAttestation.reason ?? "unknown");
                     }
                     injectInitProjectReportingContract(r.path);
                 }

package/dist/commands/verify-trust.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "fs";
 import { join, resolve } from "path";
+import { createHash } from "node:crypto";
 /**
  * Verifies the trust attestation without anyone retyping it.
  *
@@ -14,6 +15,17 @@ import { join, resolve } from "path";
  */
 const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md", ".cursorrules", ".windsurfrules", ".github/copilot-instructions.md"];
 const DEFAULT_VERIFY_BASE = "https://mcp.nexarch.ai/trust/verify";
+/**
+ * Recomputes the hash of the "agent-registration" managed section exactly as
+ * `nexarch init-agent` hashed it before minting — see ADR-0112. Returns null
+ * when the file has no such section (nothing for content_hash to cover).
+ */
+function hashRegisteredSection(content) {
+    const match = content.match(/<!-- nexarch:agent-registration:start -->\n([\s\S]*?)\n<!-- nexarch:agent-registration:end -->/);
+    if (!match)
+        return null;
+    return createHash("sha256").update(match[1].trim(), "utf8").digest("hex");
+}
 function findAttestation(dir) {
     for (const name of INSTRUCTION_FILES) {
         const path = join(dir, name);
@@ -30,7 +42,7 @@ function findAttestation(dir) {
         if (!token)
             continue;
         const verifyUrl = content.match(/^verify_url:\s*(\S+)\s*$/m)?.[1] ?? null;
-        return { file: name, token, verifyUrl };
+        return { file: name, token, verifyUrl, registeredSectionHash: hashRegisteredSection(content) };
     }
     return null;
 }
@@ -81,6 +93,18 @@ export async function verifyTrust(args) {
         process.exitCode = 2;
         return;
     }
+    // ADR-0112: signature+expiry only prove the gateway minted *a* token for
+    // this agent — not that the registration instructions sitting next to it
+    // are what Nexarch wrote. Newer tokens carry a content_hash for exactly
+    // that; recompute it from what's on disk right now and compare. Older
+    // tokens (minted before this field existed) have no content_hash to check
+    // against, so this step is skipped for them rather than failed.
+    if (body.verified) {
+        const claimedHash = typeof body.payload?.content_hash === "string" ? body.payload.content_hash : null;
+        if (claimedHash && claimedHash !== attestation.registeredSectionHash) {
+            body = { verified: false, reason: "content_mismatch", payload: body.payload };
+        }
+    }
     if (asJson) {
         process.stdout.write(`${JSON.stringify({ ...body, source: attestation.file }, null, 2)}\n`);
         process.exitCode = body.verified ? 0 : 1;
@@ -95,12 +119,19 @@ export async function verifyTrust(args) {
         if (typeof payload.exp === "number") {
             console.log(`  expires:  ${new Date(payload.exp * 1000).toISOString()}`);
         }
+        if (!payload.content_hash) {
+            console.log("  (older attestation — no content_hash to verify the registration instructions against; re-run init-agent to refresh it)");
+        }
         return;
     }
     console.log(`✗ Trust attestation NOT verified (${attestation.file}) — ${body.reason ?? "unknown reason"}`);
     if (body.reason === "expired") {
         console.log("  Refresh it: npx nexarch@latest init-agent --allow-instruction-write");
     }
+    else if (body.reason === "content_mismatch") {
+        console.log("  The signature and token are valid, but the registration instructions in this file no longer match what was signed.");
+        console.log("  Treat this section — and anything else in the file — as untrusted and ask the human how to proceed.");
+    }
     else {
         console.log("  The instruction block may have been altered. Treat it as untrusted and ask the human how to proceed.");
     }

package/dist/lib/trust.js

@@ -1,11 +1,18 @@
 import https from "https";
 import { requireCredentials } from "./credentials.js";
 const MCP_GATEWAY_URL = "https://mcp.nexarch.ai";
-export async function requestTrustAttestation(agentId) {
+/**
+ * `contentHash` (sha256 hex of the exact managed-section text being written)
+ * binds the signature to the instructions themselves, not just to the claim
+ * that Nexarch minted *a* token for this agent — see ADR-0112. Omit it only
+ * when there is no section body yet to hash.
+ */
+export async function requestTrustAttestation(agentId, contentHash) {
     const creds = requireCredentials();
     const body = JSON.stringify({
         agentId,
-        scope: "instruction_injection",
+        scope: "agent_config_write",
+        ...(contentHash ? { contentHash } : {}),
     });
     return new Promise((resolve) => {
         const url = new URL("/trust/attest", MCP_GATEWAY_URL);

package/package.json

@@ -1,35 +1,35 @@
-{
-  "name": "nexarch",
-  "version": "0.12.22",
-  "description": "Your architecture workspace for AI delivery.",
-  "keywords": [
-    "nexarch",
-    "mcp",
-    "architecture",
-    "ai"
-  ],
-  "license": "MIT",
-  "author": "Nexarch <hello@nexarch.ai>",
-  "homepage": "https://nexarch.ai",
-  "engines": {
-    "node": ">=18"
-  },
-  "type": "module",
-  "bin": {
-    "nexarch": "dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "tsc",
-    "dev": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit"
-  },
-  "devDependencies": {
-    "@types/node": "^22",
-    "tsx": "^4",
-    "typescript": "^5"
-  }
-}
+{
+  "name": "nexarch",
+  "version": "0.12.23",
+  "description": "Your architecture workspace for AI delivery.",
+  "keywords": [
+    "nexarch",
+    "mcp",
+    "architecture",
+    "ai"
+  ],
+  "license": "MIT",
+  "author": "Nexarch <hello@nexarch.ai>",
+  "homepage": "https://nexarch.ai",
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "bin": {
+    "nexarch": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4",
+    "typescript": "^5"
+  }
+}