@i4ctime/q-ring 0.14.1 → 0.16.0

package/dist/index.js

@@ -38,13 +38,14 @@ import {
   removeHook,
   revokeApproval,
   serviceForScope,
+  setAuditAgentLabel,
   setSecret,
   tunnelCreate,
   tunnelDestroy,
   tunnelList,
   tunnelRead,
   verifyAuditChain
-} from "./chunk-C2TFJ2EH.js";
+} from "./chunk-5LFKBZ3Q.js";
 
 // src/cli/commands.ts
 import { Command, Help } from "commander";
@@ -764,6 +765,79 @@ var ProviderRegistry = class {
     return [...this.providers.values()];
   }
 };
+function livenessProvider(cfg) {
+  return {
+    name: cfg.name,
+    description: cfg.description,
+    prefixes: cfg.prefixes,
+    async validate(value) {
+      const start = Date.now();
+      try {
+        const { statusCode } = await makeRequest(cfg.url, {
+          "User-Agent": "q-ring-validator/1.0",
+          ...cfg.headers(value)
+        });
+        const latencyMs = Date.now() - start;
+        if (statusCode === 200)
+          return { valid: true, status: "valid", message: "API key is valid", latencyMs, provider: cfg.name };
+        if (statusCode === 401 || statusCode === 403)
+          return { valid: false, status: "invalid", message: `Invalid or revoked API key (${statusCode})`, latencyMs, provider: cfg.name };
+        if (statusCode === 429)
+          return { valid: true, status: "error", message: "Rate limited \u2014 key may be valid", latencyMs, provider: cfg.name };
+        return { valid: false, status: "error", message: `Unexpected status ${statusCode}`, latencyMs, provider: cfg.name };
+      } catch (err) {
+        return { valid: false, status: "error", message: `${err instanceof Error ? err.message : "Network error"}`, latencyMs: Date.now() - start, provider: cfg.name };
+      }
+    }
+  };
+}
+var anthropicProvider = livenessProvider({
+  name: "anthropic",
+  description: "Anthropic API key validation",
+  prefixes: ["sk-ant-"],
+  url: "https://api.anthropic.com/v1/models?limit=1",
+  headers: (value) => ({ "x-api-key": value, "anthropic-version": "2023-06-01" })
+});
+var openrouterProvider = livenessProvider({
+  name: "openrouter",
+  description: "OpenRouter API key validation",
+  prefixes: ["sk-or-"],
+  url: "https://openrouter.ai/api/v1/key",
+  headers: (value) => ({ Authorization: `Bearer ${value}` })
+});
+var googleAiProvider = livenessProvider({
+  name: "google-ai",
+  description: "Google AI (Gemini) API key validation",
+  prefixes: ["AIza"],
+  url: "https://generativelanguage.googleapis.com/v1beta/models?pageSize=1",
+  headers: (value) => ({ "x-goog-api-key": value })
+});
+var groqProvider = livenessProvider({
+  name: "groq",
+  description: "Groq API key validation",
+  prefixes: ["gsk_"],
+  url: "https://api.groq.com/openai/v1/models",
+  headers: (value) => ({ Authorization: `Bearer ${value}` })
+});
+var huggingfaceProvider = livenessProvider({
+  name: "huggingface",
+  description: "Hugging Face token validation",
+  prefixes: ["hf_"],
+  url: "https://huggingface.co/api/whoami-v2",
+  headers: (value) => ({ Authorization: `Bearer ${value}` })
+});
+var elevenlabsProvider = livenessProvider({
+  name: "elevenlabs",
+  description: "ElevenLabs API key validation (explicit-only \u2014 set provider on the secret)",
+  url: "https://api.elevenlabs.io/v1/user",
+  headers: (value) => ({ "xi-api-key": value })
+});
+var vercelProvider = livenessProvider({
+  name: "vercel",
+  description: "Vercel token validation (explicit-only \u2014 set provider on the secret)",
+  url: "https://api.vercel.com/v2/user",
+  headers: (value) => ({ Authorization: `Bearer ${value}` })
+});
 var openaiProvider = {
   name: "openai",
   description: "OpenAI API key validation",
@@ -890,7 +964,14 @@ var httpProvider = {
   }
 };
 var registry2 = new ProviderRegistry();
+registry2.register(anthropicProvider);
+registry2.register(openrouterProvider);
 registry2.register(openaiProvider);
+registry2.register(googleAiProvider);
+registry2.register(groqProvider);
+registry2.register(huggingfaceProvider);
+registry2.register(elevenlabsProvider);
+registry2.register(vercelProvider);
 registry2.register(stripeProvider);
 registry2.register(githubProvider);
 registry2.register(awsProvider);
@@ -1984,10 +2065,9 @@ var RedactionTransform = class extends Transform {
     callback();
   }
 };
-async function execCommand(opts) {
-  const profile = getProfile(opts.profile);
-  const fullCommand = [opts.command, ...opts.args].join(" ");
-  const policyDecision = checkExecPolicy(fullCommand, opts.projectPath);
+function enforceExecPolicy(profile, command, args, projectPath) {
+  const fullCommand = [command, ...args].join(" ");
+  const policyDecision = checkExecPolicy(fullCommand, projectPath);
   if (!policyDecision.allowed) {
     throw new Error(`Policy Denied: ${policyDecision.reason}`);
   }
@@ -2003,9 +2083,13 @@ async function execCommand(opts) {
   if (profile.allowCommands) {
     const allowed = profile.allowCommands.some((a) => fullCommand.startsWith(a));
     if (!allowed) {
-      throw new Error(`Exec profile "${profile.name}" does not allow command "${opts.command}"`);
+      throw new Error(`Exec profile "${profile.name}" does not allow command "${command}"`);
     }
   }
+}
+async function execCommand(opts) {
+  const profile = getProfile(opts.profile);
+  enforceExecPolicy(profile, opts.command, opts.args, opts.projectPath);
   const envMap = {};
   for (const [k, v] of Object.entries(process.env)) {
     if (v !== void 0) envMap[k] = v;
@@ -2052,6 +2136,18 @@ async function execCommand(opts) {
       }
     }
   }
+  return spawnRedacted({
+    profile,
+    command: opts.command,
+    args: opts.args,
+    envMap,
+    secretsToRedact: [...secretsToRedact],
+    captureOutput: opts.captureOutput,
+    projectPath: opts.projectPath
+  });
+}
+function spawnRedacted(opts) {
+  const { profile, secretsToRedact, envMap } = opts;
   const maxRuntime = profile.maxRuntimeSeconds ?? getExecMaxRuntime(opts.projectPath);
   return new Promise((resolve, reject) => {
     const networkTools = /* @__PURE__ */ new Set([
@@ -2492,7 +2588,7 @@ function registerToolingCommands(program2) {
     }
   });
   program2.command("status").description("Launch the quantum status dashboard in your browser").option("--port <port>", "Port to serve on", "9876").option("--no-open", "Don't auto-open the browser").action(async (cmd) => {
-    const { startDashboardServer } = await import("./dashboard-PYYAED45.js");
+    const { startDashboardServer } = await import("./dashboard-A3GJQCJX.js");
     const { exec } = await import("child_process");
     const { platform } = await import("os");
     const port = Number(cmd.port);
@@ -3407,12 +3503,819 @@ ${SYMBOLS.lock} Approval Tokens
   });
 }
 
-// src/cli/commands/doctor.ts
-import { existsSync as existsSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync5, rmSync } from "fs";
-import { join as join3, delimiter } from "path";
+// src/core/run.ts
+import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
+import { join as join3, resolve as resolvePath } from "path";
+
+// src/core/refs.ts
+var REF_PREFIX = "qring://";
+var KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var REF_PATTERN = /^qring:\/\/(global|project|)\/([^/?#]+)(?:\?([^#]*))?$/;
+function isRef(value) {
+  return value.startsWith(REF_PREFIX);
+}
+function parseRef(raw) {
+  if (!isRef(raw)) {
+    throw new Error(`Not a qring:// reference: "${raw}"`);
+  }
+  const match = REF_PATTERN.exec(raw);
+  if (!match) {
+    const hostOnly = /^qring:\/\/([^/?#]+)\/?$/.exec(raw);
+    if (hostOnly && KEY_PATTERN.test(hostOnly[1]) && !["global", "project"].includes(hostOnly[1])) {
+      throw new Error(
+        `Invalid ref "${raw}": the key belongs in the path, not the host (URL hosts are lowercased by parsers). Use "qring:///${hostOnly[1]}" (auto scope) or "qring://project/${hostOnly[1]}".`
+      );
+    }
+    throw new Error(
+      `Invalid ref "${raw}": expected qring://<global|project|>/KEY[?env=<env>]`
+    );
+  }
+  const [, scopeRaw, key, query] = match;
+  if (!KEY_PATTERN.test(key)) {
+    throw new Error(
+      `Invalid ref "${raw}": "${key}" is not a valid secret key (expected [A-Za-z_][A-Za-z0-9_]*)`
+    );
+  }
+  let env;
+  if (query) {
+    for (const part of query.split("&")) {
+      if (!part) continue;
+      const eq = part.indexOf("=");
+      const name = eq === -1 ? part : part.slice(0, eq);
+      const value = eq === -1 ? "" : decodeURIComponent(part.slice(eq + 1));
+      if (name === "env") {
+        env = value;
+      } else {
+        throw new Error(`Invalid ref "${raw}": unknown query parameter "${name}"`);
+      }
+    }
+  }
+  return {
+    scope: scopeRaw === "" ? void 0 : scopeRaw,
+    key,
+    env,
+    raw
+  };
+}
+function resolveRef(ref, opts = {}) {
+  const scopes = ref.scope ? [ref.scope] : ["project", "global"];
+  for (const scope of scopes) {
+    const value = getSecret(ref.key, {
+      ...opts,
+      scope,
+      env: ref.env ?? opts.env
+    });
+    if (value !== null) return value;
+  }
+  return null;
+}
+function resolveRefsInMap(map, opts = {}) {
+  const resolved = {};
+  const secretValues = [];
+  const missing = [];
+  for (const [name, value] of Object.entries(map)) {
+    if (!isRef(value)) {
+      resolved[name] = value;
+      continue;
+    }
+    const ref = parseRef(value);
+    const secret = resolveRef(ref, opts);
+    if (secret === null) {
+      missing.push({ name, ref });
+      continue;
+    }
+    resolved[name] = secret;
+    secretValues.push(secret);
+  }
+  return { resolved, secretValues, missing };
+}
+
+// src/core/run.ts
+function buildRunPlan(opts) {
+  const projectPath = opts.projectPath ?? process.cwd();
+  const keyringOpts = {
+    projectPath,
+    env: opts.env,
+    source: opts.source ?? "cli",
+    silent: opts.silent
+  };
+  const envMap = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v !== void 0) envMap[k] = v;
+  }
+  const injected = [];
+  const missingRequired = [];
+  const missingOptional = [];
+  const secretsToRedact = /* @__PURE__ */ new Set();
+  if (opts.useManifest !== false) {
+    const config = readProjectConfig(projectPath);
+    for (const [key, entry] of Object.entries(config?.secrets ?? {})) {
+      const value = resolveRef(
+        { key, raw: `manifest:${key}` },
+        keyringOpts
+      );
+      if (value === null) {
+        if (entry.required !== false) missingRequired.push(key);
+        else if (opts.strict) missingRequired.push(key);
+        else missingOptional.push(key);
+        continue;
+      }
+      envMap[key] = value;
+      injected.push({ name: key, source: "manifest" });
+      if (value.length > 5) secretsToRedact.add(value);
+    }
+  }
+  const envFiles = opts.envFiles ?? (existsSync4(join3(projectPath, ".env")) ? [join3(projectPath, ".env")] : []);
+  for (const file of envFiles) {
+    const path = resolvePath(projectPath, file);
+    if (!existsSync4(path)) {
+      throw new Error(`Env file not found: ${path}`);
+    }
+    const parsed = Object.fromEntries(parseDotenv(readFileSync6(path, "utf8")));
+    const { resolved, secretValues, missing } = resolveRefsInMap(parsed, keyringOpts);
+    for (const [name, value] of Object.entries(resolved)) {
+      envMap[name] = value;
+      injected.push({
+        name,
+        source: isRef(parsed[name]) ? "env-file-ref" : "env-file"
+      });
+    }
+    for (const value of secretValues) {
+      if (value.length > 5) secretsToRedact.add(value);
+    }
+    for (const m of missing) missingRequired.push(m.name);
+  }
+  return {
+    envFiles: envFiles.map((f) => resolvePath(projectPath, f)),
+    injected,
+    missingRequired,
+    missingOptional,
+    envMap,
+    secretsToRedact: [...secretsToRedact]
+  };
+}
+async function runCommand(opts) {
+  const profile = getProfile(opts.profile);
+  enforceExecPolicy(profile, opts.command, opts.args, opts.projectPath);
+  const plan = buildRunPlan(opts);
+  if (plan.missingRequired.length > 0) {
+    throw new Error(
+      `Missing required secrets: ${plan.missingRequired.join(", ")}. Store them with \`qring set <KEY>\` or drop them from the manifest/.env refs.`
+    );
+  }
+  if (profile.stripEnvVars) {
+    for (const key of profile.stripEnvVars) {
+      delete plan.envMap[key];
+    }
+  }
+  const result = await spawnRedacted({
+    profile,
+    command: opts.command,
+    args: opts.args,
+    envMap: plan.envMap,
+    secretsToRedact: plan.secretsToRedact,
+    captureOutput: opts.captureOutput,
+    projectPath: opts.projectPath
+  });
+  return { ...result, plan };
+}
+
+// src/core/setup.ts
+import { existsSync as existsSync5, mkdirSync, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
 import { homedir } from "os";
+import { dirname, join as join4 } from "path";
+var EDITORS = ["cursor", "kiro", "claude"];
+var READ_ONLY_TOOLS = [
+  "list_secrets",
+  "has_secret",
+  "inspect_secret",
+  "detect_environment",
+  "get_project_context",
+  "list_providers",
+  "list_hooks",
+  "get_policy_summary",
+  "audit_log",
+  "verify_audit_chain",
+  "health_check",
+  "analyze_secrets"
+];
+var SERVER_NAME = "q-ring";
+function serverEntry(editor) {
+  switch (editor) {
+    case "cursor":
+      return { command: "qring-mcp", args: [], env: {} };
+    case "kiro":
+      return {
+        command: "qring-mcp",
+        args: [],
+        env: {},
+        disabled: false,
+        autoApprove: READ_ONLY_TOOLS
+      };
+    case "claude":
+      return { type: "stdio", command: "qring-mcp", args: [], env: {} };
+  }
+}
+function configPathFor(editor, global, projectPath) {
+  const home = homedir();
+  switch (editor) {
+    case "cursor":
+      return global ? join4(home, ".cursor", "mcp.json") : join4(projectPath, ".cursor", "mcp.json");
+    case "kiro":
+      return global ? join4(home, ".kiro", "settings", "mcp.json") : join4(projectPath, ".kiro", "settings", "mcp.json");
+    case "claude":
+      if (global) {
+        throw new Error(
+          "Claude Code user-scoped MCP servers are registered via the claude CLI, not a config file.\nRun: claude mcp add --scope user q-ring qring-mcp\nOr install the plugin: /plugin marketplace add I4cTime/q-ring && /plugin install qring@q-ring"
+        );
+      }
+      return join4(projectPath, ".mcp.json");
+  }
+}
+function setupEditor(opts) {
+  const projectPath = opts.projectPath ?? process.cwd();
+  const configPath = configPathFor(opts.editor, opts.global ?? false, projectPath);
+  const warnings = [];
+  let config = {};
+  if (existsSync5(configPath)) {
+    const raw = readFileSync7(configPath, "utf8");
+    try {
+      config = JSON.parse(raw);
+    } catch {
+      throw new Error(
+        `${configPath} exists but is not valid JSON \u2014 fix or remove it, then re-run.`
+      );
+    }
+  }
+  const servers = config.mcpServers ?? {};
+  const desired = serverEntry(opts.editor);
+  const existing = servers[SERVER_NAME];
+  let action;
+  if (existing === void 0) {
+    action = existsSync5(configPath) ? "updated" : "created";
+    servers[SERVER_NAME] = desired;
+  } else if (JSON.stringify(existing) === JSON.stringify(desired)) {
+    action = "unchanged";
+  } else if (opts.force) {
+    action = "updated";
+    servers[SERVER_NAME] = desired;
+  } else {
+    action = "unchanged";
+    warnings.push(
+      `A different "${SERVER_NAME}" entry already exists in ${configPath} \u2014 left as-is (use --force to replace it).`
+    );
+  }
+  config.mcpServers = servers;
+  if (action !== "unchanged" && !opts.dryRun) {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync5(configPath, JSON.stringify(config, null, 2) + "\n");
+  }
+  return {
+    editor: opts.editor,
+    configPath,
+    serverName: SERVER_NAME,
+    action,
+    dryRun: opts.dryRun ?? false,
+    warnings
+  };
+}
+
+// src/core/push.ts
+import { spawnSync } from "child_process";
+var PUSH_TARGETS = ["github", "vercel", "cloudflare"];
+var TARGETS = {
+  github: {
+    binary: "gh",
+    args: (key, opts) => [
+      ["secret", "set", key, ...opts.repo ? ["--repo", opts.repo] : []]
+    ],
+    installHint: "install the GitHub CLI: https://cli.github.com (then `gh auth login`)"
+  },
+  vercel: {
+    binary: "vercel",
+    // One invocation per environment — `vercel env add` takes a single target.
+    args: (key, opts) => (opts.vercelEnvs ?? ["production"]).map((env) => [
+      "env",
+      "add",
+      key,
+      env,
+      "--force"
+    ]),
+    installHint: "install the Vercel CLI: npm i -g vercel (then `vercel link` in the project)"
+  },
+  cloudflare: {
+    binary: "wrangler",
+    args: (key) => [["secret", "put", key]],
+    installHint: "install Wrangler: npm i -g wrangler (then `wrangler login`)"
+  }
+};
+function binaryAvailable(binary) {
+  const probe = spawnSync(binary, ["--version"], { stdio: "ignore", shell: false });
+  return !probe.error;
+}
+function resolvePushKeys(opts) {
+  if (opts.keys?.length) return opts.keys;
+  const config = readProjectConfig(opts.projectPath);
+  const manifestKeys = Object.keys(config?.secrets ?? {});
+  if (manifestKeys.length === 0) {
+    throw new Error(
+      "Nothing to push: no --keys given and no secrets manifest in .q-ring.json. Declare the project's secrets there or pass --keys KEY1,KEY2."
+    );
+  }
+  return manifestKeys;
+}
+function pushSecrets(opts) {
+  const target = TARGETS[opts.target];
+  const keys = resolvePushKeys(opts);
+  if (!opts.dryRun && !binaryAvailable(target.binary)) {
+    throw new Error(`"${target.binary}" CLI not found \u2014 ${target.installHint}`);
+  }
+  const result = { target: opts.target, pushed: [], failed: [], missing: [] };
+  for (const key of keys) {
+    const value = resolveRef(
+      { key, raw: `push:${key}` },
+      {
+        projectPath: opts.projectPath,
+        env: opts.env,
+        source: opts.source ?? "cli",
+        silent: opts.silent
+      }
+    );
+    if (value === null) {
+      result.missing.push(key);
+      continue;
+    }
+    if (opts.dryRun) {
+      result.pushed.push(key);
+      continue;
+    }
+    let failedInvocation = null;
+    for (const args of target.args(key, opts)) {
+      const child = spawnSync(target.binary, args, {
+        input: value,
+        cwd: opts.projectPath,
+        encoding: "utf8",
+        shell: false
+      });
+      if (child.status !== 0) {
+        failedInvocation = child.stderr?.trim() || child.error?.message || `exit ${child.status}`;
+        break;
+      }
+    }
+    if (failedInvocation) {
+      result.failed.push({ key, error: failedInvocation });
+      continue;
+    }
+    result.pushed.push(key);
+    if (!opts.silent) {
+      logAudit({
+        action: "push",
+        key,
+        env: opts.env,
+        source: opts.source ?? "cli",
+        detail: `pushed to ${opts.target}${opts.repo ? ` (${opts.repo})` : ""}`
+      });
+    }
+  }
+  return result;
+}
+
+// src/cli/commands/bridges.ts
+function registerBridgeCommands(program2) {
+  program2.command("run <command...>").description(
+    "Run a command with only declared secrets injected \u2014 .q-ring.json manifest keys plus qring:// refs from .env (output auto-redacted)"
+  ).option("--project-path <path>", "Explicit project path").option("-e, --env <env>", "Environment context").option("--env-file <files...>", "Env file(s) to load (default: ./.env when present)").option("--no-manifest", "Skip .q-ring.json manifest keys").option("--profile <name>", "Exec profile: unrestricted, restricted, ci").option("--strict", "Missing optional manifest keys are fatal too").option("--dry-run", "Show what would be injected without running").action(async (commandArgs, cmd) => {
+    const opts = {
+      command: commandArgs[0],
+      args: commandArgs.slice(1),
+      projectPath: cmd.projectPath ?? process.cwd(),
+      env: cmd.env,
+      envFiles: cmd.envFile,
+      useManifest: cmd.manifest !== false,
+      profile: cmd.profile,
+      strict: cmd.strict === true,
+      source: "cli"
+    };
+    try {
+      if (cmd.dryRun) {
+        const plan2 = buildRunPlan({ ...opts, silent: true });
+        console.log(`
+${SYMBOLS.zap} ${c.bold("qring run")} ${c.dim("(dry run)")}`);
+        if (plan2.envFiles.length > 0) {
+          console.log(`  Env files: ${plan2.envFiles.map((f) => c.cyan(f)).join(", ")}`);
+        }
+        for (const v of plan2.injected) {
+          console.log(`  ${c.green(SYMBOLS.check)} ${v.name} ${c.dim(`(${v.source})`)}`);
+        }
+        for (const name of plan2.missingOptional) {
+          console.log(`  ${c.yellow("?")} ${name} ${c.dim("(optional, missing)")}`);
+        }
+        for (const name of plan2.missingRequired) {
+          console.log(`  ${c.red(SYMBOLS.cross)} ${name} ${c.dim("(required, MISSING)")}`);
+        }
+        process.exit(plan2.missingRequired.length > 0 ? 1 : 0);
+      }
+      const { code, plan } = await runCommand(opts);
+      if (plan.missingOptional.length > 0) {
+        console.error(
+          c.yellow(
+            `${SYMBOLS.warning} Optional secrets not found: ${plan.missingOptional.join(", ")}`
+          )
+        );
+      }
+      process.exit(code);
+    } catch (err) {
+      console.error(
+        c.red(
+          `${SYMBOLS.cross} Run failed: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
+      process.exit(1);
+    }
+  });
+  program2.command("push <target>").description(
+    `Push manifest secrets to a deployment platform via its own CLI (${PUSH_TARGETS.join(", ")}) \u2014 values travel over stdin, never argv`
+  ).option("-k, --keys <keys>", "Comma-separated keys (default: .q-ring.json manifest)").option("--project-path <path>", "Explicit project path").option("-e, --env <env>", "Environment context for superposition collapse").option("--repo <owner/name>", "GitHub repository (github target)").option(
+    "--vercel-env <envs>",
+    "Comma-separated Vercel environments (default: production)"
+  ).option("--dry-run", "Show what would be pushed without pushing").option("--json", "Output as JSON").action((targetArg, cmd) => {
+    if (!PUSH_TARGETS.includes(targetArg)) {
+      console.error(
+        c.red(`${SYMBOLS.cross} Unknown target "${targetArg}" \u2014 expected one of: ${PUSH_TARGETS.join(", ")}`)
+      );
+      process.exit(1);
+    }
+    try {
+      const result = pushSecrets({
+        target: targetArg,
+        keys: cmd.keys?.split(",").map((k) => k.trim()),
+        projectPath: cmd.projectPath ?? process.cwd(),
+        env: cmd.env,
+        repo: cmd.repo,
+        vercelEnvs: cmd.vercelEnv?.split(",").map((e) => e.trim()),
+        dryRun: cmd.dryRun === true,
+        source: "cli"
+      });
+      if (wantsJsonOutput(program2, cmd)) {
+        console.log(JSON.stringify(result, null, 2));
+        process.exit(result.failed.length > 0 ? 1 : 0);
+      }
+      const prefix = cmd.dryRun ? c.dim("[dry-run] ") : "";
+      console.log(`
+${SYMBOLS.link} ${prefix}${c.bold(`qring push ${targetArg}`)}`);
+      for (const key of result.pushed) {
+        console.log(`  ${c.green(SYMBOLS.check)} ${key}`);
+      }
+      for (const key of result.missing) {
+        console.log(`  ${c.yellow("?")} ${key} ${c.dim("(not in keyring \u2014 skipped)")}`);
+      }
+      for (const { key, error } of result.failed) {
+        console.log(`  ${c.red(SYMBOLS.cross)} ${key} ${c.dim(`\u2014 ${error}`)}`);
+      }
+      console.log(
+        c.dim(
+          `  ${result.pushed.length} pushed${cmd.dryRun ? " (dry run)" : ""}, ${result.missing.length} missing, ${result.failed.length} failed`
+        )
+      );
+      process.exit(result.failed.length > 0 ? 1 : 0);
+    } catch (err) {
+      console.error(
+        c.red(
+          `${SYMBOLS.cross} Push failed: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
+      process.exit(1);
+    }
+  });
+  program2.command("setup <editor>").description(
+    `Wire the q-ring MCP server into an editor's MCP config (${EDITORS.join(", ")})`
+  ).option("-g, --global", "Write the per-user config instead of the project one").option("--project-path <path>", "Explicit project path").option("--force", "Replace an existing q-ring entry that differs").option("--dry-run", "Show what would change without writing").option("--json", "Output as JSON").action((editor, cmd) => {
+    if (!EDITORS.includes(editor)) {
+      console.error(
+        c.red(`${SYMBOLS.cross} Unknown editor "${editor}" \u2014 expected one of: ${EDITORS.join(", ")}`)
+      );
+      process.exit(1);
+    }
+    try {
+      const result = setupEditor({
+        editor,
+        global: cmd.global === true,
+        projectPath: cmd.projectPath ?? process.cwd(),
+        force: cmd.force === true,
+        dryRun: cmd.dryRun === true
+      });
+      if (wantsJsonOutput(program2, cmd)) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      const verb = result.action === "created" ? "Created" : result.action === "updated" ? "Updated" : "Already configured";
+      const prefix = result.dryRun ? c.dim("[dry-run] ") : "";
+      console.log(
+        `
+${SYMBOLS.check} ${prefix}${c.bold(verb)}: ${c.cyan(result.configPath)} ${c.dim(`(server "${result.serverName}")`)}`
+      );
+      for (const warning of result.warnings) {
+        console.log(`  ${c.yellow("!")} ${warning}`);
+      }
+      if (result.action !== "unchanged") {
+        console.log(c.dim(`  Restart ${editor} to pick up the MCP server. Verify with: qring doctor`));
+      }
+    } catch (err) {
+      console.error(
+        c.red(
+          `${SYMBOLS.cross} Setup failed: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
+      process.exit(1);
+    }
+  });
+}
+
+// src/core/canary.ts
+var ALPHA_UPPER_NUM = () => generateSecret({ format: "alphanumeric", length: 16 }).toUpperCase();
+var CANARY_FORMATS = {
+  aws: {
+    name: "aws",
+    description: "AWS access key id (AKIA\u2026)",
+    generate: () => `AKIA${ALPHA_UPPER_NUM()}`
+  },
+  github: {
+    name: "github",
+    description: "GitHub personal access token (ghp_\u2026)",
+    generate: () => generateSecret({ format: "api-key", prefix: "ghp_", length: 36 })
+  },
+  openai: {
+    name: "openai",
+    description: "OpenAI API key (sk-\u2026)",
+    generate: () => generateSecret({ format: "api-key", prefix: "sk-", length: 48 })
+  },
+  anthropic: {
+    name: "anthropic",
+    description: "Anthropic API key (sk-ant-\u2026)",
+    generate: () => generateSecret({ format: "api-key", prefix: "sk-ant-api03-", length: 80 })
+  },
+  stripe: {
+    name: "stripe",
+    description: "Stripe live secret key (sk_live_\u2026)",
+    generate: () => generateSecret({ format: "api-key", prefix: "sk_live_", length: 24 })
+  },
+  generic: {
+    name: "generic",
+    description: "Generic high-entropy API key",
+    generate: () => generateSecret({ format: "api-key", prefix: "qk_", length: 40 })
+  }
+};
+var DEFAULT_CANARY_FORMAT = "generic";
+function plantCanary(key, opts = {}) {
+  const formatName = opts.format ?? DEFAULT_CANARY_FORMAT;
+  const format = CANARY_FORMATS[formatName];
+  if (!format) {
+    throw new Error(
+      `Unknown canary format "${formatName}". Available: ${Object.keys(CANARY_FORMATS).join(", ")}`
+    );
+  }
+  const value = opts.value ?? format.generate();
+  const scope = opts.scope ?? "global";
+  setSecret(key, value, {
+    ...opts,
+    scope,
+    canary: true,
+    canaryFormat: formatName,
+    description: opts.value ? "Canary honeytoken (custom value)" : `Canary honeytoken (${format.description})`
+  });
+  return { key, value, format: formatName, scope };
+}
+function listCanaries(opts = {}) {
+  const out = [];
+  for (const entry of listSecrets({ ...opts, silent: true })) {
+    const meta = entry.envelope?.meta;
+    if (!meta?.canary) continue;
+    out.push({
+      key: entry.key,
+      scope: entry.scope,
+      format: meta.canaryFormat,
+      plantedAt: meta.createdAt,
+      tripCount: meta.accessCount,
+      lastTrippedAt: meta.lastAccessedAt
+    });
+  }
+  return out;
+}
+
+// src/cli/commands/canary.ts
+function registerCanaryCommands(program2) {
+  const canary = program2.command("canary").description("Honeytokens \u2014 fake credentials that raise the alarm on read");
+  canary.command("plant <key>").description("Plant a fake credential; any read fires a loud alert").option(
+    "-f, --format <format>",
+    `Token shape to imitate (${Object.keys(CANARY_FORMATS).join(", ")})`,
+    DEFAULT_CANARY_FORMAT
+  ).option("--value <value>", "Plant this exact value instead of generating one").option("--force", "Overwrite an existing non-canary secret at this key").option("-g, --global", "Global scope (default)").option("-p, --project", "Project scope").option("--team <id>", "Team scope").option("--org <id>", "Org scope").option("--project-path <path>", "Project path (defaults to cwd)").action((key, cmd) => {
+    const opts = buildOpts(cmd);
+    const existing = getEnvelope(key, opts);
+    if (existing && !existing.envelope.meta.canary && !cmd.force) {
+      console.error(
+        c.red(
+          `${SYMBOLS.cross} "${key}" already holds a real secret in ${existing.scope} scope. Use --force to replace it with a canary.`
+        )
+      );
+      process.exit(1);
+    }
+    const result = plantCanary(key, { ...opts, format: cmd.format, value: cmd.value });
+    console.log(
+      `${SYMBOLS.sparkle} ${c.yellow("canary planted")} ${c.bold(result.key)} ${c.dim(`(${result.format}, ${result.scope} scope)`)}`
+    );
+    console.log(c.dim(`  value: ${result.value}`));
+    console.log(
+      c.dim(
+        "  Reads return this fake value and fire a desktop alert + a 'canary' audit event."
+      )
+    );
+    console.log(
+      c.dim("  Watch trips with: qring canary list \xB7 qring audit --action canary")
+    );
+  });
+  canary.command("list").alias("ls").description("List planted canaries and their trip counts").option("--json", "Output as JSON").option("-g, --global", "Global scope only").option("-p, --project", "Project scope only").option("--team <id>", "Team scope").option("--org <id>", "Org scope").option("--project-path <path>", "Project path (defaults to cwd)").action((cmd) => {
+    const canaries = listCanaries(buildOpts(cmd));
+    if (emitJson(program2, cmd, { canaries })) return;
+    if (canaries.length === 0) {
+      console.log(c.dim("No canaries planted. Plant one: qring canary plant AWS_SECRET_ACCESS_KEY --format aws"));
+      return;
+    }
+    console.log(c.bold(`
+  ${SYMBOLS.eye} Canaries (${canaries.length})
+`));
+    for (const entry of canaries) {
+      const parts = [c.bold(entry.key)];
+      parts.push(c.dim(`${entry.format ?? "generic"} \xB7 ${entry.scope}`));
+      if (entry.tripCount > 0) {
+        parts.push(c.red(`trips: ${entry.tripCount}`));
+        if (entry.lastTrippedAt) {
+          parts.push(c.red(`last: ${entry.lastTrippedAt}`));
+        }
+      } else {
+        parts.push(c.green("no trips"));
+      }
+      console.log(`  ${SYMBOLS.eye} ${parts.join("  ")}`);
+    }
+    console.log();
+  });
+}
+
+// src/core/wrap.ts
+import { randomUUID } from "crypto";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+function createAirlockServer(downstream, session) {
+  const downstreamInfo = downstream.getServerVersion();
+  const name = downstreamInfo ? `${downstreamInfo.name} (q-ring airlock)` : "q-ring-airlock";
+  const proxy = new Server(
+    { name, version: PACKAGE_VERSION },
+    { capabilities: { tools: {} } }
+  );
+  proxy.oninitialized = () => {
+    const info = proxy.getClientVersion();
+    if (info) setAuditAgentLabel(`${info.name}@${info.version}`);
+  };
+  proxy.setRequestHandler(ListToolsRequestSchema, async (request) => {
+    return downstream.listTools(request.params);
+  });
+  proxy.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    const toolName = request.params.name;
+    logAudit({
+      action: "wrap",
+      source: "mcp",
+      detail: `tool call "${toolName}" \u2192 ${session.label}`,
+      correlationId: session.correlationId
+    });
+    try {
+      return await downstream.callTool(request.params, void 0, {
+        signal: extra.signal
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logAudit({
+        action: "wrap",
+        source: "mcp",
+        detail: `tool call "${toolName}" failed: ${message}`,
+        correlationId: session.correlationId
+      });
+      return {
+        content: [
+          { type: "text", text: `airlock: downstream error: ${message}` }
+        ],
+        isError: true
+      };
+    }
+  });
+  return proxy;
+}
+async function connectDownstream(opts) {
+  const client = new Client({
+    name: "q-ring-airlock",
+    version: PACKAGE_VERSION
+  });
+  const env = opts.inheritEnv ? Object.fromEntries(
+    Object.entries(process.env).filter(([, v]) => v !== void 0)
+  ) : void 0;
+  const transport = new StdioClientTransport({
+    command: opts.command,
+    args: opts.args ?? [],
+    env,
+    stderr: "inherit"
+  });
+  await client.connect(transport);
+  return client;
+}
+async function runWrap(opts) {
+  const label = opts.label ?? [opts.command, ...opts.args ?? []].join(" ");
+  const session = { label, correlationId: randomUUID() };
+  const downstream = await connectDownstream(opts);
+  const downstreamInfo = downstream.getServerVersion();
+  logAudit({
+    action: "wrap",
+    source: "cli",
+    detail: `airlock session started: ${label}${opts.inheritEnv ? " (env inherited)" : " (env stripped)"}`,
+    correlationId: session.correlationId
+  });
+  console.error(
+    `q-ring airlock: wrapping ${downstreamInfo?.name ?? label} \u2014 env ${opts.inheritEnv ? "inherited" : "stripped"}, tool calls audited (session ${session.correlationId.slice(0, 8)})`
+  );
+  const proxy = createAirlockServer(downstream, session);
+  const transport = new StdioServerTransport();
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (code, reason) => {
+      if (settled) return;
+      settled = true;
+      logAudit({
+        action: "wrap",
+        source: "cli",
+        detail: `airlock session ended: ${reason}`,
+        correlationId: session.correlationId
+      });
+      void proxy.close().catch(() => {
+      });
+      void downstream.close().catch(() => {
+      });
+      resolve(code);
+    };
+    downstream.onclose = () => finish(1, "wrapped server exited");
+    transport.onclose = () => finish(0, "host disconnected");
+    transport.onerror = (err) => finish(1, `transport error: ${err.message}`);
+    process.stdin.on("end", () => finish(0, "host disconnected"));
+    process.stdout.on("error", (err) => {
+      if (err.code === "EPIPE") finish(0, "host disconnected");
+      else finish(1, `stdout error: ${err.message}`);
+    });
+    proxy.connect(transport).catch((err) => {
+      console.error(
+        `q-ring airlock: failed to start: ${err instanceof Error ? err.message : String(err)}`
+      );
+      finish(1, "startup failure");
+    });
+  });
+}
+
+// src/cli/commands/mcp.ts
+function registerMcpCommands(program2) {
+  const mcp = program2.command("mcp").description("MCP airlock \u2014 run third-party MCP servers behind q-ring");
+  mcp.command("wrap <command...>").description(
+    "Proxy an MCP server through the airlock: spawned with a stripped env, every tool call audited. Use -- before the server command: qring mcp wrap -- npx some-server"
+  ).option(
+    "--inherit-env",
+    "Pass the full parent environment to the wrapped server (default: minimal safe env)"
+  ).option("--label <label>", "Session label for audit events (default: the command line)").action(async (commandArgs, cmd) => {
+    try {
+      const code = await runWrap({
+        command: commandArgs[0],
+        args: commandArgs.slice(1),
+        inheritEnv: cmd.inheritEnv === true,
+        label: cmd.label
+      });
+      process.exit(code);
+    } catch (err) {
+      console.error(
+        c.red(
+          `${SYMBOLS.cross} Airlock failed: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/commands/doctor.ts
+import { existsSync as existsSync6, readFileSync as readFileSync8, writeFileSync as writeFileSync6, rmSync } from "fs";
+import { join as join5, delimiter } from "path";
+import { homedir as homedir2 } from "os";
 function auditDir() {
-  return process.env.QRING_AUDIT_DIR ?? join3(homedir(), ".config", "q-ring");
+  return process.env.QRING_AUDIT_DIR ?? join5(homedir2(), ".config", "q-ring");
 }
 function checkNode() {
   const major = Number(process.versions.node.split(".")[0]);
@@ -3452,8 +4355,8 @@ async function checkKeyringBackend() {
 function checkAuditLog() {
   const dir = auditDir();
   try {
-    const probeFile = join3(dir, ".doctor-probe");
-    writeFileSync5(probeFile, "ok");
+    const probeFile = join5(dir, ".doctor-probe");
+    writeFileSync6(probeFile, "ok");
     rmSync(probeFile);
   } catch (err) {
     return {
@@ -3480,8 +4383,8 @@ function checkAuditLog() {
   };
 }
 function checkManifest(projectPath) {
-  const manifestPath = join3(projectPath, ".q-ring.json");
-  if (!existsSync4(manifestPath)) {
+  const manifestPath = join5(projectPath, ".q-ring.json");
+  if (!existsSync6(manifestPath)) {
     return {
       name: "project manifest",
       status: "warn",
@@ -3489,7 +4392,7 @@ function checkManifest(projectPath) {
     };
   }
   try {
-    const config = JSON.parse(readFileSync6(manifestPath, "utf8"));
+    const config = JSON.parse(readFileSync8(manifestPath, "utf8"));
     const declared = Object.keys(config.secrets ?? {}).length;
     const hasPolicy = !!config.policy;
     return {
@@ -3538,11 +4441,11 @@ function checkMcpBinary() {
   for (const dir of (process.env.PATH ?? "").split(delimiter)) {
     if (!dir) continue;
     for (const ext of exts) {
-      if (existsSync4(join3(dir, `qring-mcp${ext}`))) {
+      if (existsSync6(join5(dir, `qring-mcp${ext}`))) {
         return {
           name: "qring-mcp binary",
           status: "ok",
-          detail: `found at ${join3(dir, `qring-mcp${ext}`)}`
+          detail: `found at ${join5(dir, `qring-mcp${ext}`)}`
         };
       }
     }
@@ -3749,6 +4652,11 @@ var COMMAND_GROUPS = [
     symbol: SYMBOLS.zap,
     commands: ["exec", "scan", "lint", "status", "doctor", "completion"]
   },
+  {
+    name: "Bridges",
+    symbol: SYMBOLS.link,
+    commands: ["run", "setup", "push"]
+  },
   {
     name: "Audit & Health",
     symbol: SYMBOLS.eye,
@@ -3772,7 +4680,7 @@ var COMMAND_GROUPS = [
   {
     name: "Security & Governance",
     symbol: SYMBOLS.lock,
-    commands: ["approve", "approvals", "policy"]
+    commands: ["approve", "approvals", "policy", "canary", "mcp"]
   }
 ];
 var GroupedHelp = class extends Help {
@@ -3889,6 +4797,9 @@ function createProgram() {
   registerHookCommands(program2);
   registerAgentCommands(program2);
   registerSecurityCommands(program2);
+  registerBridgeCommands(program2);
+  registerCanaryCommands(program2);
+  registerMcpCommands(program2);
   registerDoctorCommand(program2);
   registerCompletionCommand(program2);
   return program2;