arcane-cli 0.29.6 → 0.30.0

package/dist/assets/.arcane/governance/authentication-strategy.md

@@ -193,7 +193,7 @@ Use this consistently across all credential storage:
 auth = { provider = "token", token = { source = "env", id = "SECRET_NAME" } }
 
 # In .env (never committed)
-SECRET_NAME=actual-secret-value-here
+SECRET_NAME={THE_REAL_VALUE}
 ```
 
 **Enforcement: explicitly advisory prose (ARC-023) — Arcane ships no config-schema validator or lint rule in this repository that checks a downstream repo's config for inline secrets versus this reference pattern; adoption depends on the operator's own discipline.**

package/dist/assets/.arcane/governance/threat-model.md

@@ -50,7 +50,7 @@ See also: [Hardening Checklist](hardening-checklist.md), [Authentication Strateg
 | Supply chain (package installs) | **Mitigated** | Global package installs use a user-owned directory, not a system directory. No `sudo` during install. |
 | Inter-machine communication | **Mitigated** | Encrypted mesh tunnel/VPN. No direct unencrypted LAN communication. |
 | Token/credential exposure (at rest) | **Mitigated** | Token stored as an env var in a `.env` file. Config uses a secret reference, not plaintext. State directory is mode `700`. |
-| Credential committed to version control | **Not mitigated** | Storage conventions are documented (secret references, `.gitignore` entries for `.env`/`*.pem`/`*.key`) but **no detection exists** — no scanner runs on the commit path, the push path, or in CI, and nothing verifies the conventions were followed. `spell-security-review`'s secrets step is an on-demand agent read, not a control. **Treat every credential that reaches a commit as compromised and rotate it — history, existing clones, and remote backups all survive deleting the file (EF-35). Enforcement: explicitly advisory prose (ARC-023) — rotating a leaked credential happens at the third-party provider that issued it; no Arcane mechanism can perform or verify that a specific credential was actually rotated.** |
+| Credential committed to version control | **Partially mitigated** (ARC-037) | A pattern-based scanner (`src/modules/secrets-scan.ts`) runs at two points: a pre-commit hook step (local, `--no-verify`-bypassable by design) and a repository-wide backstop inside `npm run build`'s existing CI gate (not bypassable, catches anything that skipped or bypassed the hook before merge) — plus an on-demand `spell doctor --leaks` for a manual check anytime. This is detection, not prevention: a regex denylist can miss non-standard credential shapes, and neither point runs on a commit that is never pushed. `spell-security-review`'s secrets step remains an on-demand agent read, not a control, and is unchanged by this. **Treat every credential that reaches a commit as compromised and rotate it — history, existing clones, and remote backups all survive deleting the file (EF-35). Enforcement: explicitly advisory prose (ARC-023) — rotating a leaked credential happens at the third-party provider that issued it; no Arcane mechanism can perform or verify that a specific credential was actually rotated.** |
 
 ---
 

package/dist/assets/.arcane.json

@@ -1,5 +1,11 @@
 {
     "selfHosted": true,
     "tracking_mode": "internal",
-    "external_provider": null
+    "external_provider": null,
+    "secretsScanExcludePrefixes": [
+        "test/copy-assets.test.ts",
+        "test/org-token-lint.test.ts",
+        "test/secrets-scan.test.ts",
+        "src/modules/secrets-scan.ts"
+    ]
 }

package/dist/index.js

@@ -112,6 +112,14 @@ function validateSubjectRoot(value, filePath) {
     throw new ManifestInvalidFieldError(filePath, "subject_root", value);
   }
 }
+function isValidSecretsScanExcludePrefixes(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.length > 0);
+}
+function validateSecretsScanExcludePrefixes(value, filePath) {
+  if (!isValidSecretsScanExcludePrefixes(value)) {
+    throw new ManifestInvalidFieldError(filePath, "secretsScanExcludePrefixes", value);
+  }
+}
 function manifestPath(targetDir) {
   return path2.join(targetDir, MANIFEST_FILE);
 }
@@ -138,6 +146,9 @@ function validateTrackingFields(manifest, filePath) {
     }
     validateSubjectRoot(manifest.subject_root, filePath);
   }
+  if (manifest.secretsScanExcludePrefixes !== void 0) {
+    validateSecretsScanExcludePrefixes(manifest.secretsScanExcludePrefixes, filePath);
+  }
 }
 async function readManifest(targetDir) {
   const filePath = manifestPath(targetDir);
@@ -159,6 +170,26 @@ async function readManifest(targetDir) {
   validateTrackingFields(manifest, filePath);
   return manifest;
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function resolveSecretsScanExcludePrefixes(targetDir) {
+  try {
+    const manifest = await readManifest(targetDir);
+    return manifest.secretsScanExcludePrefixes ?? [];
+  } catch {
+  }
+  try {
+    const raw = await readFile(path2.join(targetDir, "src", "assets", ".arcane.json"), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (isRecord(parsed) && parsed["selfHosted"] === true && parsed["tracking_mode"] === "internal") {
+      const prefixes = parsed["secretsScanExcludePrefixes"];
+      if (isValidSecretsScanExcludePrefixes(prefixes)) return prefixes;
+    }
+  } catch {
+  }
+  return [];
+}
 async function writeManifest(targetDir, manifest) {
   const filePath = manifestPath(targetDir);
   await writeFile(filePath, JSON.stringify(manifest, null, 2), "utf-8");
@@ -1100,11 +1131,11 @@ var AgentConfigValidationError = class extends Error {
     this.name = "AgentConfigValidationError";
   }
 };
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function requireRecord(value, path4, issues) {
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     issues.push(`${path4} must be an object`);
     return void 0;
   }
@@ -3624,8 +3655,8 @@ Run \`spell unblock-push\` first (interactive), then uninstall.`
 }
 
 // src/commands/doctor.ts
-import { access as access4, readFile as readFile6, mkdir as mkdir6, copyFile as fsCopyFile2 } from "fs/promises";
-import { join as join11, dirname as dirname3 } from "path";
+import { access as access4, readFile as readFile7, mkdir as mkdir6, copyFile as fsCopyFile2 } from "fs/promises";
+import { join as join12, dirname as dirname3 } from "path";
 import { execFile as execFile3 } from "child_process";
 import { promisify as promisify2 } from "util";
 
@@ -3694,6 +3725,111 @@ function evaluateIncidentGate(records) {
   };
 }
 
+// src/modules/denylist-scan.ts
+import { readFile as readFile6, readdir as readdir5 } from "fs/promises";
+import { join as join11, relative } from "path";
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function createDenylistRules(tokens, labelPrefix) {
+  return tokens.map((token, index) => ({
+    label: `${labelPrefix}-${index + 1}`,
+    pattern: new RegExp(
+      `(?:^|[^A-Za-z0-9])${escapeRegExp(token)}(?=$|[^A-Za-z0-9])`,
+      "i"
+    )
+  }));
+}
+async function scanFile(absolutePath, displayPath, rules) {
+  const findings = [];
+  let content;
+  try {
+    content = await readFile6(absolutePath, "utf8");
+  } catch {
+    return findings;
+  }
+  const lines = content.split("\n");
+  for (let index = 0; index < lines.length; index++) {
+    const searchable = lines[index].replace(/\{[A-Z][A-Z0-9_]*\}/g, "");
+    for (const rule of rules) {
+      if (rule.pattern.test(searchable)) {
+        findings.push({ file: displayPath, line: index + 1, rule: rule.label });
+        break;
+      }
+    }
+  }
+  return findings;
+}
+var SKIP_DIRECTORIES = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "coverage",
+  ".vitest",
+  ".claude"
+]);
+var DEFAULT_SCANNABLE_EXTENSIONS = [".md", ".ts", ".js", ".json", ".yml", ".yaml"];
+async function collectScannableFiles(root, repoRoot = root, extensions = DEFAULT_SCANNABLE_EXTENSIONS) {
+  const collected = [];
+  let entries;
+  try {
+    entries = await readdir5(root, { withFileTypes: true });
+  } catch {
+    return collected;
+  }
+  for (const entry of entries) {
+    const absolutePath = join11(root, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRECTORIES.has(entry.name)) continue;
+      collected.push(...await collectScannableFiles(absolutePath, repoRoot, extensions));
+    } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+      const displayPath = relative(repoRoot, absolutePath).replace(/\\/g, "/");
+      collected.push([absolutePath, displayPath]);
+    }
+  }
+  return collected;
+}
+async function scanRepository(repoRoot, rules, extensions, excludePrefixes = []) {
+  if (rules.length === 0) return [];
+  const findings = [];
+  for (const [absolutePath, displayPath] of await collectScannableFiles(repoRoot, repoRoot, extensions)) {
+    if (excludePrefixes.some((prefix) => displayPath.includes(prefix))) continue;
+    findings.push(...await scanFile(absolutePath, displayPath, rules));
+  }
+  return findings;
+}
+
+// src/modules/secrets-scan.ts
+var SECRETS_RULES = [
+  { label: "api-key", pattern: /API[_-]KEY\s*[:=]\s*\S+/i },
+  // Case-sensitive and requiring an all-caps/underscore identifier (SECRET,
+  // MY_SECRET, API_SECRET_KEY...) -- the real config/env-var convention for a
+  // credential-holding key. Widening this repository-wide (ARC-037 decision 3)
+  // surfaced that the original case-insensitive form matched ANY lowercase
+  // `secret`/`token` code identifier (e.g. `const token = value.trim();`),
+  // which is overwhelmingly a parsed/resolved value, never a literal
+  // credential. The `(?!\$?\{)` guard additionally excludes any
+  // brace-delimited placeholder -- GitHub Actions/templating references
+  // (`TOKEN: ${{ secrets.X }}`, a reference to a secret store, never the
+  // secret itself) and this codebase's own documented `{UPPER_SNAKE}`
+  // placeholder convention (denylist-scan.ts's `scanFile` already strips
+  // those before matching for the sibling org-token scan; a bare single
+  // brace, with no `scanFile`-style stripping in the copy-time call path,
+  // needed the same exclusion here rather than only the double-brace case).
+  // A minimum length of 8 further excludes short non-secret values like
+  // `write` (`id-token: write`).
+  { label: "generic-secret", pattern: /\b[A-Z0-9_]*SECRET[A-Z0-9_]*\s*[:=]\s*(?!\$?\{)\S{8,}/ },
+  { label: "generic-token", pattern: /\b[A-Z0-9_]*TOKEN[A-Z0-9_]*\s*[:=]\s*(?!\$?\{)\S{8,}/ },
+  { label: "bearer-token", pattern: /Bearer\s+[A-Za-z0-9._~+/-]{20,}/ },
+  // real tokens are long
+  { label: "openai-key", pattern: /sk-[A-Za-z0-9]{20,}/ },
+  { label: "pem-key", pattern: /-----BEGIN [A-Z ]+-----/ },
+  { label: "slack-token", pattern: /xox[bpars]-[A-Za-z0-9-]+/ },
+  { label: "aws-access-key", pattern: /AKIA[0-9A-Z]{16}/ },
+  { label: "github-pat", pattern: /ghp_[A-Za-z0-9]{36}/ }
+];
+var SECRETS_PATTERNS = SECRETS_RULES.map((rule) => rule.pattern);
+
 // src/modules/platform-policy.ts
 import { execFile as execFile2 } from "child_process";
 import { promisify } from "util";
@@ -3865,6 +4001,9 @@ function parseAdoRemote(url) {
 
 // src/commands/doctor.ts
 var execFileAsync2 = promisify2(execFile3);
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 async function checkNodeVersion() {
   const name = "Node.js version";
   const raw = process.version;
@@ -3882,8 +4021,8 @@ async function checkVSCodeExtension(id, label) {
   const name = `VS Code extension: ${label}`;
   const home = process.env["HOME"] ?? "";
   const extDirs = [
-    join11(home, ".vscode", "extensions"),
-    join11(home, ".vscode-insiders", "extensions")
+    join12(home, ".vscode", "extensions"),
+    join12(home, ".vscode-insiders", "extensions")
   ];
   for (const dir of extDirs) {
     try {
@@ -3917,15 +4056,15 @@ async function checkVSCodeExtension(id, label) {
 }
 async function checkArcaneManifest(targetDir) {
   const name = "Arcane manifest (.arcane.json)";
-  const manifestPath2 = join11(targetDir, ".arcane.json");
+  const manifestPath2 = join12(targetDir, ".arcane.json");
   try {
     await access4(manifestPath2);
   } catch {
-    const selfHostedManifestPath = join11(targetDir, "src", "assets", ".arcane.json");
+    const selfHostedManifestPath = join12(targetDir, "src", "assets", ".arcane.json");
     try {
-      const raw = await readFile6(selfHostedManifestPath, "utf8");
+      const raw = await readFile7(selfHostedManifestPath, "utf8");
       const manifest = JSON.parse(raw);
-      if (manifest.selfHosted === true && manifest.tracking_mode === "internal") {
+      if (isRecord3(manifest) && manifest["selfHosted"] === true && manifest["tracking_mode"] === "internal") {
         return {
           name,
           passed: true,
@@ -3942,9 +4081,9 @@ async function checkArcaneManifest(targetDir) {
     };
   }
   try {
-    const raw = await readFile6(manifestPath2, "utf8");
+    const raw = await readFile7(manifestPath2, "utf8");
     const manifest = JSON.parse(raw);
-    if (!manifest.version || !Array.isArray(manifest.components)) {
+    if (!isRecord3(manifest) || typeof manifest["version"] !== "string" || !manifest["version"] || !Array.isArray(manifest["components"])) {
       return {
         name,
         passed: false,
@@ -3954,7 +4093,7 @@ async function checkArcaneManifest(targetDir) {
     return {
       name,
       passed: true,
-      message: `v${manifest.version} \u2014 ${manifest.components.length} component(s) installed`
+      message: `v${manifest["version"]} \u2014 ${manifest["components"].length} component(s) installed`
     };
   } catch {
     return {
@@ -4003,6 +4142,20 @@ function checkIncidentReleaseGate() {
     message: `${result.checked} incidents classified${accepted}`
   };
 }
+async function checkSecrets(targetDir) {
+  const name = "Secrets scan (ARC-037)";
+  const excludePrefixes = await resolveSecretsScanExcludePrefixes(targetDir);
+  const findings = await scanRepository(targetDir, SECRETS_RULES, void 0, excludePrefixes);
+  if (findings.length === 0) {
+    return { name, passed: true, message: "no credential-shaped patterns found" };
+  }
+  const summary = findings.map((f) => `${f.file}:${f.line} [${f.rule}]`).join("; ");
+  return {
+    name,
+    passed: false,
+    message: `${findings.length} credential-shaped pattern(s) found: ${summary}`
+  };
+}
 var SESSION_CONTINUITY_FILES = [
   "TODO.md",
   "DECISIONS.md",
@@ -4013,7 +4166,7 @@ async function checkSessionContinuity(targetDir) {
   const results = [];
   for (const file of SESSION_CONTINUITY_FILES) {
     const name = `Session file: ${file}`;
-    const filePath = join11(targetDir, file);
+    const filePath = join12(targetDir, file);
     try {
       await access4(filePath);
       results.push({ name, passed: true, message: "present" });
@@ -4031,11 +4184,11 @@ async function checkSessionContinuity(targetDir) {
 async function fixSessionContinuity(targetDir, assetsDir) {
   const created = [];
   for (const file of SESSION_CONTINUITY_FILES) {
-    const destPath = join11(targetDir, file);
+    const destPath = join12(targetDir, file);
     try {
       await access4(destPath);
     } catch {
-      const srcPath = join11(assetsDir, file);
+      const srcPath = join12(assetsDir, file);
       await mkdir6(dirname3(destPath), { recursive: true });
       await fsCopyFile2(srcPath, destPath);
       created.push(file);
@@ -4096,16 +4249,16 @@ async function checkPushPolicy(targetDir) {
 }
 async function checkMcpConfig(targetDir) {
   const name = "MCP config (per-server timeout, I12)";
-  const filePath = join11(targetDir, ".mcp.json");
+  const filePath = join12(targetDir, ".mcp.json");
   let raw;
   try {
-    raw = await readFile6(filePath, "utf8");
+    raw = await readFile7(filePath, "utf8");
   } catch {
     return { name, passed: true, blocking: false, message: "no .mcp.json \u2014 nothing to check" };
   }
-  let parsed;
+  let rawParsed;
   try {
-    parsed = JSON.parse(raw);
+    rawParsed = JSON.parse(raw);
   } catch {
     return {
       name,
@@ -4114,6 +4267,15 @@ async function checkMcpConfig(targetDir) {
       message: ".mcp.json exists but contains invalid JSON"
     };
   }
+  if (!isRecord3(rawParsed)) {
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: ".mcp.json exists but is not a JSON object"
+    };
+  }
+  const parsed = rawParsed;
   const servers = parsed.mcpServers ?? {};
   const serverNames = Object.keys(servers);
   if (serverNames.length === 0) {
@@ -4135,18 +4297,24 @@ async function checkMcpConfig(targetDir) {
     message: `${serverNames.length} server(s) configured, all with a timeout set`
   };
 }
+function isDelegation(value) {
+  return isRecord3(value) && typeof value["id"] === "string" && typeof value["status"] === "string" && typeof value["scope"] === "string" && Array.isArray(value["excludedActions"]);
+}
+function isDelegationsFile(value) {
+  return isRecord3(value) && Array.isArray(value["delegations"]) && value["delegations"].every(isDelegation);
+}
 async function checkDelegations(targetDir) {
   const name = "Standing delegations (T13)";
-  const filePath = join11(targetDir, ".arcane", "delegations.json");
+  const filePath = join12(targetDir, ".arcane", "delegations.json");
   let raw;
   try {
-    raw = await readFile6(filePath, "utf8");
+    raw = await readFile7(filePath, "utf8");
   } catch {
     return { name, passed: true, blocking: false, message: "no delegations recorded" };
   }
-  let parsed;
+  let rawParsed;
   try {
-    parsed = JSON.parse(raw);
+    rawParsed = JSON.parse(raw);
   } catch {
     return {
       name,
@@ -4155,7 +4323,16 @@ async function checkDelegations(targetDir) {
       message: `.arcane/delegations.json exists but contains invalid JSON`
     };
   }
-  const active = (parsed.delegations ?? []).filter((d) => d.status === "active");
+  if (!isDelegationsFile(rawParsed)) {
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: `.arcane/delegations.json exists but is not a valid delegations file (expected a "delegations" array of well-formed entries)`
+    };
+  }
+  const parsed = rawParsed;
+  const active = parsed.delegations.filter((d) => d.status === "active");
   if (active.length === 0) {
     return { name, passed: true, blocking: false, message: "no active delegations" };
   }
@@ -4212,6 +4389,19 @@ async function checkPlatformBranchPolicy(targetDir) {
 }
 async function runDoctor(targetDir, options = {}, assetsDir) {
   console.log("\nspell doctor \u2014 checking your Arcane environment\n");
+  if (options.leaks) {
+    const result = await checkSecrets(targetDir);
+    const icon = result.passed ? "\u2713" : "\u2717";
+    console.log(`  ${icon} [${result.passed ? "pass" : "FAIL"}] ${result.name}`);
+    if (!result.passed) {
+      console.log(`         ${result.message}`);
+      console.log("\n  One or more checks failed. Fix the issues above before proceeding.\n");
+      process.exitCode = 1;
+    } else {
+      console.log("\n  All checks passed. Your environment is ready.\n");
+    }
+    return;
+  }
   const results = await Promise.all([
     checkNodeVersion(),
     checkVSCodeExtension("GitHub.copilot-chat", "GitHub Copilot (Chat)"),
@@ -4268,52 +4458,6 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
 // src/modules/ward.ts
 import { readdir as readdir6, readFile as readFile8 } from "fs/promises";
 import { join as join13, relative as relative2 } from "path";
-
-// src/modules/denylist-scan.ts
-import { readFile as readFile7, readdir as readdir5 } from "fs/promises";
-import { join as join12, relative } from "path";
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function createDenylistRules(tokens, labelPrefix) {
-  return tokens.map((token, index) => ({
-    label: `${labelPrefix}-${index + 1}`,
-    pattern: new RegExp(
-      `(?:^|[^A-Za-z0-9])${escapeRegExp(token)}(?=$|[^A-Za-z0-9])`,
-      "i"
-    )
-  }));
-}
-var SKIP_DIRECTORIES = /* @__PURE__ */ new Set([
-  "node_modules",
-  ".git",
-  "dist",
-  "coverage",
-  ".vitest"
-]);
-var DEFAULT_SCANNABLE_EXTENSIONS = [".md", ".ts", ".js", ".json", ".yml", ".yaml"];
-async function collectScannableFiles(root, repoRoot = root, extensions = DEFAULT_SCANNABLE_EXTENSIONS) {
-  const collected = [];
-  let entries;
-  try {
-    entries = await readdir5(root, { withFileTypes: true });
-  } catch {
-    return collected;
-  }
-  for (const entry of entries) {
-    const absolutePath = join12(root, entry.name);
-    if (entry.isDirectory()) {
-      if (SKIP_DIRECTORIES.has(entry.name)) continue;
-      collected.push(...await collectScannableFiles(absolutePath, repoRoot, extensions));
-    } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
-      const displayPath = relative(repoRoot, absolutePath).replace(/\\/g, "/");
-      collected.push([absolutePath, displayPath]);
-    }
-  }
-  return collected;
-}
-
-// src/modules/ward.ts
 async function scanFileAllRules(absolutePath, displayPath, rules) {
   const findings = [];
   let content;
@@ -4639,8 +4783,8 @@ program.command("uninstall").description("Remove all installed Arcane framework
 program.command("unblock-push").description("Lift this repository's push block (interactive terminal only)").action(async () => {
   await runUnblockPush(process.cwd());
 });
-program.command("doctor").description("Check your environment for Arcane prerequisites").option("--fix", "Automatically create missing session continuity files").action(async (opts) => {
-  await runDoctor(process.cwd(), { fix: opts.fix }, ASSETS_DIR);
+program.command("doctor").description("Check your environment for Arcane prerequisites").option("--fix", "Automatically create missing session continuity files").option("--leaks", "Run only the on-demand secrets/credential scan (ARC-037), skipping the default checks").action(async (opts) => {
+  await runDoctor(process.cwd(), { fix: opts.fix, leaks: opts.leaks }, ASSETS_DIR);
 });
 program.command("ward").description("Scan the repo for leaked identifiers -- third-party trademarks and the operator's own personal identifiers alike (T18)").option(
   "--terms <terms>",