ikanban 0.4.9 → 0.5.0

package/README.md

@@ -1,16 +1,21 @@
 # ikanban
 
 The iKanban command line. It scans your own repo on your machine and, when you ask, files the
-results into [iKanban](https://i-kanban.com).
+findings into [iKanban](https://i-kanban.com). Full reports and raw tool output stay on your
+machine, encrypted (see "Where scans are stored").
 
 ```bash
 npx ikanban secscan                 # dependencies, committed secrets, risky file permissions
 npx ikanban aiscan --help           # red-team scan of your AI app (OWASP LLM Top 10)
-npx ikanban secscan --publish       # also file the report and findings into iKanban
+npx ikanban secscan --publish       # also file the findings into iKanban
 npx ikanban infrascan --image app:1 # IaC misconfiguration and container image scan (Trivy)
 npx ikanban dastscan --url URL      # passive web scan of a registered URL (OWASP ZAP in Docker)
 npx ikanban dastscan --url URL --openapi openapi.json   # API scan of a registered URL (ZAP, active)
 npx ikanban cloudscan --aws-profile P --region R --account ID   # read-only AWS account audit (Prowler)
+npx ikanban controlscan --path .    # repository controls: CI audits, lockfiles, secret scanning, CODEOWNERS…
+npx ikanban import codeql.sarif --publish --team TEAM_ID   # another scanner's SARIF file as findings
+npx ikanban scans list              # the stored scans of this repository
+npx ikanban scans show <id>         # print a stored report (decrypted on this machine only)
 npx ikanban secscan --task IKA-123  # also show the run in that task's Pipelines
 npx ikanban roadmap sync plan.json  # make the Roadmap plan match the plan file
 npx ikanban hooks install           # sync plan files on every agent write and git push
@@ -73,17 +78,57 @@ peer conflict), `secscan` writes a lockfile for a copy of `package.json` in its
 `.npmrc`) and audits that copy. Nothing is written into the repository. If npm still cannot
 resolve the tree, the folder is SKIPPED with the fix: commit a `package-lock.json`.
 
-## Scan files
+## Where scans are stored
 
-Every scanner keeps its raw tool output and its report in `.iKanban/scans/<scanner>-<time>/` in
-the repository (`--work-dir PATH` or `IKANBAN_SCAN_DIR` to put it elsewhere). The folder holds its
-own `.gitignore`, so nothing in it is committed. Delete old runs whenever you like.
+Each scanner writes its report and raw tool output into a private temporary folder. When it
+ends, `ikanban` encrypts every file (AES-256-GCM) into
+`~/.ikanban/scans/<repo>-<8 hex>/<scanner>-<UTC time>/` (Windows: `%USERPROFILE%\.ikanban\scans`)
+and deletes the temporary folder. Nothing is written into the repository. `manifest.json` next to
+the encrypted files lists only file names, sizes, the time, the scanner and the repository path.
+
+```bash
+ikanban scans list [--repo PATH | --all]       # stored scans (default: this folder's repository)
+ikanban scans show <id> [file] [--out FILE]    # decrypt to the terminal (default report.md)
+ikanban scans migrate [--path PATH]            # seal old .iKanban/scans folders, remove the plain copies
+```
+
+The key is 32 random bytes, made on first use, and kept by the operating system:
+
+- macOS: the login keychain (service `ikanban-scan-store`).
+- Windows: DPAPI for the current user; the protected key is `%USERPROFILE%\.ikanban\scan-store.key.dpapi`.
+- Linux: the Secret Service through `secret-tool` (service `ikanban-scan-store`).
+- Anywhere else, or when the keychain fails, or with `IKANBAN_SCAN_STORE=file` (CI runners): an
+  owner-only file `~/.ikanban/scan-store.key`, and `ikanban` prints one line saying so.
+
+The key is never printed or put on a command line. A changed file or another machine's key gives
+a clear error, never garbled output. With `--work-dir PATH` the run folder in PATH is sealed and
+removed too. Under `ikanban`, a scanner prints its progress, the counts and
+`Full report: ikanban scans show <id>`; add `--print-report` to print the report itself. Running a
+`.py` scanner directly with Python keeps the old behaviour: the report prints, and the files stay
+in `.iKanban/scans/`.
+
+## Repository controls
+
+`controlscan` checks eight controls of the repository and gives each pass, warn, fail or skipped
+with the reason: a CI dependency audit (or Dependabot / Renovate), committed lockfiles, CI secret
+scanning, CI static analysis (SAST), no `.env` or key file in git, default-branch protection,
+CODEOWNERS and SECURITY.md. Branch protection, and GitHub secret scanning when CI has no secret
+scanner, are read with your own `gh` sign-in; without `gh` that check is skipped, never passed.
+`--publish` files one result per control; a failed control files one Medium finding, a warning
+one Low finding.
+
+## Import another scanner's results
+
+`ikanban import FILE.sarif` reads a SARIF 2.1.0 file (CodeQL, Semgrep, Trivy, Snyk…). A result
+whose rule carries a CWE becomes a code finding under the OWASP Top 10 2021 category that lists
+that CWE. A result with no CWE, or a CWE no category lists, stays in the local report as
+"not filed: no OWASP category". The SARIF file is never uploaded.
 
 ## Pipelines
 
 Every scanner takes `--task IKA-123` (or `IKANBAN_TASK`) and `--task-team` (default `--team`). The
 run then shows in that task's Pipelines view: running, then passed, failed or skipped with a
-one-line summary, and the masked report as its log. While the scan runs, the stage log gets one
+one-line summary. The report itself is never sent there. While the scan runs, the stage log gets one
 line as each step starts and ends. A plan without Pipelines never fails the scan.
 
 ## What you need
@@ -100,8 +145,11 @@ iKanban checks your plan when you publish; a plan that does not include it gets
 
 ## What it sends
 
-Nothing, unless you pass `--publish`. With `--publish`, the report and its findings go to iKanban.
-Secrets found in your repo are masked in the report before anything is sent.
+Nothing, unless you pass `--publish`. With `--publish`, only findings go to iKanban: title,
+category, severity, file and line, and the fix. Every text field is scrubbed on your machine first
+(secrets, keys and tokens cut, your home folder written as `~`), and again on the server. AI scan
+evidence (the attack, the answer, the grader's reason) is cut to 2,000 characters. Full reports,
+raw tool output and SARIF files stay on your machine.
 
 ## Licence
 

package/bin/ikanban.js

@@ -4,8 +4,10 @@
 // Scans run free on your machine; only --publish talks to iKanban, and the
 // server checks your plan there (a 402 means the plan, not the scan).
 const path = require("node:path");
-const { runCommand } = require("../lib/ikanban-safe.js");
 const { version } = require("../package.json");
+// Loaded when a scan needs it: `ikanban plan check` must run from a plain checkout, where the
+// copied lib/ikanban-safe.js is missing (the plan gate tells agents to run it there).
+const runCommand = (...a) => require("../lib/ikanban-safe.js").runCommand(...a);
 
 const COMMANDS = {
   aiscan: { file: "ikanban-aiscan.py", about: "Red-team scan of your AI app (OWASP LLM Top 10)" },
@@ -13,10 +15,12 @@ const COMMANDS = {
   infrascan: { file: "ikanban-infrascan.py", about: "Container image and IaC scan (needs Trivy)" },
   dastscan: { file: "ikanban-dastscan.py", about: "Web or API scan of a registered URL (needs Docker)" },
   cloudscan: { file: "ikanban-cloudscan.py", about: "Read-only AWS account audit (needs AWS CLI, Docker)" },
+  controlscan: { file: "ikanban-controlscan.py", about: "Repository security controls: CI audits, lockfiles, secret scanning, CODEOWNERS…" },
+  import: { file: "ikanban-import.py", about: "Turn another scanner's SARIF file into findings: import FILE.sarif" },
 };
 
 function help() {
-  const lines = Object.entries(COMMANDS).map(([n, c]) => `  ${n.padEnd(10)}${c.about}`);
+  const lines = Object.entries(COMMANDS).map(([n, c]) => `  ${n.padEnd(12)}${c.about}`);
   console.log(`ikanban ${version}
 
 Usage: ikanban <command> [options]
@@ -25,12 +29,14 @@ Commands:
 ${lines.join("\n")}
   roadmap  Keep a Roadmap plan in step with its plan file: roadmap sync [plan.json] [--check]
   hooks    Install the hooks that run that sync on every agent write and git push
+  plan     Check a plan file against the template: plan check FILE [--done]
 
   pipeline Report a task's stage and stream its log to iKanban (any CI)
 
 Run "ikanban <command> --help" for its options. Add --publish to file the
-results into iKanban (needs an API token; the server checks your plan), and
---task IKA-123 to show the run in that task's Pipelines.
+findings into iKanban (needs an API token; the server checks your plan), and
+--task IKA-123 to show the run in that task's Pipelines. Full reports and raw tool
+output stay on this machine, encrypted in ~/.ikanban/scans ("ikanban scans").
 Needs Python 3.9 or newer.`);
 }
 
@@ -62,6 +68,14 @@ if (cmd === "roadmap" || cmd === "hooks") {
   });
   return;
 }
+// Plan 7 P1: one shared definition of "a plan that passes", for every gate.
+if (cmd === "plan") {
+  Promise.resolve(require("../lib/plancheck.js").run(args)).then((code) => process.exit(code), (e) => {
+    console.error(`ikanban plan: ${e.message}`);
+    process.exit(1);
+  });
+  return;
+}
 // Plan 21 F10: report a task's pipeline stages and stream their logs, from any CI.
 if (cmd === "pipeline") {
   require("../lib/pipeline.js").run(args).then((code) => process.exit(code), (e) => {
@@ -70,6 +84,10 @@ if (cmd === "pipeline") {
   });
   return;
 }
+// Plan 5 X3: stored scans, decrypted on this machine only.
+if (cmd === "scans") {
+  process.exit(require("../lib/scanstore.js").run(args));
+}
 const command = COMMANDS[cmd];
 if (!command) {
   console.error(`ikanban: unknown command "${cmd}". Run "ikanban --help".`);
@@ -84,5 +102,30 @@ const [py, pre] = python;
 const script = path.join(__dirname, "..", "scanners", command.file);
 // Windows consoles default to cp1252, which lacks characters the reports print.
 const env = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
-const r = runCommand(py, [...pre, script, ...args], { stdio: "inherit", env });
-process.exit(r.status === null ? 1 : r.status);
+// Plan 5 X3: the scanner writes into a private temp folder (IKANBAN_SCAN_DIR); afterwards every
+// file is sealed into ~/.ikanban/scans and the folder is removed. The exit code is the scanner's.
+const optionValue = (name) => {
+  const i = args.indexOf(name);
+  if (i >= 0) return args[i + 1];
+  const eq = args.find((a) => a.startsWith(`${name}=`));
+  return eq ? eq.slice(name.length + 1) : undefined;
+};
+const repoPath = path.resolve(optionValue("--path") || ".");
+const workDir = optionValue("--work-dir"); // an explicit --work-dir run folder is sealed too
+const started = Date.now() - 2000;
+const extraDirs = () => {
+  if (!workDir) return [];
+  const fs = require("node:fs");
+  const dir = path.resolve(workDir);
+  if (!fs.existsSync(dir)) return [];
+  const runDir = new RegExp(`^${cmd}-\\d{8}-\\d{6}$`);
+  return fs.readdirSync(dir).filter((n) => runDir.test(n)).map((n) => path.join(dir, n))
+    .filter((p) => fs.statSync(p).isDirectory() && fs.statSync(p).mtimeMs >= started);
+};
+const store = require("../lib/scanstore.js").createStore();
+process.exit(store.runSealed({
+  scanner: cmd,
+  repoPath,
+  extraDirs,
+  run: (scanEnv) => runCommand(py, [...pre, script, ...args], { stdio: "inherit", env: { ...env, ...scanEnv } }).status,
+}));

package/hooks/deploy-check.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+// iKanban: after a deploy, check what the site serves before anyone reads it (plan 35 V1-T4).
+// An agent hook runs this after each shell command (Claude Code PostToolUse, Gemini CLI
+// AfterTool, Copilot CLI postToolUse; `npx ikanban hooks install` wires them). When the command
+// contains one of the deploy commands in .iKanban/settings-local.json "deploy_check":
+//   1. Bundle guard: it reads the site's build marker (build_url) and says PASS when the marker
+//      names the commit just deployed, else STALE: no reading of the site until it does.
+//   2. Intent check: it asks the agent to open site_url and show that the change does what the
+//      task asked, before it reports the deploy as done.
+// It runs no git command (it reads .git directly) and never blocks the agent: it always exits 0;
+// problems go to stderr. V13-T10: with the kit's api_url, api_key and team in settings-local.json,
+// it reports each result (pass, stale, intent) to iKanban for Observification; the key goes only
+// to iKanban's API (ikanbanFetch). The task is IKANBAN_TASK or the key in the branch name.
+// V16-T14: with those settings, iKanban decides (Agent settings → Pipelines → Deploy check): Off there
+// is off here, and its commands and addresses replace the local "deploy_check" block. The local block
+// is used only without the kit's API settings, or when iKanban does not answer and no copy is saved.
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { ikanbanFetch, teamId } = require("./ikanban-safe.js");
+
+const TIMEOUT_MS = 8000;
+// The app's settings are read once in 5 minutes: the hook runs after every shell command.
+const SETTINGS_TTL_MS = 5 * 60 * 1000;
+
+function repoRoot(cwd) {
+  for (let dir = fs.realpathSync(cwd); ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+function gitDir(root) {
+  const dot = path.join(root, ".git");
+  if (fs.statSync(dot).isDirectory()) return dot;
+  const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dot, "utf8"));
+  return m ? path.resolve(root, m[1].trim()) : null;
+}
+
+/** The commit HEAD names, read from .git (a worktree's commondir holds the shared refs). */
+function headSha(root) {
+  const dir = gitDir(root);
+  if (!dir) return null;
+  const head = fs.readFileSync(path.join(dir, "HEAD"), "utf8").trim();
+  if (/^[0-9a-f]{40}$/.test(head)) return head;
+  const ref = (/^ref:\s*(.+)$/.exec(head) || [])[1];
+  if (!ref) return null;
+  const common = fs.existsSync(path.join(dir, "commondir"))
+    ? path.resolve(dir, fs.readFileSync(path.join(dir, "commondir"), "utf8").trim())
+    : dir;
+  for (const d of [dir, common]) {
+    const f = path.join(d, ref);
+    if (fs.existsSync(f)) return fs.readFileSync(f, "utf8").trim();
+  }
+  const packed = path.join(common, "packed-refs");
+  if (!fs.existsSync(packed)) return null;
+  const line = fs.readFileSync(packed, "utf8").split("\n").find((l) => l.endsWith(` ${ref}`));
+  return line ? line.split(" ")[0] : null;
+}
+
+function kitSettings(root) {
+  for (const kit of [".iKanban", ".i-kanban"]) {
+    const f = path.join(root, kit, "settings-local.json");
+    if (!fs.existsSync(f)) continue;
+    try {
+      return JSON.parse(fs.readFileSync(f, "utf8")) || {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+function taskKey(root) {
+  const own = (process.env.IKANBAN_TASK || "").trim();
+  if (/^[A-Za-z][A-Za-z0-9]{0,9}-\d+$/.test(own)) return own.toUpperCase();
+  let head = "";
+  try { head = fs.readFileSync(path.join(gitDir(root), "HEAD"), "utf8"); } catch { return undefined; }
+  const branch = (/^ref:\s*refs\/heads\/(.+)$/m.exec(head) || [])[1] || "";
+  const m = /(?:^|[/_-])([A-Za-z][A-Za-z0-9]{0,9}-\d+)(?=$|[/_-])/.exec(branch.trim());
+  return m ? m[1].toUpperCase() : undefined;
+}
+
+/** V13-T10: one result to iKanban; best effort, never in the agent's way. */
+async function report(kit, body) {
+  if (!kit.api_url || !kit.api_key || !kit.team) return;
+  try {
+    const team = await teamId({ base: kit.api_url, token: kit.api_key, team: kit.team });
+    const res = await ikanbanFetch(`/api/teams/${encodeURIComponent(team)}/deploy-checks`, {
+      base: kit.api_url, token: kit.api_key, method: "POST", body, timeoutMs: 4000,
+    });
+    if (!res.ok) throw new Error(`iKanban answered ${res.status}`);
+  } catch (e) {
+    process.stderr.write(`iKanban deploy check: not reported (${e.message})\n`);
+  }
+}
+
+/** V16-T14: the team's deploy check from iKanban; null when it does not answer. */
+async function appSettings(kit) {
+  const file = path.join(os.homedir(), ".ikanban", "deploy-check", `${String(kit.team).replace(/[^A-Za-z0-9-]/g, "_")}.json`);
+  let saved = null;
+  try {
+    saved = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    saved = null;
+  }
+  const mine = saved && saved.api_url === kit.api_url && saved.settings && typeof saved.settings.enabled === "boolean";
+  if (mine && Date.now() - saved.at < SETTINGS_TTL_MS) return saved.settings;
+  try {
+    const team = await teamId({ base: kit.api_url, token: kit.api_key, team: kit.team });
+    const res = await ikanbanFetch(`/api/teams/${encodeURIComponent(team)}/deploy-check-settings`, { base: kit.api_url, token: kit.api_key, timeoutMs: 3000 });
+    if (!res.ok) throw new Error(`iKanban answered ${res.status}`);
+    const d = ((await res.json()) || {}).data || {};
+    if (typeof d.enabled !== "boolean") throw new Error("no deploy check settings in the answer");
+    const settings = { enabled: d.enabled, commands: Array.isArray(d.commands) ? d.commands : [], build_url: d.build_url || undefined, site_url: d.site_url || undefined };
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, JSON.stringify({ at: Date.now(), api_url: kit.api_url, settings }));
+    } catch {
+      // the saved copy only spares a request
+    }
+    return settings;
+  } catch (e) {
+    process.stderr.write(`iKanban deploy check: settings not read from iKanban (${e.message})\n`);
+    return mine ? saved.settings : null;
+  }
+}
+
+/** The deploy check in force: iKanban's when the kit can ask it, else the local block. */
+async function settingsFor(kit) {
+  if (kit.api_url && kit.api_key && kit.team) {
+    const app = await appSettings(kit);
+    if (app) return app.enabled ? app : null;
+  }
+  return kit.deploy_check || null;
+}
+
+/** The shell command from any of the three agents' hook input. */
+function commandOf(event) {
+  let args = event.tool_input || event.toolArgs || event.tool_args || {};
+  if (typeof args === "string") {
+    try { args = JSON.parse(args); } catch { return ""; }
+  }
+  return args && typeof args.command === "string" ? args.command : "";
+}
+
+/** C1: build_url comes from a settings file, so only https, or http to this laptop. */
+function allowedUrl(raw) {
+  try {
+    const u = new URL(raw);
+    return u.protocol === "https:" || (u.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(u.hostname));
+  } catch {
+    return false;
+  }
+}
+
+/** Security review: the site URL reaches the agent as text, so only an origin and a short plain path:
+ *  no sign-in, query or fragment (the same rule as check_deploy_settings on the server). */
+function cleanUrl(raw) {
+  if (typeof raw !== "string" || raw.length > 200 || /[\s\u0000-\u001f\u007f]/.test(raw) || !allowedUrl(raw)) return null;
+  const u = new URL(raw);
+  if (u.username || u.password || u.search || u.hash || u.hostname.length > 100 || !/^[A-Za-z0-9/._~-]{1,100}$/.test(u.pathname)) return null;
+  return u.origin + u.pathname;
+}
+
+async function bundleGuard(cfg, sha) {
+  const short = sha ? sha.slice(0, 7) : "";
+  if (!cfg.build_url) return "Bundle guard: no build_url in deploy_check, so the served build is unknown; read the site's build marker yourself before any check.";
+  if (!allowedUrl(cfg.build_url)) return `Bundle guard: not run: build_url must be https (or http on localhost): ${cfg.build_url}`;
+  if (!short) return "Bundle guard: could not read this repository's HEAD commit.";
+  let body;
+  try {
+    const res = await fetch(cfg.build_url, { redirect: "error", signal: AbortSignal.timeout(TIMEOUT_MS), headers: { "cache-control": "no-cache" } });
+    body = (await res.text()).slice(0, 4000);
+  } catch (e) {
+    return `Bundle guard: could not read ${cfg.build_url} (${e.message}). Read it again before any check of the site.`;
+  }
+  if (body.includes(short)) return `Bundle guard: PASS: ${cfg.build_url} serves commit ${sha.slice(0, 8)}, the one just deployed.`;
+  return `Bundle guard: STALE: ${cfg.build_url} does not name commit ${sha.slice(0, 8)} yet (it says: ${body.replace(/\s+/g, " ").slice(0, 120)}). Do not read or check the site until it does: wait for the deploy, then read the marker again.`;
+}
+
+async function main(input) {
+  let event = {};
+  try { event = JSON.parse(input || "{}"); } catch { return {}; }
+  if (!event || typeof event !== "object") return {};
+  const cwd = typeof event.cwd === "string" && fs.existsSync(event.cwd) ? event.cwd : process.cwd();
+  const root = repoRoot(cwd);
+  const kit = root ? kitSettings(root) : {};
+  const command = commandOf(event);
+  if (!command) return {};
+  const cfg = await settingsFor(kit);
+  if (!cfg || !Array.isArray(cfg.commands)) return {};
+  if (!cfg.commands.some((c) => typeof c === "string" && c.trim() && command.includes(c.trim()))) return {};
+  // Gemini CLI also calls AfterTool for a failed command; a failed deploy has nothing to check.
+  if (event.tool_response && event.tool_response.error) return {};
+  const sha = headSha(root);
+  const guard = await bundleGuard(cfg, sha);
+  const result = guard.startsWith("Bundle guard: PASS") ? "pass" : guard.startsWith("Bundle guard: STALE") ? "stale" : null;
+  const siteUrl = cleanUrl(cfg.site_url);
+  const common = { site: siteUrl || undefined, commit: sha || undefined, task: taskKey(root) };
+  if (result) await report(kit, { result, ...common });
+  await report(kit, { result: "intent", ...common });
+  const site = siteUrl ? ` Open "${siteUrl}"` : " Open the deployed site";
+  const text = `${guard}\nIntent check:${site} in the browser once the bundle guard passes, and show that the change does what the task asked (the screen, the number, the flow), on the page a user would open. Report what you saw; "deployed" alone is not a check.`;
+  // Copilot CLI reads a top-level additionalContext; Claude Code and Gemini CLI read hookSpecificOutput.
+  if (event.toolName !== undefined || event.toolArgs !== undefined) return { additionalContext: text };
+  return { hookSpecificOutput: { hookEventName: event.hook_event_name || "PostToolUse", additionalContext: text } };
+}
+
+let input = "";
+process.stdin.on("data", (c) => { input += c; });
+process.stdin.on("end", async () => {
+  let out = {};
+  try {
+    out = await main(input);
+  } catch (e) {
+    process.stderr.write(`iKanban deploy check: ${e.message}\n`);
+  }
+  process.stdout.write(`${JSON.stringify(out)}\n`);
+  process.exit(0);
+});

package/hooks/ikanban-safe.js

@@ -64,16 +64,20 @@ function apiOrigin(base) {
 
 /**
  * fetch() to iKanban's API. opts: base (the signed-in api_url), token, method, body (sent as
- * JSON), timeoutMs. Refuses another host, an absolute or protocol-relative path, and redirects.
+ * JSON), timeoutMs, headers (only X-Trace-Token is passed on). Refuses another host, an absolute or protocol-relative path, and redirects.
  */
-async function ikanbanFetch(apiPath, { base, token, method = "GET", body, timeoutMs = 60000 } = {}) {
+async function ikanbanFetch(apiPath, { base, token, method = "GET", body, timeoutMs = 60000, headers: extra = {} } = {}) {
   const origin = apiOrigin(base);
   if (typeof apiPath !== "string" || !apiPath.startsWith("/") || apiPath.startsWith("//")) {
     throw new Error(`"${apiPath}" is not a path on the iKanban API; the key was not sent`);
   }
   const url = new URL(apiPath, origin);
   if (url.origin !== origin) throw new Error(`"${apiPath}" leaves ${origin}; the key was not sent`);
+  // Plan 35: X-Trace-Token (a trace's write token) is the one extra header; nothing may replace the key's.
   const headers = { Authorization: `Bearer ${token}` };
+  for (const [k, v] of Object.entries(extra)) {
+    if (k.toLowerCase() === "x-trace-token" && typeof v === "string" && /^[A-Za-z0-9]{16,128}$/.test(v)) headers["X-Trace-Token"] = v;
+  }
   if (body !== undefined) headers["Content-Type"] = "application/json";
   let res;
   try {
@@ -93,4 +97,23 @@ async function ikanbanFetch(apiPath, { base, token, method = "GET", body, timeou
   return res;
 }
 
-module.exports = { runCommand, startCommand, ikanbanFetch, apiOrigin };
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** The team's id for API paths. Set up writes the team's key ("IKA") into settings-local.json,
+ *  and the API's routes take the id, so a key is looked up among the caller's teams. */
+async function teamId({ base, token, team }) {
+  if (UUID.test(String(team || ""))) return team;
+  const res = await ikanbanFetch("/api/teams", { base, token, timeoutMs: 5000 });
+  if (!res.ok) throw new Error(`iKanban answered ${res.status} for the team list`);
+  const json = await res.json();
+  const list = Array.isArray(json.data) ? json.data : (json.data && json.data.teams) || [];
+  // Security review: the key first; a name only when no key matches; never a guess between two.
+  const want = String(team || "").toLowerCase();
+  const byKey = list.filter((t) => String(t.identifier || "").toLowerCase() === want);
+  const hits = byKey.length ? byKey : list.filter((t) => String(t.name || "").toLowerCase() === want);
+  if (hits.length > 1) throw new Error(`more than one team is called "${team}"; put the team's id in settings-local.json`);
+  if (!hits.length || !UUID.test(String(hits[0].id))) throw new Error(`no team "${team}" for this key`);
+  return hits[0].id;
+}
+
+module.exports = { runCommand, startCommand, ikanbanFetch, apiOrigin, teamId };