@sphyr/cli 2.0.0-beta.1

package/src/lib/ide-clients.js

@@ -0,0 +1,411 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sphyr
+
+/**
+ * IDE client definitions for sphyr init.
+ *
+ * Provides:
+ *   IDE_CLIENTS                — ordered array of 6 supported IDE clients
+ *   detectInstalledClients()   — returns Set of installed client IDs
+ *   isSphyrEntry(...)          — returns true if an mcpServers key/entry is sphyr-owned (D-04)
+ *   mergeClientConfig(...)     — read-merge-write a client's JSON config file
+ *   buildServerEntry(...)      — constructs the MCP server entry JSON
+ *   readMcpServersForIde(...)  — reads existing mcpServers for an IDE client
+ *   replaceWithGuardEntry(...) — replaces wrapped entries with a single sphyr-guard entry
+ */
+
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+// D-17: Read the CLI version from package.json at module load time.
+// Using createRequire because this file is ESM ("type": "module" in package.json),
+// so require() is not available natively. createRequire gives us a CJS-compatible
+// require() bound to this file's URL, making the relative path resolution correct
+// regardless of the process cwd. The CLI_VERSION is read once and pinned into
+// every generated npx command to prevent supply-chain attacks via future npm
+// releases of @sphyr/sdk that the user has not vetted.
+const _require = createRequire(import.meta.url);
+const CLI_VERSION = _require('../../package.json').version;
+
+// D-07: Read the SDK version from @sphyr/sdk/package.json at module load time.
+// This is distinct from CLI_VERSION (packages/cli is 1.1.0-beta.1; @sphyr/sdk is
+// 2.0.0-beta.1 — different packages). SDK_VERSION is used in buildServerEntry to
+// pin the sphyr-guard binary to the exact SDK version installed in this workspace,
+// satisfying the D-17 supply-chain pinning requirement for the new sphyr-guard entry.
+export const SDK_VERSION = _require('@sphyr/sdk/package.json').version;
+
+const HOME = os.homedir();
+const PLATFORM = process.platform;
+
+// Helper: resolve %APPDATA% on Windows, fall back to HOME-relative on others
+function appdata(...segments) {
+  if (PLATFORM === 'win32') {
+    const base = process.env.APPDATA || path.join(HOME, 'AppData', 'Roaming');
+    return path.join(base, ...segments);
+  }
+  return null;
+}
+
+/**
+ * IDE_CLIENTS — 6 entries in priority order:
+ *   Claude Desktop, Cursor, VS Code (Cline/Roo), Antigravity, Zed, Windsurf
+ *
+ * Each entry:
+ *   id           — string identifier
+ *   name         — display name
+ *   configPath() — returns absolute path or null (e.g. Claude Desktop on Linux)
+ *   topLevelKey  — JSON key for the MCP servers block
+ *   entryExtra   — optional extra fields merged into the server entry
+ */
+export const IDE_CLIENTS = [
+  {
+    id: 'claude-desktop',
+    name: 'Claude Desktop',
+    configPath() {
+      if (PLATFORM === 'darwin') {
+        return path.join(HOME, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+      }
+      if (PLATFORM === 'win32') {
+        return appdata('Claude', 'claude_desktop_config.json');
+      }
+      // Linux: not supported
+      return null;
+    },
+    topLevelKey: 'mcpServers',
+    entryExtra: undefined,
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    configPath() {
+      return path.join(HOME, '.cursor', 'mcp.json');
+    },
+    topLevelKey: 'mcpServers',
+    entryExtra: undefined,
+  },
+  {
+    id: 'vscode',
+    name: 'VS Code (Cline/Roo)',
+    configPath() {
+      if (PLATFORM === 'win32') {
+        return appdata('Code', 'User', 'mcp.json');
+      }
+      return path.join(HOME, '.vscode', 'mcp.json');
+    },
+    topLevelKey: 'servers',
+    entryExtra: { type: 'stdio' },
+  },
+  {
+    id: 'antigravity',
+    name: 'Antigravity',
+    configPath() {
+      return path.join(HOME, '.gemini', 'antigravity', 'mcp_config.json');
+    },
+    topLevelKey: 'mcpServers',
+    entryExtra: undefined,
+  },
+  {
+    id: 'zed',
+    name: 'Zed',
+    configPath() {
+      if (PLATFORM === 'win32') {
+        return appdata('Zed', 'settings.json');
+      }
+      return path.join(HOME, '.config', 'zed', 'settings.json');
+    },
+    topLevelKey: 'context_servers',
+    entryExtra: undefined,
+  },
+  {
+    id: 'windsurf',
+    name: 'Windsurf',
+    configPath() {
+      return path.join(HOME, '.codeium', 'windsurf', 'mcp_config.json');
+    },
+    topLevelKey: 'mcpServers',
+    entryExtra: undefined,
+  },
+];
+
+/**
+ * Returns a Set of client IDs whose configPath() is non-null AND whose config
+ * file (or its parent directory) exists on the filesystem.
+ */
+export function detectInstalledClients() {
+  const installed = new Set();
+  for (const client of IDE_CLIENTS) {
+    const cfgPath = client.configPath();
+    if (!cfgPath) continue;
+    // Check for the file itself, or the parent directory (e.g. app is installed
+    // but config hasn't been created yet)
+    if (fs.existsSync(cfgPath) || fs.existsSync(path.dirname(cfgPath))) {
+      installed.add(client.id);
+    }
+  }
+  return installed;
+}
+
+/**
+ * Read-merge-write a client's JSON config file.
+ *
+ * @param {string} configPath   — absolute path to the config file
+ * @param {string} topLevelKey  — JSON key that holds the MCP servers map
+ * @param {string} serverEntryKey — the key to set within the servers map
+ * @param {object} serverEntry  — the MCP server entry object to write
+ */
+export function mergeClientConfig(configPath, topLevelKey, serverEntryKey, serverEntry) {
+  let existing = {};
+
+  if (fs.existsSync(configPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      if (typeof existing !== 'object' || existing === null || Array.isArray(existing)) {
+        throw new Error(
+          `Config file at ${configPath} must contain a JSON object at the top level. ` +
+            `Found ${Array.isArray(existing) ? 'array' : typeof existing}. ` +
+            `Fix the file manually, then re-run sphyr init.`,
+        );
+      }
+    } catch (parseErr) {
+      throw new Error(
+        `Config file at ${configPath} contains invalid JSON and cannot be merged safely.\n` +
+          `Fix the file manually, then re-run sphyr init.\n` +
+          `Parse error: ${parseErr.message}`,
+      );
+    }
+  } else {
+    // Ensure parent directory exists
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  }
+
+  if (!existing[topLevelKey] || typeof existing[topLevelKey] !== 'object') {
+    existing[topLevelKey] = {};
+  }
+
+  existing[topLevelKey][serverEntryKey] = serverEntry;
+
+  fs.writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+  fs.chmodSync(configPath, 0o600);
+}
+
+/**
+ * Returns true if an mcpServers entry should be excluded from SPHYR_DOWNSTREAM
+ * (D-04 belt-and-suspenders circular-wrapping prevention).
+ *
+ * Exclusion rules:
+ *   1. Key prefix check: key.toLowerCase().startsWith('sphyr')
+ *   2. Command/args content check: 'sphyr-guard' or 'sphyr-proxy' appears in
+ *      entry.command or entry.args (catches sphyr binaries keyed under non-sphyr names)
+ *
+ * Exported so init.js can use it for wrappedKeys computation and D-04 logging
+ * without duplicating the rule (kept in sync automatically).
+ *
+ * @param {string} key     — the mcpServers entry key
+ * @param {object} entry   — the mcpServers entry value
+ * @returns {boolean}
+ */
+export function isSphyrEntry(key, entry) {
+  if (key.toLowerCase().startsWith('sphyr')) return true;
+  const cmd = entry.command || '';
+  const argsStr = (entry.args || []).join(' ');
+  return cmd.includes('sphyr-guard') || cmd.includes('sphyr-proxy') || cmd.includes('sphyr-mcp') ||
+    argsStr.includes('sphyr-guard') || argsStr.includes('sphyr-proxy') || argsStr.includes('sphyr-mcp');
+}
+
+/**
+ * Reads existing mcpServers entries from an IDE client's config, applying D-04
+ * exclusion, D-08 mapping, and D-01 merge semantics with dual legacy source support.
+ *
+ * Returns warnings in the result object — callers (init.js) are responsible for
+ * surfacing them via p.log.warn(). This file has no @clack/prompts dependency.
+ *
+ * @param {object} client — an entry from IDE_CLIENTS (must have configPath() and topLevelKey)
+ * @returns {{ all: object[], existingWrapped: object[], newIndividual: object[], warnings: string[] }}
+ */
+// eslint-disable-next-line max-lines-per-function -- sequential read-merge phases with D-01/D-04/D-08 logic; splitting would obscure the merge invariant
+export function readMcpServersForIde(client) {
+  const empty = { all: [], existingWrapped: [], newIndividual: [], warnings: [] };
+
+  const configPath = client.configPath();
+  if (!configPath || !fs.existsSync(configPath)) {
+    return empty;
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch (parseErr) {
+    // Non-fatal during preview phase (D-03) — return empty with a warning
+    return {
+      ...empty,
+      warnings: [`Config file at ${configPath} could not be parsed: ${parseErr.message}`],
+    };
+  }
+
+  // Use client.topLevelKey (NOT hardcoded 'mcpServers') — Pitfall 6:
+  // Zed uses 'context_servers', VS Code uses 'servers'.
+  const servers = config[client.topLevelKey] || {};
+  const warnings = [];
+
+  // Read previously-wrapped servers from BOTH legacy sources (D-01 re-run correctness).
+  // 'sphyr' is the current canonical entry; it wins on name collision with any legacy
+  // 'sphyr-guard' entry (the pre-rename entry written by older versions of this CLI).
+  let canonicalWrapped = [];
+  let legacyGuardWrapped = [];
+
+  const canonicalEntry = servers['sphyr'];
+  const legacyGuardEntry = servers['sphyr-guard'];
+
+  if (canonicalEntry?.env?.SPHYR_DOWNSTREAM) {
+    try {
+      canonicalWrapped = JSON.parse(canonicalEntry.env.SPHYR_DOWNSTREAM);
+      if (!Array.isArray(canonicalWrapped)) canonicalWrapped = [];
+    } catch {
+      warnings.push(
+        `Existing SPHYR_DOWNSTREAM in 'sphyr' could not be parsed — ` +
+        `previously-wrapped servers from that entry will be lost. ` +
+        `Check the entry manually.`,
+      );
+      canonicalWrapped = [];
+    }
+  }
+
+  if (legacyGuardEntry?.env?.SPHYR_DOWNSTREAM) {
+    try {
+      legacyGuardWrapped = JSON.parse(legacyGuardEntry.env.SPHYR_DOWNSTREAM);
+      if (!Array.isArray(legacyGuardWrapped)) legacyGuardWrapped = [];
+    } catch {
+      warnings.push(
+        `Existing SPHYR_DOWNSTREAM in 'sphyr-guard' could not be parsed — ` +
+        `previously-wrapped servers from that entry will be lost. ` +
+        `Check the entry manually.`,
+      );
+      legacyGuardWrapped = [];
+    }
+  }
+
+  // Merge both sources. 'sphyr' wins on name collision (it is the current canonical
+  // entry written by this version of the CLI; 'sphyr-guard' is a legacy key from
+  // older installs that used @sphyr/agent-guard-cli).
+  const existingWrappedMap = new Map(legacyGuardWrapped.map(e => [e.name, e]));
+  for (const e of canonicalWrapped) existingWrappedMap.set(e.name, e);
+  const existingWrapped = [...existingWrappedMap.values()];
+
+  // Build newIndividual: iterate mcpServers, exclude sphyr entries (D-04),
+  // map to DownstreamServerConfig shape (D-08 — unknown fields dropped silently).
+  const newIndividual = Object.entries(servers)
+    .filter(([key, entry]) => !isSphyrEntry(key, entry))
+    .map(([key, entry]) => ({
+      name: key,
+      command: entry.command,
+      args: entry.args || [],
+      ...(entry.env ? { env: entry.env } : {}),
+    }));
+
+  // Merge with D-01 semantics: existing first, new individual wins on name collision.
+  const merged = new Map(existingWrapped.map(e => [e.name, e]));
+  for (const e of newIndividual) merged.set(e.name, e);
+
+  return {
+    all: [...merged.values()],
+    existingWrapped,
+    newIndividual,
+    warnings,
+  };
+}
+
+/**
+ * Constructs the MCP server entry for a given client.
+ * Generates a sphyr-guard entry with SPHYR_DOWNSTREAM embedded in env.
+ *
+ * The sphyr-guard binary fail-fasts at startup if required env vars are missing,
+ * so callers must always supply all required env vars.
+ *
+ * @param {object} client        — an entry from IDE_CLIENTS
+ * @param {string} credential    — the Sphyr single credential (`sphyr_v1_<keyId>.<signingSecret>`)
+ * @param {string} downstreamJson — JSON.stringify'd DownstreamServerConfig[] array
+ * @returns {object} the server entry object
+ */
+export function buildServerEntry(client, credential, downstreamJson) {
+  // D-07: Pin SDK_VERSION (not CLI_VERSION) in the npx command — the sphyr-mcp
+  // binary lives in @sphyr/sdk, not @sphyr/cli. Using SDK_VERSION ensures the
+  // generated config pins the correct package at the correct version.
+  // D-06: args use 'sphyr-mcp'; SPHYR_DOWNSTREAM added to env.
+  const entry = {
+    command: 'npx',
+    args: ['-y', '-p', `@sphyr/sdk@${SDK_VERSION}`, 'sphyr-mcp'],
+    env: {
+      SPHYR_CREDENTIAL: credential,
+      SPHYR_DOWNSTREAM: downstreamJson,
+    },
+  };
+  if (client.entryExtra) Object.assign(entry, client.entryExtra);
+  return entry;
+}
+
+/**
+ * Replaces existing wrapped + sphyr-prefixed entries in an IDE config with a
+ * single sphyr-guard entry (D-05 write operation).
+ *
+ * Steps:
+ *   1. Read existing config (replicates mergeClientConfig read-guard exactly)
+ *   2. Delete all keys in wrappedKeys from config[topLevelKey]
+ *   3. Delete any remaining keys whose lowercased prefix starts with 'sphyr' (upgrade path)
+ *   4. Write config[topLevelKey]['sphyr-guard'] = guardEntry
+ *   5. Write file with 0o600 permissions (belt-and-suspenders: mode in writeFileSync + chmodSync)
+ *
+ * @param {string} configPath    — absolute path to the config file
+ * @param {string} topLevelKey   — JSON key that holds the MCP servers map
+ * @param {object} guardEntry    — the sphyr-guard entry to write
+ * @param {string[]} wrappedKeys — keys to remove from servers (the previously-individual entries)
+ */
+// eslint-disable-next-line max-lines-per-function -- sequential read-guard then delete-write phases; splitting obscures the file-integrity invariant (same rationale as mergeClientConfig)
+export function replaceWithGuardEntry(configPath, topLevelKey, guardEntry, wrappedKeys) {
+  let existing = {};
+
+  if (fs.existsSync(configPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      if (typeof existing !== 'object' || existing === null || Array.isArray(existing)) {
+        throw new Error(
+          `Config file at ${configPath} must contain a JSON object at the top level. ` +
+            `Found ${Array.isArray(existing) ? 'array' : typeof existing}. ` +
+            `Fix the file manually, then re-run sphyr init.`,
+        );
+      }
+    } catch (parseErr) {
+      throw new Error(
+        `Config file at ${configPath} contains invalid JSON and cannot be merged safely.\n` +
+          `Fix the file manually, then re-run sphyr init.\n` +
+          `Parse error: ${parseErr.message}`,
+      );
+    }
+  } else {
+    // Ensure parent directory exists
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  }
+
+  if (!existing[topLevelKey] || typeof existing[topLevelKey] !== 'object') {
+    existing[topLevelKey] = {};
+  }
+  const servers = existing[topLevelKey];
+
+  // Remove the individual wrapped entries (the ones now encoded in SPHYR_DOWNSTREAM)
+  for (const key of wrappedKeys) delete servers[key];
+
+  // Remove any remaining sphyr-prefixed entries (upgrade path D-05):
+  // clears old 'sphyr', 'sphyr-proxy', 'sphyr-guard' regardless of wrappedKeys.
+  for (const key of Object.keys(servers)) {
+    if (key.toLowerCase().startsWith('sphyr')) delete servers[key];
+  }
+
+  // Write the single new 'sphyr' entry (key is hardcoded — ROADMAP SC-2, Pitfall 2)
+  servers['sphyr'] = guardEntry;
+
+  // Belt-and-suspenders: set mode in writeFileSync AND follow up with chmodSync
+  // (same pattern as mergeClientConfig — both calls required per security requirement)
+  fs.writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+  fs.chmodSync(configPath, 0o600);
+}

package/src/lib/url-guard.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sphyr Agent Guard Contributors
+//
+// packages/cli/src/lib/url-guard.js
+//
+// REVIEW.md W-10 (2026-06-09): SPHYR_API_URL / SPHYR_MCP_URL flow into the
+// device flow and are persisted into ~/.sphyr/config.json, where the SDK reads
+// them for credentialed traffic indefinitely. A poisoned env var at login time
+// would silently redirect credentials to an attacker host. guard.js has always
+// enforced HTTPS on its own env var; this helper ports the same rule (plus the
+// SDK's local-host exception, matching sdk/ts/guard.ts) to the two commands
+// that actually handle the credential.
+
+const LOCAL_HOSTNAMES = ['localhost', '127.0.0.1', '[::1]'];
+
+/** Strips userinfo so a URL can be printed in errors without leaking embedded credentials. */
+export function safeUrl(raw) {
+  try {
+    const u = new URL(raw);
+    u.username = '';
+    u.password = '';
+    return u.toString();
+  } catch {
+    return '<invalid url>';
+  }
+}
+
+/**
+ * Validates an endpoint URL sourced from an env var. Exits the process on a
+ * non-HTTPS non-local URL; prints a loud notice when a non-default endpoint is
+ * in effect so an unexpected override is visible at the moment credentials flow.
+ *
+ * @param {string} value        the URL in effect (env override or default)
+ * @param {string} envName      the env var name, for messages
+ * @param {string} defaultValue the built-in default endpoint
+ * @returns {string} value, unchanged, for assignment convenience
+ */
+export function requireTrustedEndpoint(value, envName, defaultValue) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    process.stderr.write(`[sphyr] Fatal: ${envName} is not a valid URL: ${safeUrl(value)}\n`);
+    process.exit(1);
+  }
+  if (parsed.protocol !== 'https:' && !LOCAL_HOSTNAMES.includes(parsed.hostname)) {
+    process.stderr.write(
+      `[sphyr] Fatal: ${envName} must use https:// for non-local hosts (got: ${safeUrl(value)}). ` +
+        `Credentials will not be sent over an insecure or unexpected transport.\n`,
+    );
+    process.exit(1);
+  }
+  if (value !== defaultValue) {
+    process.stderr.write(
+      `[sphyr] NOTICE: ${envName} is overridden — credentials will flow to ${safeUrl(value)} (default: ${defaultValue}).\n`,
+    );
+  }
+  return value;
+}