Merge pull request #9 from kiran-4444/fix/apikey-as-plaintext

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

Author: VisargD

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. Each teammate just exports their own `PORTKEY_API_KEY`:
+>
+> ```bash
+> export PORTKEY_API_KEY="pk-..."   # add to ~/.zshrc, ~/.bashrc, or CI secrets
+> ```
+>
+> Config files the CLI creates itself (`~/.claude/settings.json`, `.mcp.json`) are written with owner-only `0600` permissions. Your **shell profile** (`~/.zshrc`, `~/.bashrc`, …) is left untouched — the CLI never changes its permissions — but it **warns** if that file is readable by other users while holding a secret, so you can `chmod 600` it yourself on shared machines.
+
 **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,20 @@ 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,
+  warnIfFileGroupOrWorldReadable,
   getMcpFilePath,
   settingsSetMcp,
   settingsRemoveMcp,
@@ -46,7 +52,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 +180,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 +296,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 +318,35 @@ 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.`
+    );
+    warnIfFileGroupOrWorldReadable(shellRc, `your ${PORTKEY_KEY_ENV}`);
+  } 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,
@@ -23,6 +25,7 @@ import {
   settingsSetKey,
   settingsSetMcp,
   writeShellRc,
+  warnIfFileGroupOrWorldReadable,
   normalizeProvider,
   isClaudeInstalled,
   readExistingConfig,
@@ -136,7 +139,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({
@@ -841,6 +844,7 @@ export async function doSetup(args) {
       "# ── End Portkey + Codex ──",
     ].join("\n"));
     ok(`PORTKEY_API_KEY written to ${shellRc}`);
+    warnIfFileGroupOrWorldReadable(shellRc, "your PORTKEY_API_KEY");
 
     const reloadCmd = isPwsh ? `. ${shellRc}` : `source ${shellRc}`;
     console.log();
@@ -882,12 +886,16 @@ export async function doSetup(args) {
 
       writeShellRc(targetFile, lines.join("\n"));
       ok(`Gateway config written to ${targetFile}`);
+      warnIfFileGroupOrWorldReadable(targetFile, "your ANTHROPIC_AUTH_TOKEN");
 
     } 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 +907,34 @@ 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}`);
+      }
+      warnIfFileGroupOrWorldReadable(shellRc, `your ${shellVar}`);
     }
 
     // Reload reminder (once, at the end)
@@ -1140,11 +1159,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 +1183,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,40 @@ export function mask(key) {
   return "***";
 }
 
+// ── Secure write ─────────────────────────────────────────────────────────────
+
+/**
+ * Write a file the CLI itself authors and 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).
+ *
+ * Use this only for files we own (e.g. `.mcp.json`, `.claude/settings.json`).
+ * Do NOT use it for user-managed files like shell rc — their permissions are the
+ * user's choice; warn with `warnIfFileGroupOrWorldReadable` instead.
+ */
+export function writeFileSecure(filePath, data) {
+  fs.writeFileSync(filePath, data, { mode: 0o600 });
+  try { fs.chmodSync(filePath, 0o600); } catch {}
+}
+
+/**
+ * Warn (without modifying anything) when a file we just wrote a secret into is
+ * readable by group or other. Intended for user-managed files such as shell rc,
+ * where we deliberately never change permissions implicitly.
+ */
+export function warnIfFileGroupOrWorldReadable(filePath, secretLabel = "a credential") {
+  let mode;
+  try { mode = fs.statSync(filePath).mode & 0o777; } catch { return; }
+  if (mode & 0o077) {
+    warn(
+      `${filePath} is readable by other users (permissions ${mode.toString(8)}) and now contains ${secretLabel}. ` +
+        `On a shared machine, restrict it with: ${c.bold}chmod 600 ${filePath}${c.reset}`
+    );
+  }
+}
+
 // ── JSON helpers ─────────────────────────────────────────────────────────────
 
 export function jsonRead(filePath, keyPath) {
@@ -65,15 +107,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 +125,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 +164,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 +179,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,6 +351,9 @@ export function writeShellRc(filePath, block) {
     ""
   );
   content += "\n" + block + "\n";
+  // Preserve the user's existing permissions — never implicitly chmod a
+  // user-managed shell rc. Callers warn via warnIfFileGroupOrWorldReadable
+  // when the block contains a secret.
   fs.writeFileSync(filePath, content);
 }
 

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 ───────────────────────────────────────────────────