@botbuddy/cli 1.23.0 → 1.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/commands.mjs

@@ -15,6 +15,7 @@ import { runWait } from "./wait.mjs";
 import { green, red, cyan, dim, bold, die } from "./utils.mjs";
 import { VERSION } from "./version.mjs";
 import { bootstrapProfile, ProfileBootstrapError, profileBootstrapRecovery, profileShellRefresh } from "./profile-bootstrap.mjs";
+import { setupMcpKey, revokeMcpKey, resolveMcpConfigKey, resolveEnvVarName, DEFAULT_MCP_ENV_VAR, McpKeyError, McpKeyStoreError } from "./mcp-key.mjs";
 import { runPw } from "./pw/run.mjs";
 import { maybeWarnStale, cmdUpdate } from "./update-check.mjs";
 
@@ -57,6 +58,7 @@ export async function run(argv, {
     case "pw": return runPw(args);
     case "profile": return cmdProfile(args);
     case "carrier": return cmdCarrier(args);
+    case "mcp": return cmdMcp(args);
     case "resources": return callTool("list_resources");
     case "agents": return callTool("list_agents");
     case "tasks": return readResource("botbuddy://tasks");
@@ -101,6 +103,13 @@ ${bold("AUTH")}
   carrier setup <profile>    CI hosts only: store an unattended tenant-bound carrier key
                              (interactive operators use ${cyan("login")} — it installs the client key)
 
+${bold("MCP CONFIG KEY")}
+  mcp setup [--env <NAME>] [--tenant <slug>] [--label <l>] [--expiry-days <n>]
+                             Mint a bb_mcp_ key for your .mcp.json (independently
+                             revocable; stored under ${dim("BOTBUDDY_MCP_KEY")})
+  mcp revoke <agent_id>      Revoke only that MCP key (login + sessions unaffected)
+  mcp status                 Which env var holds the MCP key (never prints it)
+
 ${bold("TOOLS")}
   help --tools               List every BotBuddy tool
   help <tool>                Show one tool's arguments
@@ -678,6 +687,233 @@ export async function cmdCarrier(args, {
   await runCarrierSetup(positionals[1], { log, setExitCode, bootstrap });
 }
 
+// ─── BOT-1607: `botbuddy mcp` — the tier-2 bb_mcp_ config key ────────────────
+
+function mcpHelp(log) {
+  log(`Usage: botbuddy mcp <setup|revoke|status> [options]
+
+  setup [--env <NAME>] [--tenant <slug>] [--label <label>] [--expiry-days <n>] [--force]
+                    Mint a bb_mcp_ MCP config key (authenticated by your
+                    ${cyan("botbuddy login")} owner/client credential), store it in the
+                    Keychain under ${dim("BOTBUDDY_MCP_KEY")} (or --env <NAME>), and print
+                    the .mcp.json / .codex/config.toml snippets that reference it.
+                    Refuses an occupied Keychain slot unless --force (revoke the
+                    old key first — --force leaves it live server-side).
+  revoke <agent_id> [--tenant <slug>] [--env <NAME>]
+                    Revoke ONLY that MCP key (returned by setup). Your login and
+                    live agent sessions keep working. Multi-tenant owners must
+                    pin the tenant the key was minted for with --tenant. Pass
+                    --env <NAME> and the receipt's cleanup command names that
+                    slot (revoke never deletes local Keychain items itself).
+  status [--env <NAME>]
+                    Report which env var holds the MCP config key (never prints
+                    the secret). ${dim("BOTBUDDY_BB_AGENT_KEY")} is honoured as a deprecated
+                    alias for one release.
+
+Present the key from .mcp.json instead of reusing an agent session token — it is
+independently revocable, so a leaked config credential rotates without a re-login.`);
+}
+
+// Actionable recovery for an mcp setup/revoke failure code.
+export function mcpRecovery(code) {
+  switch (code) {
+    case "not_authenticated":
+      return "run `botbuddy login` to install this machine's client key, then re-run `botbuddy mcp setup`.";
+    case "owner_required":
+      return "minting requires your owner/client credential — run `botbuddy login` (an agent or MCP key cannot mint a key).";
+    case "tenant_pin_required":
+      return "you belong to more than one tenant — pin the tenant the key lives in: `botbuddy mcp setup --tenant <slug>` (or `botbuddy mcp revoke <agent_id> --tenant <slug>`).";
+    case "mcp_key_store_failed":
+      return "the key was minted but not stored — unlock your login keychain (`security unlock-keychain`) and re-run `botbuddy mcp setup`.";
+    case "invalid_env_var":
+      return "--env must be an UPPER_SNAKE_CASE variable name, e.g. BOTBUDDY_MCP_KEY_WORK.";
+    case "reserved_env_var":
+      return "that --env name belongs to another BotBuddy credential (it would clobber that Keychain slot) — pick a distinct MCP var like BOTBUDDY_MCP_KEY_WORK.";
+    case "env_var_in_use":
+      return "that Keychain slot already holds a key — revoke the old server key (`botbuddy mcp revoke <agent_id>`) if it is still live, then clear the local slot with `security delete-generic-password -s <NAME>`; or use a different --env, or pass --force to replace it in place.";
+    case "keychain_read_failed":
+      return "couldn't read the Keychain to check the slot (locked/unavailable) — unlock it (`security unlock-keychain`) and retry, or pass --force to skip the check.";
+    case "not_an_mcp_key":
+      return "that agent_id is not a bb_mcp_ key — pass the agent_id `botbuddy mcp setup` returned.";
+    case "not_found":
+      return "no MCP key with that agent_id — check the id from `botbuddy mcp setup`.";
+    case "forbidden":
+      return "that key is not in the pinned tenant — pin the tenant it was minted for with `--tenant <slug>` (and you must be a member).";
+    case "tenant_forbidden":
+      return "you are not a member of the pinned tenant — pin one you belong to with `--tenant <slug>` (re-login won't fix a tenant mismatch).";
+    case "invalid_label":
+      return "--label requires a value, e.g. --label laptop.";
+    case "unexpected_arg":
+      return "botbuddy mcp setup takes no positional arguments — pass options like --env <NAME> / --tenant <slug> / --label <label>.";
+    default:
+      return "run `botbuddy login`, then re-run the command.";
+  }
+}
+
+export function parseMcpSetupArgs(args) {
+  const out = { envVar: DEFAULT_MCP_ENV_VAR, tenant: null, label: null, expiryDays: null, force: false };
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    const take = (flag) => (arg.startsWith(`${flag}=`) ? arg.slice(flag.length + 1) : args[++i]);
+    if (arg === "--force" || arg === "-f") { out.force = true; continue; }
+    if (arg === "--env" || arg.startsWith("--env=")) {
+      // Codex P2: a bare `--env` (no value) must NOT silently fall back to the
+      // default slot and mint there — distinguish a missing value from a missing
+      // option.
+      const val = take("--env");
+      if (val === undefined || val === "") throw new McpKeyError("invalid_env_var", { detail: "--env requires a variable name, e.g. BOTBUDDY_MCP_KEY_WORK" });
+      out.envVar = resolveEnvVarName(val);
+      continue;
+    }
+    if (arg === "--tenant" || arg.startsWith("--tenant=")) {
+      const value = take("--tenant");
+      if (typeof value !== "string" || !TENANT_SLUG_RE.test(value)) die("error: --tenant must be a lowercase slug");
+      out.tenant = value;
+      continue;
+    }
+    if (arg === "--label" || arg.startsWith("--label=")) {
+      // Codex P2: a bare `--label` (no value) must not silently mint an unlabeled
+      // key — a missing value is a usage error, like --env.
+      const val = take("--label");
+      if (val === undefined || val === "") throw new McpKeyError("invalid_label", { detail: "--label requires a value" });
+      out.label = val;
+      continue;
+    }
+    if (arg === "--expiry-days" || arg.startsWith("--expiry-days=")) {
+      const value = Number(take("--expiry-days"));
+      if (!Number.isInteger(value) || value <= 0) die("error: --expiry-days must be a positive integer");
+      out.expiryDays = value;
+      continue;
+    }
+    if (arg.startsWith("-")) die(`Unknown mcp setup option: ${arg}. Run ${cyan("botbuddy mcp --help")}.`);
+    // Codex P2: a stray positional (`mcp setup laptop`, or a misspelled option
+    // value) must be a usage error, not silently ignored while a live credential
+    // is minted with defaults. mcp setup takes options only.
+    throw new McpKeyError("unexpected_arg", { detail: arg });
+  }
+  return out;
+}
+
+// BOT-1607 (Codex P2): `mcp status` accepts the same `--env <NAME>` an install
+// used, so a custom install reports correctly. Returns the requested var name
+// (the default when the flag is absent); a bad name throws invalid_env_var.
+export function parseMcpStatusEnv(args) {
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--env" || arg.startsWith("--env=")) {
+      const raw = arg.startsWith("--env=") ? arg.slice("--env=".length) : args[++i];
+      if (raw === undefined || raw === "") throw new McpKeyError("invalid_env_var", { detail: "--env requires a variable name, e.g. BOTBUDDY_MCP_KEY_WORK" });
+      // Explicit selector → inspect exactly this var (canonical or custom).
+      // Read-only: the deprecated alias BOTBUDDY_BB_AGENT_KEY is allowed here.
+      return { envVar: resolveEnvVarName(raw, { forWrite: false }), explicit: true };
+    }
+    if (arg.startsWith("-")) die(`Unknown mcp status option: ${arg}. Run ${cyan("botbuddy mcp --help")}.`);
+  }
+  return { envVar: DEFAULT_MCP_ENV_VAR, explicit: false };
+}
+
+export async function cmdMcp(args, {
+  log = (line) => console.log(line),
+  setExitCode = (n) => { process.exitCode = n; },
+  setup = setupMcpKey,
+  revoke = revokeMcpKey,
+  resolveConfigKey = resolveMcpConfigKey,
+  env = process.env,
+} = {}) {
+  if (args[0] === "--help" || args[0] === "-h") return mcpHelp(log);
+  const sub = args.find((a) => !a.startsWith("-"));
+  if (!sub) return mcpHelp(log);
+
+  if (sub === "setup") {
+    try {
+      // Parse inside the try so a bad --env (missing value / reserved name) becomes
+      // an error receipt rather than an uncaught throw (Codex P2).
+      const opts = parseMcpSetupArgs(args);
+      log(JSON.stringify(await setup({ envVar: opts.envVar, tenant: opts.tenant, label: opts.label, expiryDays: opts.expiryDays, force: opts.force })));
+    } catch (error) {
+      const code = (error instanceof McpKeyError || error instanceof McpKeyStoreError) ? error.code : "mint_failed";
+      const extra = {};
+      if (error instanceof McpKeyStoreError) {
+        extra.detail = error.message;
+        // An un-rolled-back mint left a live orphan — name it so the operator
+        // can `botbuddy mcp revoke <id>` rather than pile up unusable keys.
+        if (!error.rolledBack && error.agentId) extra.orphan_agent_id = error.agentId;
+      }
+      log(JSON.stringify({ schema_version: 1, outcome: "error", error: code, ...extra, recovery: mcpRecovery(code) }));
+      setExitCode(3);
+    }
+    return;
+  }
+
+  if (sub === "revoke") {
+    // The server binds revocation to the pinned tenant (BOT-1607 Codex P1), so a
+    // multi-tenant owner must pin the tenant the key was minted for. --env names
+    // the local Keychain slot to clear after a successful revoke (Codex P2). Parse
+    // flag-aware so a flag value is not mistaken for an extra positional.
+    let agentId = null, tenant = null, envVar = null, extraPositionals = 0;
+    try {
+      for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--tenant" || arg.startsWith("--tenant=")) {
+          tenant = arg.startsWith("--tenant=") ? arg.slice("--tenant=".length) : args[++i];
+          if (typeof tenant !== "string" || !TENANT_SLUG_RE.test(tenant)) die("error: --tenant must be a lowercase slug");
+          continue;
+        }
+        if (arg === "--env" || arg.startsWith("--env=")) {
+          const raw = arg.startsWith("--env=") ? arg.slice("--env=".length) : args[++i];
+          if (raw === undefined || raw === "") throw new McpKeyError("invalid_env_var", { detail: "--env requires a variable name, e.g. BOTBUDDY_MCP_KEY_WORK" });
+          envVar = resolveEnvVarName(raw);
+          continue;
+        }
+        if (arg.startsWith("-")) die(`Unknown mcp revoke option: ${arg}. Run ${cyan("botbuddy mcp --help")}.`);
+        if (agentId == null) agentId = arg; else extraPositionals++;
+      }
+    } catch (error) {
+      const code = error instanceof McpKeyError ? error.code : "revoke_failed";
+      log(JSON.stringify({ schema_version: 1, outcome: "error", error: code, recovery: mcpRecovery(code) }));
+      setExitCode(3);
+      return;
+    }
+    if (!agentId || extraPositionals > 0) die("Usage: botbuddy mcp revoke <agent_id> [--tenant <slug>] [--env <NAME>]");
+    try {
+      log(JSON.stringify(await revoke({ agentId, tenant, envVar })));
+    } catch (error) {
+      const code = error instanceof McpKeyError ? error.code : "revoke_failed";
+      log(JSON.stringify({ schema_version: 1, outcome: "error", error: code, recovery: mcpRecovery(code) }));
+      setExitCode(3);
+    }
+    return;
+  }
+
+  if (sub === "status") {
+    let requested;
+    try {
+      requested = parseMcpStatusEnv(args);
+    } catch (error) {
+      const code = error instanceof McpKeyError ? error.code : "invalid_env_var";
+      log(JSON.stringify({ schema_version: 1, outcome: "error", error: code, recovery: mcpRecovery(code) }));
+      setExitCode(3);
+      return;
+    }
+    const resolved = resolveConfigKey(env, { envVar: requested.envVar, explicit: requested.explicit });
+    if (!resolved) {
+      log(JSON.stringify({ schema_version: 1, outcome: "status", configured: false, env_var: requested.envVar }));
+      return;
+    }
+    log(JSON.stringify({
+      schema_version: 1,
+      outcome: "status",
+      configured: true,
+      env_var: resolved.envVar,
+      deprecated: resolved.deprecated,
+      ...(resolved.notice ? { notice: resolved.notice } : {}),
+    }));
+    return;
+  }
+
+  die(`Unknown mcp subcommand: ${sub}. Run ${cyan("botbuddy mcp --help")}.`);
+}
+
 function cmdLock(args) {
   if (args.length < 2) die("Usage: botbuddy lock <resource_name> <type>");
   return callTool("acquire_lock", { resource_name: args[0], resource_type: args[1] });

package/src/credential-kinds.mjs

@@ -17,6 +17,9 @@ export const CREDENTIAL_PREFIXES = [
   { prefix: "mcp_at_", kind: "oauth", label: "OAuth owner token" },
   { prefix: "bb_pat_", kind: "pat", label: "personal access token" },
   { prefix: "bb_cli_", kind: "cli", label: "client key" },
+  // BOT-1607: the tier-2 MCP config key a .mcp.json presents (independently
+  // revocable; minted by `botbuddy mcp`). Unambiguous by prefix.
+  { prefix: "bb_mcp_", kind: "mcp", label: "MCP key" },
   // BOT-1573/1582 transition: bb_agent_ is now BOTH the per-session agent token
   // (BOT-1582 renamed it from bb_sess_) AND the older shared service carrier, so
   // the prefix ALONE can no longer tell them apart. Classification is display

package/src/mcp-key.mjs

@@ -0,0 +1,385 @@
+// BOT-1607 — `botbuddy mcp`: mint / revoke the tier-2 `bb_mcp_` MCP config key.
+//
+// A `.mcp.json` should present its OWN independently-revocable key, not the
+// reused `bb_agent_` session token `profile setup` planted in
+// BOTBUDDY_BB_AGENT_KEY. `botbuddy mcp setup` mints a `bb_mcp_` key —
+// authenticated by the tier-1 owner/client credential (resolveCallAuth: the
+// owner OAuth/client key from `botbuddy login`) — stores it in the Keychain
+// under a default-or-`--env` service, and prints the `.mcp.json` /
+// `.codex/config.toml` snippets that reference that var. `botbuddy mcp revoke`
+// invalidates ONLY that key, so a leaked config credential rotates without a
+// re-login or agent disruption.
+//
+// The mint/revoke calls are the server tools mint_mcp_key / revoke_mcp_key
+// (owner/client-gated). This module mirrors profile-bootstrap.mjs's dependency
+// injection so the whole flow is unit-testable with an injected call / auth /
+// keychain.
+
+import { keychainAvailable, readKeychainSecret, writeKeychainSecret } from "./agent-credential-store.mjs";
+import { callToolJson, resolveCallAuth } from "./api.mjs";
+import { SERVER_URL } from "./config.mjs";
+
+// The default env/Keychain var a `.mcp.json` references (BOT-1108 canonical set,
+// aligned with src/components/credentials/SetupSnippet.tsx). `--env <NAME>`
+// overrides it.
+export const DEFAULT_MCP_ENV_VAR = "BOTBUDDY_MCP_KEY";
+
+// BOT-1607 AC5: the pre-1607 var `profile setup` wrote the reused bb_agent_ session token into.
+// A `.mcp.json` still referencing it keeps authenticating for one release (the
+// server authenticates by hash regardless of which env var carried the key); the
+// CLI recognises it as a DEPRECATED alias and tells the operator to migrate.
+export const LEGACY_MCP_ENV_VAR = "BOTBUDDY_BB_AGENT_KEY";
+
+// A valid shell env-var / Keychain service name.
+const ENV_VAR_RE = /^[A-Z][A-Z0-9_]*$/;
+
+// BOT-1607 (Codex P2): --env doubles as the macOS Keychain service name, so a
+// name owned by ANOTHER BotBuddy credential kind would silently overwrite that
+// credential's Keychain slot (e.g. BOTBUDDY_CLIENT_KEY is the bb_cli_ token
+// `botbuddy login` installs). Refuse those; the MCP default var and its legacy
+// alias are fine, as is any distinct custom name (BOTBUDDY_MCP_KEY_WORK, …).
+const RESERVED_ENV_VARS = new Set([
+  "BOTBUDDY_CLIENT_KEY",     // bb_cli_ — botbuddy login client key
+  "BOTBUDDY_AGENT_KEY",      // bb_agent_ — per-session agent token
+  "BOTBUDDY_SVC_KEY",        // bb_svc_ — legacy carrier
+  "BOTBUDDY_CI_KEY",         // bb_ci_ — CI key
+  "BOTBUDDY_TOKEN",          // PAT / OAuth owner token
+  "BOTBUDDY_TEST_RUN_TOKEN", // publishable test-run token
+  "BOTBUDDY_SG_AGENT_KEY",   // Supply Guard profile Keychain slot (profileCredentialEnvironment) — never an MCP var
+]);
+
+// BOTBUDDY_BB_AGENT_KEY is dual-purpose: the deprecated MCP READ alias AND the
+// botbuddy profile Keychain slot (agent-credential-store profileCredentialEnvironment).
+// A `mcp status` (read-only) may name it, but `mcp setup`/`revoke` must NOT write
+// or delete it — that would clobber/destroy the profile client credential (Codex P2).
+// It is not in RESERVED_ENV_VARS so status can still resolve the legacy alias.
+
+export class McpKeyError extends Error {
+  constructor(code, { detail = null } = {}) {
+    super(detail ? `${code}: ${detail}` : code);
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+// A Keychain write failed AFTER minting succeeded. Distinct so the CLI never
+// mislabels a storage failure as an auth failure (AC2: a read-back mismatch /
+// locked keychain must fail loudly, never a silent success).
+export class McpKeyStoreError extends Error {
+  constructor(message, { cause, agentId = null, rolledBack = false } = {}) {
+    super(message);
+    this.name = "McpKeyStoreError";
+    this.code = "mcp_key_store_failed";
+    // BOT-1607 (Codex P2): the minted key's id + whether the best-effort rollback
+    // revoked it, so the receipt can point the operator at a manual revoke when
+    // an orphan key survives.
+    this.agentId = agentId;
+    this.rolledBack = rolledBack;
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+// A structured MCP error code on a tool-result body (`data.code`) or, for a
+// 401/403, on the auth receipt (`code`) callToolJson lifts out (BOT-1561).
+function structuredCode(response) {
+  if (typeof response?.data?.code === "string") return response.data.code;
+  if (typeof response?.code === "string") return response.code;
+  return null;
+}
+
+/** Validate an explicit `--env <NAME>`; the default needs no validation. */
+export function resolveEnvVarName(explicit, { forWrite = true } = {}) {
+  if (explicit == null) return DEFAULT_MCP_ENV_VAR;
+  const name = String(explicit).trim();
+  if (!ENV_VAR_RE.test(name)) {
+    throw new McpKeyError("invalid_env_var", { detail: `${explicit} (use UPPER_SNAKE_CASE)` });
+  }
+  if (RESERVED_ENV_VARS.has(name)) {
+    throw new McpKeyError("reserved_env_var", { detail: `${name} is owned by another BotBuddy credential; choose a distinct name like BOTBUDDY_MCP_KEY_WORK` });
+  }
+  // Only a WRITE (setup) or DELETE (revoke) into the botbuddy profile slot is
+  // dangerous; a read-only status may still resolve the deprecated MCP alias.
+  if (forWrite && name === LEGACY_MCP_ENV_VAR) {
+    throw new McpKeyError("reserved_env_var", { detail: `${name} is the botbuddy profile Keychain slot — mint/revoke into a dedicated MCP var like ${DEFAULT_MCP_ENV_VAR}` });
+  }
+  return name;
+}
+
+/**
+ * The consumer snippets for the MCP key — the SAME shape the web UI renders
+ * (src/components/credentials/SetupSnippet.tsx): a `.mcp.json` block and a
+ * `.codex/config.toml` block that reference `$envVar` (never the raw secret), and
+ * the macOS Keychain store-once command. Kept in sync by tests on both sides.
+ */
+export function mcpKeySnippets(envVar, { mcpUrl = SERVER_URL, loaderOnly = false } = {}) {
+  const mcpJson = JSON.stringify(
+    {
+      mcpServers: {
+        botbuddy: {
+          type: "http",
+          url: mcpUrl,
+          headers: { Authorization: `Bearer \${${envVar}}` },
+        },
+      },
+    },
+    null,
+    2,
+  );
+  // Codex does NOT interpolate ${VAR} inside a `headers` table (unlike Claude's
+  // .mcp.json above) — a literal `Bearer ${BOTBUDDY_MCP_KEY}` would be sent. Its
+  // supported env-backed auth is `bearer_token_env_var = "<NAME>"` (the same
+  // setting .codex/config.toml uses for the botbuddy server), so emit that.
+  const codexToml = `[mcp_servers.botbuddy]\ntype = "http"\nurl = "${mcpUrl}"\nbearer_token_env_var = "${envVar}"`;
+  // Storing the secret and EXPORTING it are two separate steps (README.md /
+  // AGENTS.md). Both client configs above read $envVar at launch, so the snippet
+  // must emit the Keychain-to-environment loader too — otherwise the operator
+  // stores the key, then launches Claude/Codex with $envVar unset (Codex P1).
+  // Mirrors the web keychain tab (SetupSnippet.tsx). The service name IS the var.
+  const load = `export ${envVar}="$(security find-generic-password -w -a "$USER" -s ${envVar})"`;
+  // loaderOnly (Codex P2): after a successful `mcp setup`, the key is ALREADY in
+  // the Keychain and its plaintext is intentionally not echoed — so the receipt
+  // must NOT show a `security add-generic-password -w` store prompt (the user has
+  // nothing to paste and could overwrite the valid key with garbage). Emit only
+  // the loader. The store+load pair is for the minted_no_keychain path, where the
+  // raw key is returned for the operator to place themselves.
+  const keychain = loaderOnly
+    ? `# Already stored in your Keychain by \`botbuddy mcp setup\` — load it into each shell:\n${load}`
+    : `# 1) Store once — prompted; nothing hits shell history\n`
+      + `security add-generic-password -U -a "$USER" -s ${envVar} -T /usr/bin/security -w\n\n`
+      + `# 2) Every subsequent shell (and the MCP client it launches) reads it back\n${load}`;
+  return { mcp_json: mcpJson, codex_toml: codexToml, keychain };
+}
+
+/**
+ * BOT-1607 AC5: resolve the MCP config key from the environment. Prefers
+ * BOTBUDDY_MCP_KEY; falls back to the deprecated BOTBUDDY_BB_AGENT_KEY alias with
+ * a migration notice. Never logs the key itself — only which var carries it.
+ */
+export function resolveMcpConfigKey(env = process.env, { envVar = null, explicit = false } = {}) {
+  const legacyNotice =
+    `${LEGACY_MCP_ENV_VAR} is a deprecated alias for ${DEFAULT_MCP_ENV_VAR} and will stop being read in a future release. `
+    + `Run \`botbuddy mcp setup\` to mint a dedicated ${DEFAULT_MCP_ENV_VAR} and update your .mcp.json.`;
+
+  // BOT-1607 (Codex P2): when `--env <NAME>` is EXPLICITLY supplied — a canonical
+  // name (default OR legacy alias) or a custom one — inspect exactly that
+  // variable, never the default-first fallback. Otherwise `status --env
+  // BOTBUDDY_BB_AGENT_KEY` (unset) could report BOTBUDDY_MCP_KEY, and vice versa.
+  if (explicit && envVar) {
+    const val = env?.[envVar];
+    if (typeof val === "string" && val) {
+      const deprecated = envVar === LEGACY_MCP_ENV_VAR;
+      return { envVar, key: val, deprecated, ...(deprecated ? { notice: legacyNotice } : {}) };
+    }
+    return null;
+  }
+
+  // No explicit selector: default → legacy-alias precedence.
+  const primary = env?.[DEFAULT_MCP_ENV_VAR];
+  if (typeof primary === "string" && primary) {
+    return { envVar: DEFAULT_MCP_ENV_VAR, key: primary, deprecated: false };
+  }
+  const legacy = env?.[LEGACY_MCP_ENV_VAR];
+  if (typeof legacy === "string" && legacy) {
+    return { envVar: LEGACY_MCP_ENV_VAR, key: legacy, deprecated: true, notice: legacyNotice };
+  }
+  return null;
+}
+
+// Map a mint_mcp_key server refusal code to a CLI error code the receipt reports.
+function mapMintCode(code) {
+  if (code === "MCP_TENANT_PIN_REQUIRED" || code === "MCP_TENANT_SELECTION_REQUIRED") return "tenant_pin_required";
+  if (code === "MCP_TENANT_MEMBERSHIP_REQUIRED") return "tenant_forbidden";
+  if (code === "mcp_key_owner_required") return "owner_required";
+  if (code === "owner_auth_required") return "not_authenticated";
+  return code || "mint_failed";
+}
+
+/**
+ * Mint a `bb_mcp_` key, authenticated by the tier-1 owner/client credential, and
+ * store it in the Keychain under `envVar` (read-back verified). On a host without
+ * a Keychain (BOTBUDDY_NO_KEYCHAIN / non-darwin) it is NOT persisted — the raw
+ * key is returned so the caller can place it in a secret store (CI should prefer
+ * a `bb_ci_` key, not a planted `bb_mcp_`).
+ */
+export async function setupMcpKey({
+  envVar = DEFAULT_MCP_ENV_VAR,
+  tenant = null,
+  label = null,
+  expiryDays = null,
+  force = false,
+  call = callToolJson,
+  resolveAuth = resolveCallAuth,
+  keychainAvailable: keychainAvail = keychainAvailable,
+  writeKeychain = writeKeychainSecret,
+  readKeychain = readKeychainSecret,
+  mcpUrl = SERVER_URL,
+} = {}) {
+  const pinned = await resolveAuth();
+  if (pinned?.error) throw new McpKeyError("not_authenticated");
+  const auth = pinned?.auth ?? null;
+
+  // Codex P1/P2: refuse to mint into an OCCUPIED Keychain slot unless --force.
+  // Re-running setup would `security -U`-overwrite the local secret AFTER a
+  // second server credential is minted, silently orphaning the previous, still
+  // ACTIVE bb_mcp_ row (its plaintext + agent_id no longer on this machine).
+  // Check BEFORE minting so a collision creates no new credential — and fail
+  // CLOSED: a STRICT read distinguishes a genuinely-empty slot from a transient
+  // read failure (a swallowed failure would look empty and overwrite a live key).
+  if (!force && keychainAvail()) {
+    let existing = null;
+    try {
+      existing = await readKeychain(envVar, { strict: true });
+    } catch (error) {
+      throw new McpKeyError("keychain_read_failed", { detail: error?.message ?? String(error) });
+    }
+    if (typeof existing === "string" && existing) {
+      throw new McpKeyError("env_var_in_use", { detail: envVar });
+    }
+  }
+
+  const args = {
+    ...(label ? { label } : {}),
+    ...(expiryDays != null ? { expiry_days: expiryDays } : {}),
+  };
+  const response = await call("mint_mcp_key", args, { auth, ...(tenant ? { tenant } : {}) });
+
+  const code = structuredCode(response);
+  // A 401/403 that carries a STRUCTURED tenant code (pin/membership) is not a
+  // credential failure — the login is valid, the tenant is wrong. Map it so the
+  // recovery is accurate; only a code-less refusal is a true auth failure (Codex P2).
+  if (response?.auth || (response?.ok === false && response?.error === "unauthorized")) {
+    if (code) throw new McpKeyError(mapMintCode(code));
+    throw new McpKeyError("not_authenticated");
+  }
+  if (!response?.ok || response.isError || response.data?.ok === false) {
+    throw new McpKeyError(mapMintCode(code));
+  }
+  const key = response.data?.api_key;
+  const agentId = response.data?.agent_id;
+  const tenantId = response.data?.tenant_id ?? tenant ?? null;
+  if (typeof key !== "string" || !key.startsWith("bb_mcp_") || typeof agentId !== "string") {
+    throw new McpKeyError("mint_failed");
+  }
+
+  let stored = false;
+  if (keychainAvail()) {
+    try {
+      // createOnly when !force makes the write itself the atomic guard: if the
+      // slot filled between the preflight read and here, `security` (no -U) fails
+      // "already exists" and we roll the just-minted key back below (Codex P2).
+      await writeKeychain(envVar, key, { createOnly: !force });
+      stored = true;
+    } catch (error) {
+      // AC2: a read-back mismatch / locked Keychain must fail LOUDLY — the key
+      // was minted, so never report success with an unverified store.
+      // Codex P2: the server already persisted the key. An un-stored key is an
+      // orphan the operator can't see to revoke, and every retry would mint
+      // another live row — so roll it back (best-effort) before failing. If the
+      // rollback itself fails, surface the agent_id so it can be revoked by hand.
+      let rolledBack = false;
+      try {
+        const undo = await call("revoke_mcp_key", { agent_id: agentId }, { auth, ...(tenant ? { tenant } : {}) });
+        rolledBack = Boolean(undo?.ok && !undo.isError && undo.data?.ok !== false);
+      } catch {
+        // keep rolledBack=false — the message tells the operator to revoke it.
+      }
+      // Codex P2: a create-only write can fail its read-back verification AFTER
+      // the item was created, leaving a stale item the strict occupied-slot
+      // preflight would then reject on retry — so always spell out clearing it.
+      const clearHint = `if a stale item remains under ${envVar}, clear it first with \`security delete-generic-password -s ${envVar}\`, then `;
+      const tail = rolledBack
+        ? `the freshly minted key was rolled back — unlock the Keychain, ${clearHint}re-run \`botbuddy mcp setup\`.`
+        : `the minted key could NOT be rolled back — revoke it with \`botbuddy mcp revoke ${agentId} --env ${envVar}\`, ${clearHint}re-run setup.`;
+      throw new McpKeyStoreError(
+        `minted the MCP key but could not store it in the macOS Keychain under ${envVar}: ${error?.message ?? error}; ${tail}`,
+        { cause: error, agentId, rolledBack },
+      );
+    }
+  }
+
+  return {
+    schema_version: 1,
+    outcome: stored ? "installed" : "minted_no_keychain",
+    // Codex P1: storing ≠ exporting. When stored in the Keychain, the key is not
+    // yet in the environment the MCP client reads — spell out the loader so the
+    // operator doesn't launch Claude/Codex with $envVar unset.
+    ...(stored
+      ? { next_step: `Load it into your shell (and the MCP client it launches): export ${envVar}="$(security find-generic-password -w -a "$USER" -s ${envVar})" — see snippets.keychain for the store+load pair.` }
+      : {}),
+    env_var: envVar,
+    key_prefix: "bb_mcp_",
+    agent_id: agentId,
+    tenant_id: tenantId,
+    // Only surface the raw key when it could NOT be stored (headless/CI), so the
+    // operator can place it themselves. On a Keychain host it is never echoed.
+    ...(stored ? {} : { api_key: key }),
+    // When stored, the snippet is loader-only (no store prompt for a key the user
+    // no longer has); otherwise it carries the store+load pair (Codex P2).
+    snippets: mcpKeySnippets(envVar, { mcpUrl, loaderOnly: stored }),
+  };
+}
+
+// Map a revoke_mcp_key server refusal to a CLI error code.
+function mapRevokeCode(code) {
+  if (code === "MCP_TENANT_PIN_REQUIRED" || code === "MCP_TENANT_SELECTION_REQUIRED") return "tenant_pin_required";
+  if (code === "MCP_TENANT_MEMBERSHIP_REQUIRED") return "tenant_forbidden";
+  if (code === "mcp_key_owner_required") return "owner_required";
+  if (code === "owner_auth_required") return "not_authenticated";
+  if (code === "mcp_key_wrong_kind") return "not_an_mcp_key";
+  if (code === "mcp_key_not_found") return "not_found";
+  if (code === "mcp_key_forbidden") return "forbidden";
+  return code || "revoke_failed";
+}
+
+/**
+ * Revoke a `bb_mcp_` key by its agent_id via the owner/client credential.
+ *
+ * The server binds revocation to the connection's authenticated tenant (BOT-1607
+ * Codex P1), so a multi-tenant owner MUST pin the tenant the key lives in — the
+ * same tenant `mcp setup --tenant` minted it for. Without `tenant` the call rides
+ * the repo profile's default pin and the server refuses a cross-tenant revoke,
+ * leaving the key live. Forward `--tenant` so `mcp revoke --tenant <slug>` works.
+ */
+export async function revokeMcpKey({
+  agentId,
+  tenant = null,
+  envVar = null,
+  call = callToolJson,
+  resolveAuth = resolveCallAuth,
+} = {}) {
+  if (typeof agentId !== "string" || !agentId.trim()) throw new McpKeyError("agent_id_required");
+  const id = agentId.trim();
+  const pinned = await resolveAuth();
+  if (pinned?.error) throw new McpKeyError("not_authenticated");
+  const auth = pinned?.auth ?? null;
+
+  const response = await call("revoke_mcp_key", { agent_id: id }, { auth, ...(tenant ? { tenant } : {}) });
+  const code = structuredCode(response);
+  // A structured tenant code (pin/membership) on a 401/403 is a tenant mismatch,
+  // not a credential failure — map it so recovery is accurate (Codex P2).
+  if (response?.auth || (response?.ok === false && response?.error === "unauthorized")) {
+    if (code) throw new McpKeyError(mapRevokeCode(code));
+    throw new McpKeyError("not_authenticated");
+  }
+  if (!response?.ok || response.isError || response.data?.ok === false) {
+    throw new McpKeyError(mapRevokeCode(code));
+  }
+
+  // The server key is now dead. The CLI does NOT delete the local Keychain slot
+  // itself (BOT-1607, Codex rounds 5–11): revoke is keyed by agent_id, which
+  // cannot be safely mapped to a machine Keychain slot — `--env` accepts any
+  // service name (a typo could name an unrelated secret), the probe/delete cannot
+  // be made atomic against a concurrent `mcp setup` (no OS compare-and-delete),
+  // and macOS offers no per-service cross-process lock. So we always hand back the
+  // exact, side-effect-free deletion command instead of deleting anything.
+  const slot = envVar || "<NAME>";
+  return {
+    schema_version: 1,
+    outcome: "revoked",
+    agent_id: id,
+    ...(envVar ? { env_var: envVar } : {}),
+    next_step:
+      `The server key is revoked. If a local Keychain slot still holds it, the next \`mcp setup\` will refuse that slot — `
+      + `clear it yourself with \`security delete-generic-password -s ${slot}\`.`,
+  };
+}