fix: Stop embedding Portkey API key in committed config and tighten file perms

The setup/mcp wizards offered "share with the team" destinations they
labeled commit-safe (.mcp.json "ok to commit", .claude/settings.json
"committed to git") but wrote the live workspace API key into them in
plaintext. Every fs.writeFileSync also omitted a mode, so secret-bearing
home-dir files (~/.claude/settings.json, shell rc, ~/.codex/config.toml)
landed world-readable at 0644.

For git-committed scopes the config now references ${PORTKEY_API_KEY}
(expanded from the environment at read time, matching how the Codex
paths already worked) instead of the literal key; the real secret is
persisted to the user's shell rc. All secret-bearing writes now use a
writeFileSecure helper that creates files at 0600 and chmods existing
ones. UI hints and post-write banners updated to reflect that committed
files no longer contain a secret, and the README documents the
PORTKEY_API_KEY env-var workflow.

Adds regression tests for the env-var reference and 0600 permissions.

Author: kiran-4444

README.md

@@ -39,6 +39,14 @@ npx portkey mcp add
 
 Config goes mainly into your shell profile and/or `.claude/` (the wizard explains each choice). Open a **new terminal** (or `source` your profile) after setup, then run `claude` as usual.
 
+> **Shared / committed config (`PORTKEY_API_KEY`).** When you choose a git-tracked destination — `mcp add` → **Repo file (.mcp.json)** or `setup` → **Project (shared)** (`.claude/settings.json`) — the CLI **never** writes your key into the committed file. It writes the reference `"${PORTKEY_API_KEY}"` (Claude Code expands it from the environment at read time) and stores the real key in your shell profile (owner-only, `0600`). Each teammate just exports their own `PORTKEY_API_KEY`:
+>
+> ```bash
+> export PORTKEY_API_KEY="pk-..."   # add to ~/.zshrc, ~/.bashrc, or CI secrets
+> ```
+>
+> All files the CLI writes that hold a secret (shell profile, `~/.claude/settings.json`, `~/.codex/config.toml`) are created with `0600` permissions.
+
 **Later, from your project folder:**
 
 ```bash

src/api.js

@@ -164,17 +164,23 @@ export async function fetchModels(portkeyKey, providerSlug, gateway) {
  *   services.
  *
  * Never put the key in `Authorization` or use `Authorization: x-portkey-api-key: …`.
+ *
+ * `opts.keyRef` — when set (e.g. `"${PORTKEY_API_KEY}"`), the header carries this
+ * environment-variable reference instead of the literal key. Use it for any
+ * destination that is committed to git so the secret never lands in a tracked file
+ * (Claude Code expands `${VAR}` in `.mcp.json` headers at read time).
  */
-export function buildClaudeMcpHttpConfig(server, portkeyKey) {
+export function buildClaudeMcpHttpConfig(server, portkeyKey, { keyRef = null } = {}) {
   const cfg = {
     type: "http",
     url:  server.url,
   };
-  if (!portkeyKey) return cfg;
+  const headerValue = keyRef || portkeyKey;
+  if (!headerValue) return cfg;
   return {
     ...cfg,
     headers: {
-      "x-portkey-api-key": portkeyKey,
+      "x-portkey-api-key": headerValue,
     },
   };
 }

src/commands/claude-code/mcp.js

@@ -3,14 +3,19 @@ import path from "node:path";
 import os from "node:os";
 import * as p from "@clack/prompts";
 import {
+  VERSION,
   PORTKEY_DASHBOARD,
+  PORTKEY_KEY_ENV,
+  PORTKEY_KEY_ENV_REF,
   c,
   ok,
   err,
   info,
   warn,
   mask,
   findProjectRoot,
+  detectShellRc,
+  writeShellRc,
   getMcpFilePath,
   settingsSetMcp,
   settingsRemoveMcp,
@@ -46,7 +51,7 @@ function scopeToFilePath(scope, projectRoot) {
 
 function scopeLabel(scope, projectRoot) {
   if (scope === "project") {
-    return `project  ${c.dim}(.mcp.json in repo — team can commit)${c.reset}`;
+    return `project  ${c.dim}(.mcp.json in repo — uses ${PORTKEY_KEY_ENV_REF}, safe to commit)${c.reset}`;
   }
   if (scope === "local") {
     return `this project only  ${c.dim}(~/.claude.json, not under .claude/settings*)${c.reset}`;
@@ -174,7 +179,7 @@ export async function doMcpAdd(args) {
         {
           value: "project",
           label: "Repo file (.mcp.json)",
-          hint:  "in project root — ok to commit for the team",
+          hint:  `in project root — committed; key read from ${PORTKEY_KEY_ENV} env`,
         },
         {
           value: "user",
@@ -290,11 +295,15 @@ export async function doMcpAdd(args) {
   }
 
   // ── Claude write ────────────────────────────────────────────────────────────
+  // "project" scope writes a git-committed .mcp.json, so reference the key via
+  // ${PORTKEY_API_KEY} instead of embedding the secret in a tracked file.
+  const committed = mcpScope === "project";
+  const keyRef = committed ? PORTKEY_KEY_ENV_REF : null;
   const mcpEntries = {};
   for (const slug of selected) {
     const srv = servers.find((x) => x.slug === slug);
     if (!srv) continue;
-    mcpEntries[`portkey-${slug}`] = buildClaudeMcpHttpConfig(srv, portkeyKey);
+    mcpEntries[`portkey-${slug}`] = buildClaudeMcpHttpConfig(srv, portkeyKey, { keyRef });
   }
 
   if (args.dryRun) {
@@ -308,6 +317,34 @@ export async function doMcpAdd(args) {
     projectPath: mcpScope === "local" ? (projectRoot || process.cwd()) : null,
   });
 
+  // The committed file only resolves if PORTKEY_API_KEY is in the environment.
+  // Persist the secret to the user's shell rc (owner-only) so it works out of the box.
+  if (committed && !process.env[PORTKEY_KEY_ENV]) {
+    const shellRc = detectShellRc();
+    const isFish  = shellRc.endsWith("config.fish");
+    const isPwsh  = shellRc.endsWith(".ps1");
+    const isNu    = shellRc.endsWith(".nu");
+    let exportLine;
+    if (isFish)      exportLine = `set -gx ${PORTKEY_KEY_ENV} "${portkeyKey}"`;
+    else if (isPwsh) exportLine = `$env:${PORTKEY_KEY_ENV} = "${portkeyKey}"`;
+    else if (isNu)   exportLine = `$env.${PORTKEY_KEY_ENV} = "${portkeyKey}"`;
+    else             exportLine = `export ${PORTKEY_KEY_ENV}="${portkeyKey}"`;
+    writeShellRc(shellRc, [
+      `# ── Portkey + Claude Code (v${VERSION}) ──`,
+      exportLine,
+      "# ── End Portkey + Claude Code ──",
+    ].join("\n"));
+    warn(
+      `.mcp.json references ${c.bold}${PORTKEY_KEY_ENV_REF}${c.reset} (no secret committed). ` +
+        `Your key was saved to ${c.bold}${shellRc}${c.reset} — run ${c.bold}source ${shellRc}${c.reset} or open a new terminal.`
+    );
+  } else if (committed) {
+    info(
+      `.mcp.json references ${c.bold}${PORTKEY_KEY_ENV_REF}${c.reset} — no secret committed. ` +
+        `Teammates set ${c.bold}${PORTKEY_KEY_ENV}${c.reset} in their environment.`
+    );
+  }
+
   console.log();
   for (const [name, cfg] of Object.entries(mcpEntries)) {
     ok(`${name}  ${c.dim}${cfg.url}${c.reset}`);

src/commands/claude-code/setup.js

@@ -8,6 +8,8 @@ import {
   VERSION,
   PORTKEY_GATEWAY,
   PORTKEY_DASHBOARD,
+  PORTKEY_KEY_ENV,
+  PORTKEY_KEY_ENV_REF,
   c,
   ok,
   err,
@@ -136,7 +138,7 @@ export async function doSetup(args) {
     if (projectRoot) {
       locationOptions.push(
         { value: "project-local",  label: "Project (private)",   hint: ".claude/settings.local.json  (gitignored)" },
-        { value: "project-shared", label: "Project (shared)",    hint: ".claude/settings.json  (committed to git)" },
+        { value: "project-shared", label: "Project (shared)",    hint: ".claude/settings.json  (committed; key read from PORTKEY_API_KEY env)" },
       );
     }
     const picked = await p.select({
@@ -884,10 +886,13 @@ export async function doSetup(args) {
       ok(`Gateway config written to ${targetFile}`);
 
     } else {
-      // Write to settings.json
+      // Write to settings.json. "project-shared" is committed to git, so reference
+      // the key via ${PORTKEY_API_KEY} (Claude expands it from env at read time)
+      // instead of embedding the secret in a tracked file.
+      const committed = location === "project-shared";
       const envPairs = {
         ANTHROPIC_BASE_URL:       gateway,
-        ANTHROPIC_AUTH_TOKEN:     portkeyKey,
+        ANTHROPIC_AUTH_TOKEN:     committed ? PORTKEY_KEY_ENV_REF : portkeyKey,
         ANTHROPIC_CUSTOM_HEADERS: extraHeaders,
       };
       if (setModelMappings) {
@@ -899,23 +904,33 @@ export async function doSetup(args) {
       if (model) settingsSetKey(targetFile, "model", model);
       ok(`Gateway config written to ${targetFile}`);
 
-      // Also write auth token to shell RC so Claude Code can start
+      // Keep the real secret in the user's shell rc (owner-only), never in the
+      // committed file. For a committed config the env var must be PORTKEY_API_KEY
+      // so the ${PORTKEY_API_KEY} reference resolves; otherwise export the token directly.
+      const shellVar = committed ? PORTKEY_KEY_ENV : "ANTHROPIC_AUTH_TOKEN";
       const shellRc = detectShellRc();
       const isFish  = shellRc.endsWith("config.fish");
       const isPwsh  = shellRc.endsWith(".ps1");
       const isNu    = shellRc.endsWith(".nu");
       let exportLine;
-      if (isFish)      exportLine = `set -gx ANTHROPIC_AUTH_TOKEN "${portkeyKey}"`;
-      else if (isPwsh) exportLine = `$env:ANTHROPIC_AUTH_TOKEN = "${portkeyKey}"`;
-      else if (isNu)   exportLine = `$env.ANTHROPIC_AUTH_TOKEN = "${portkeyKey}"`;
-      else             exportLine = `export ANTHROPIC_AUTH_TOKEN="${portkeyKey}"`;
+      if (isFish)      exportLine = `set -gx ${shellVar} "${portkeyKey}"`;
+      else if (isPwsh) exportLine = `$env:${shellVar} = "${portkeyKey}"`;
+      else if (isNu)   exportLine = `$env.${shellVar} = "${portkeyKey}"`;
+      else             exportLine = `export ${shellVar}="${portkeyKey}"`;
 
       writeShellRc(shellRc, [
         `# ── Portkey + Claude Code (v${VERSION}) ──`,
         exportLine,
         "# ── End Portkey + Claude Code ──",
       ].join("\n"));
-      ok(`Auth token also written to ${shellRc}`);
+      if (committed) {
+        warn(
+          `${targetFile} is committed to git and references ${c.bold}${PORTKEY_KEY_ENV_REF}${c.reset} — no secret written to it. ` +
+            `Your key was saved to ${c.bold}${shellRc}${c.reset}; teammates set ${c.bold}${PORTKEY_KEY_ENV}${c.reset} themselves.`
+        );
+      } else {
+        ok(`Auth token also written to ${shellRc}`);
+      }
     }
 
     // Reload reminder (once, at the end)
@@ -1140,11 +1155,14 @@ async function runMcpSelection(
     mcpScope === "project" ? "project-shared" : "global",
     projectRoot
   );
+  // "project" scope writes a git-committed .mcp.json — reference the key via
+  // ${PORTKEY_API_KEY} rather than embedding the secret in a tracked file.
+  const mcpKeyRef = mcpScope === "project" ? PORTKEY_KEY_ENV_REF : null;
   const mcpEntries = {};
   for (const slug of selected) {
     const srv = servers.find((sv) => sv.slug === slug);
     if (!srv) continue;
-    mcpEntries[`portkey-${slug}`] = buildClaudeMcpHttpConfig(srv, portkeyKey);
+    mcpEntries[`portkey-${slug}`] = buildClaudeMcpHttpConfig(srv, portkeyKey, { keyRef: mcpKeyRef });
   }
 
   settingsSetMcp(mcpFile, mcpEntries, {
@@ -1161,7 +1179,7 @@ async function runMcpSelection(
   }
 
   const mcpScopeLabel =
-    mcpScope === "project" ? `repo .mcp.json  ${c.dim}(team can commit)${c.reset}` :
+    mcpScope === "project" ? `repo .mcp.json  ${c.dim}(uses ${PORTKEY_KEY_ENV_REF}, safe to commit)${c.reset}` :
     mcpScope === "local"   ? `this project only  ${c.dim}(~/.claude.json)${c.reset}` :
                              `all projects  ${c.dim}(~/.claude.json)${c.reset}`;
   ok(`${selected.length} MCP server${selected.length !== 1 ? "s" : ""} added  [${mcpScopeLabel}]`);

src/utils.js

@@ -12,6 +12,14 @@ export const VERSION = pkg.version;
 export const PORTKEY_GATEWAY = "https://api.portkey.ai";
 export const PORTKEY_DASHBOARD = "https://app.portkey.ai";
 
+/**
+ * Placeholder written into team-shared / git-committed config instead of the live key.
+ * Claude Code expands `${VAR}` in `.mcp.json` headers and `settings.json` env values,
+ * so the secret stays in the environment (e.g. the user's shell rc) and never lands in git.
+ */
+export const PORTKEY_KEY_ENV = "PORTKEY_API_KEY";
+export const PORTKEY_KEY_ENV_REF = "${" + PORTKEY_KEY_ENV + "}";
+
 /** Shown on multiselect prompts — Clack uses arrows, Space toggles, Enter submits */
 export const MULTISELECT_HINT =
   "↑↓ move highlight · Space = select or deselect · Enter = finish";
@@ -48,6 +56,19 @@ export function mask(key) {
   return "***";
 }
 
+// ── Secure write ─────────────────────────────────────────────────────────────
+
+/**
+ * Write a file that may contain a secret (API key / auth token) with owner-only
+ * permissions (0600). `fs.writeFileSync`'s `mode` only applies when the file is
+ * created, so we also `chmod` to tighten any pre-existing file on the default
+ * umask (which would otherwise leave it world-readable at 0644).
+ */
+export function writeFileSecure(filePath, data) {
+  fs.writeFileSync(filePath, data, { mode: 0o600 });
+  try { fs.chmodSync(filePath, 0o600); } catch {}
+}
+
 // ── JSON helpers ─────────────────────────────────────────────────────────────
 
 export function jsonRead(filePath, keyPath) {
@@ -65,15 +86,15 @@ export function settingsSetEnv(filePath, pairs) {
   if (!data.env) data.env = {};
   Object.assign(data.env, pairs);
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
+  writeFileSecure(filePath, JSON.stringify(data, null, 2) + "\n");
 }
 
 export function settingsSetKey(filePath, key, value) {
   let data = {};
   try { data = JSON.parse(fs.readFileSync(filePath, "utf8")); } catch {}
   data[key] = value;
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
+  writeFileSecure(filePath, JSON.stringify(data, null, 2) + "\n");
 }
 
 export function settingsRemoveKeys(filePath, envKeys) {
@@ -83,7 +104,7 @@ export function settingsRemoveKeys(filePath, envKeys) {
   for (const k of envKeys) delete env[k];
   if (Object.keys(env).length === 0) delete data.env;
   else data.env = env;
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
+  writeFileSecure(filePath, JSON.stringify(data, null, 2) + "\n");
 }
 
 // ── MCP settings helpers ─────────────────────────────────────────────────────
@@ -122,7 +143,7 @@ export function settingsSetMcp(filePath, servers, { scope = "user", projectPath
   if (!target.mcpServers) target.mcpServers = {};
   Object.assign(target.mcpServers, servers);
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
+  writeFileSecure(filePath, JSON.stringify(data, null, 2) + "\n");
 }
 
 /**
@@ -137,7 +158,7 @@ export function settingsRemoveMcp(filePath, names, { scope = "user", projectPath
   for (const n of names) delete servers[n];
   if (Object.keys(servers).length === 0) delete target.mcpServers;
   else target.mcpServers = servers;
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
+  writeFileSecure(filePath, JSON.stringify(data, null, 2) + "\n");
 }
 
 /**
@@ -309,7 +330,8 @@ export function writeShellRc(filePath, block) {
     ""
   );
   content += "\n" + block + "\n";
-  fs.writeFileSync(filePath, content);
+  // Shell rc may carry an exported API key — keep it owner-only.
+  writeFileSecure(filePath, content);
 }
 
 export function removeShellRcBlock(filePath) {

tests/api.test.js

@@ -167,6 +167,16 @@ describe("buildClaudeMcpHttpConfig", () => {
       url: "https://mcp.portkey.ai/linear/mcp",
     });
   });
+
+  it("uses the env-var reference instead of the live key when keyRef is set (committed scope)", () => {
+    const cfg = buildClaudeMcpHttpConfig(
+      { url: "https://mcp.portkey.ai/linear/mcp" },
+      "pk-secret-123",
+      { keyRef: "${PORTKEY_API_KEY}" }
+    );
+    expect(cfg.headers["x-portkey-api-key"]).toBe("${PORTKEY_API_KEY}");
+    expect(JSON.stringify(cfg)).not.toContain("pk-secret-123");
+  });
 });
 
 // ── portkeyMcpRequiresOAuth ───────────────────────────────────────────────────

tests/utils.test.js

@@ -15,8 +15,13 @@ import {
   settingsReadMcp,
   writeShellRc,
   removeShellRcBlock,
+  writeFileSecure,
 } from "../src/utils.js";
 
+function mode(file) {
+  return (fs.statSync(file).mode & 0o777).toString(8);
+}
+
 function tmpDir() {
   return fs.mkdtempSync(path.join(os.tmpdir(), "portkey-test-"));
 }
@@ -140,6 +145,43 @@ describe("jsonRead", () => {
   });
 });
 
+// ── writeFileSecure (0600 for secret-bearing files) ───────────────────────────
+
+describe("writeFileSecure", () => {
+  let dir;
+  beforeEach(() => { dir = tmpDir(); });
+  afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+
+  it("creates new files with owner-only 0600 permissions", () => {
+    const file = path.join(dir, "secret.json");
+    writeFileSecure(file, "secret");
+    expect(mode(file)).toBe("600");
+  });
+
+  it("tightens a pre-existing world-readable (0644) file to 0600", () => {
+    const file = path.join(dir, "existing.json");
+    fs.writeFileSync(file, "old", { mode: 0o644 });
+    expect(mode(file)).toBe("644");
+    writeFileSecure(file, "new");
+    expect(mode(file)).toBe("600");
+  });
+
+  it("is used by settings/mcp/shellrc writers so secrets are never world-readable", () => {
+    const settings = path.join(dir, "settings.json");
+    settingsSetEnv(settings, { ANTHROPIC_AUTH_TOKEN: "pk-secret" });
+    expect(mode(settings)).toBe("600");
+
+    const mcp = path.join(dir, ".mcp.json");
+    settingsSetMcp(mcp, { srv: { type: "http", url: "u" } }, { scope: "project" });
+    expect(mode(mcp)).toBe("600");
+
+    const rc = path.join(dir, ".bashrc");
+    fs.writeFileSync(rc, "# rc", { mode: 0o644 });
+    writeShellRc(rc, "export ANTHROPIC_AUTH_TOKEN=pk-secret");
+    expect(mode(rc)).toBe("600");
+  });
+});
+
 // ── settingsSetEnv / settingsRemoveKeys ───────────────────────────────────────
 
 describe("settingsSetEnv + settingsRemoveKeys", () => {