@commonlyai/cli 0.1.61 → 0.1.64

package/src/lib/mcp-credential-delivery.js

@@ -0,0 +1,110 @@
+/**
+ * How a declared MCP server receives the seat credential, for the two adapters
+ * that cannot hand it over on a pipe.
+ *
+ * The pi bridge spawns the server itself, so it can pipe the credential on an
+ * inherited fd (see `pi-mcp-client.mjs`). Claude and codex do not: each of them
+ * starts the server inside its own process tree, so the only two channels
+ * available are (a) a value in the runtime's environment, which the whole
+ * subtree inherits, or (b) a PATH in the declaration that the server itself
+ * reads. (b) is the one that leaves the token where it belongs.
+ *
+ * This module makes that choice in ONE place, because three call sites deciding
+ * version thresholds independently is how one of them ends up handing over the
+ * value while the others hand over the path.
+ *
+ * The rewrite is of the DECLARATION, not of the value: an entry that named
+ * `COMMONLY_AGENT_TOKEN` comes back naming `COMMONLY_TOKEN_FILE`, so the value
+ * never exists in the runtime's environment to be inherited, logged, or dumped
+ * by an unrelated MCP server that a seat was granted.
+ */
+import { CREDENTIAL_FILE_VAR, CREDENTIAL_KEY } from './credential-file.js';
+import {
+  FILE_READER_VERSION, MCP_PACKAGE, describeMcpCommand, versionOlderThan,
+} from './mcp-server-version.js';
+
+/** What a declaration should say to receive the credential as a path. */
+export const CREDENTIAL_FILE_PLACEHOLDER = '${COMMONLY_TOKEN_FILE}';
+
+/**
+ * What a runtime's OWN environment may carry, once the declarations are settled.
+ *
+ * The rewrite above decides what a CHILD is told. It does not decide what the
+ * runtime process itself carries, and that is a separate leak with the same
+ * symptom: the credential is exported for bootstrap (`agent run`, the daemon),
+ * so an adapter that derives its runtime environment from `process.env` hands
+ * the value back to the runtime — and to every MCP child, hook and shell below
+ * it — however the declaration was rewritten. Measured (Vera, 70455): four tests
+ * that pass in a runner without the variable fail with it set, and the value
+ * they saw was the runner's own.
+ *
+ * So the PATH of this spawn's file goes in (a path is not a secret, and a hook
+ * process resolves its credential from it — see `hooks-config.resolveHookToken`)
+ * and the VALUE comes out, unless a carve-out genuinely needs the value here:
+ * a field the adapter substitutes LITERALLY has no file channel, so `keepsValue`
+ * is passed in by the adapter rather than inferred, and the spawn that keeps a
+ * secret says so in its own warning.
+ */
+export const withholdRuntimeCredential = (env, { credentialFile = null, keepsValue = false } = {}) => {
+  if (credentialFile) env[CREDENTIAL_FILE_VAR] = credentialFile;
+  if (!keepsValue) delete env[CREDENTIAL_KEY];
+  return env;
+};
+
+/** What a declaration says when it asks for the seat credential (the old shape). */
+export const CREDENTIAL_PLACEHOLDER = '${COMMONLY_AGENT_TOKEN}';
+
+/**
+ * Rewrite one server's declared environment so the credential arrives as a path.
+ *
+ * Returns `{ env, delivered }` where `delivered` is one of:
+ *   'path'        — the declaration now names the file; the adapter expands it
+ *   'env'         — the value stays in the environment, deliberately (see below)
+ *   'none'        — nothing to deliver: the entry declares no credential
+ *   'unavailable' — no launcher credential file exists for this spawn
+ *
+ * `env` is a fresh object; the caller's declaration is never mutated.
+ */
+export const deliverSeatCredential = (server, {
+  credentialFile,
+  onWarn = (message) => process.stderr.write(`${message}\n`),
+  label = 'mcp',
+} = {}) => {
+  const env = { ...((server || {}).env || {}) };
+  if (env[CREDENTIAL_FILE_VAR] !== undefined && String(env[CREDENTIAL_FILE_VAR]).trim() !== '') {
+    // Already on the launcher channel — an operator who set this by hand, or a
+    // record written after this shipped. Nothing to rewrite.
+    return { env, delivered: 'path' };
+  }
+  if (env[CREDENTIAL_KEY] === undefined) return { env, delivered: 'none' };
+  if (!credentialFile) {
+    // No launcher wrote a file, so there is nothing to point at. Leave the
+    // declaration exactly as it was rather than handing over a path to nowhere.
+    return { env, delivered: 'unavailable' };
+  }
+  const ours = describeMcpCommand((server || {}).command);
+  if (!ours) {
+    // Somebody else's server. Their declaration is theirs: we do not know their
+    // protocol, so replacing their variable with a path would break a server we
+    // have no business redefining.
+    onWarn(`[${label}] ${server?.name} is not ${MCP_PACKAGE} but declares ${CREDENTIAL_KEY}; leaving that declaration alone. Declare the seat credential on the commonly entry instead.`);
+    return { env, delivered: 'env' };
+  }
+  if (versionOlderThan(ours.version, FILE_READER_VERSION) === true) {
+    // Measured, not hypothetical: five seats run a hand-patched staging checkout
+    // at 0.3.7, whose reader only understands the environment. Handing it a path
+    // it cannot read would take its tools away rather than its secret.
+    onWarn(`[${label}] ${server.name} runs @commonlyai/mcp ${ours.version.join('.')}, which predates the credential file (${FILE_READER_VERSION.join('.')}): keeping the token in the environment. Unpin it, or move that seat off this checkout.`);
+    return { env, delivered: 'env' };
+  }
+  if (String(env[CREDENTIAL_KEY]) !== CREDENTIAL_PLACEHOLDER) {
+    // A literal token in a declaration is stale by construction — seat tokens
+    // rotate, and this one was read when the record was written. Superseding it
+    // with the live credential is a repair, but it IS a change in what the seat
+    // sends, so it is said out loud rather than done quietly.
+    onWarn(`[${label}] ${server.name} declares a literal ${CREDENTIAL_KEY}; superseding it with this spawn's credential file.`);
+  }
+  delete env[CREDENTIAL_KEY];
+  env[CREDENTIAL_FILE_VAR] = CREDENTIAL_FILE_PLACEHOLDER;
+  return { env, delivered: 'path' };
+};

package/src/lib/mcp-server-version.js

@@ -0,0 +1,90 @@
+/**
+ * Which `@commonlyai/mcp` a declared MCP command would run, and which channels
+ * that release understands.
+ *
+ * Shared by the pi bridge (which decides whether to pipe a credential) and by
+ * the claude and codex adapters (which decide whether to hand over a PATH or the
+ * value): one predicate, because three copies of "is this old enough" would
+ * drift, and the drift would be silent in exactly one adapter.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const MCP_PACKAGE = '@commonlyai/mcp';
+
+/** The release whose reader accepts the credential on an inherited fd. */
+export const PIPE_READER_VERSION = [0, 3, 11];
+
+/** The release whose reader accepts `COMMONLY_TOKEN_FILE` (a PATH, not a secret). */
+export const FILE_READER_VERSION = [0, 3, 12];
+
+export const parseVersion = (spec) => {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(String(spec || '').trim());
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+};
+
+/**
+ * True when `version` is older than `target`; null when there is no version to
+ * judge (an unpinned `@latest` tracks the published release, so it is never
+ * treated as old).
+ */
+export const versionOlderThan = (version, target) => {
+  if (!version) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (version[i] !== target[i]) return version[i] < target[i];
+  }
+  return false;
+};
+
+/**
+ * What an `@commonlyai/mcp` command would run, or null when the command cannot
+ * be identified as that package at all.
+ *
+ * Two shapes matter: `npx [-y] @commonlyai/mcp@<spec>` (a spec is a version, or
+ * `latest`/absent, which resolves to whatever is published — never treated as
+ * old), and a local checkout, `node <path>/src/index.js`, which is what the
+ * staging seats run; for that one the package.json beside it is the only honest
+ * answer, and a package.json naming something else means this is not our server.
+ *
+ * `{ isCommonly: true, version: null }` means "our server, version unknown" —
+ * an unpinned npx spec, whose whole point is that it tracks the published one.
+ * `null` as the return value means "not identifiable as our server", which is a
+ * different answer and takes a different branch: a stranger's server gets its
+ * declaration honoured unchanged.
+ */
+export const describeMcpCommand = (command, {
+  readTextFile = (p) => (existsSync(p) ? readFileSync(p, 'utf8') : null),
+} = {}) => {
+  if (!Array.isArray(command) || command.length === 0) return null;
+  const parts = command.map(String);
+  const pkgArg = parts.find((p) => p.includes(MCP_PACKAGE));
+  if (pkgArg) {
+    const at = pkgArg.lastIndexOf('@');
+    if (at <= pkgArg.indexOf(MCP_PACKAGE)) return { isCommonly: true, version: null };
+    return { isCommonly: true, version: parseVersion(pkgArg.slice(at + 1)) };
+  }
+  const scriptPath = parts.find((p) => p.endsWith('.js') || p.endsWith('.mjs'));
+  if (!scriptPath) return null;
+  // `src/index.js` → `../package.json`; also try one level further up, because a
+  // bin shim can live in `bin/` beside `src/`.
+  for (const candidate of [join(dirname(scriptPath), '..', 'package.json'), join(dirname(scriptPath), 'package.json')]) {
+    let raw;
+    try {
+      raw = readTextFile(candidate);
+    } catch {
+      raw = null;
+    }
+    if (!raw) continue;
+    try {
+      const pkg = JSON.parse(raw);
+      if (!pkg || typeof pkg !== 'object') continue;
+      if (pkg.name === MCP_PACKAGE) return { isCommonly: true, version: parseVersion(pkg.version) };
+      // A package.json that names another package settles it: not ours, so its
+      // declaration is none of this function's business.
+      return null;
+    } catch {
+      // A malformed package.json is not an answer; keep looking.
+    }
+  }
+  return null;
+};