@sphyr/cli 2.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sphyr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# @sphyr/cli
+
+Sphyr platform CLI. Currently ships Agent Guard commands; additional product groups will be added as they launch.
+
+Part of the [Sphyr Agent Guard monorepo](../../README.md).
+
+## Commands
+
+```
+sphyr login              Sign in to Sphyr (device flow — writes ~/.sphyr/config.json)
+sphyr guard init         Interactive setup wizard — writes IDE MCP configs
+sphyr guard verify       Connectivity check (delegates to @sphyr/sdk sphyr-mcp)
+sphyr guard run          STDIO↔HTTP bridge — used directly in IDE MCP config entries
+```
+
+> **`sphyr guard verify`** delegates to the `sphyr-mcp` binary from `@sphyr/sdk` — it performs
+> a real HMAC handshake and `agent_guard_up` round-trip, reports gateway reachability and
+> per-library instrumentation status, and supports `--json` for CI output.
+
+## Installation
+
+Designed to be used via `npx` without a permanent install:
+
+```bash
+npx @sphyr/cli login
+```
+
+To install globally:
+
+```bash
+npm install -g @sphyr/cli
+```
+
+## Quick start — Claude Desktop setup
+
+The recommended way to configure Claude Desktop is to run the interactive setup wizard, which writes the correct config automatically:
+
+```bash
+npx @sphyr/cli guard init
+```
+
+The wizard writes a config entry that routes through the `sphyr-mcp` command from `@sphyr/sdk`, which signs every outbound request with HMAC. The resulting entry looks like:
+
+```json
+{
+  "mcpServers": {
+    "sphyr": {
+      "command": "npx",
+      "args": ["-y", "-p", "@sphyr/sdk", "sphyr-mcp"],
+      "env": {
+        "SPHYR_CREDENTIAL": "your-credential"
+      }
+    }
+  }
+}
+```
+
+`SPHYR_DOWNSTREAM` is optional — add a JSON array of MCP servers to also wrap and guard them
+(tool-poisoning + tool-argument-entropy blocking). The old standalone `sphyr-proxy` binary has been
+**removed**; `sphyr-mcp` replaces it (`init` rewrites any legacy `sphyr-proxy` and `sphyr-guard` IDE entries automatically).
+
+> **Note:** The `init` wizard configures the unified SDK binary (`sphyr-mcp` from `@sphyr/sdk`). The `sphyr guard run` command in *this* CLI package is a simpler STDIO↔HTTP bridge intended for development and advanced manual setups.
+
+## Sign in for SDK use (`login`)
+
+If you are using the Python or TypeScript SDK directly (not just the IDE MCP integration), run:
+
+```bash
+npx @sphyr/cli login
+```
+
+This runs the device flow and writes your credential to `~/.sphyr/config.json` (owner-only `0600`).
+The SDKs then auto-load it — `auto_instrument()` / `autoInstrument()` work with no arguments and no
+manual key copy-paste. Credential precedence: explicit args → `SPHYR_*` env vars → `~/.sphyr/config.json`.
+
+## Headless environments (SSH, containers, CI)
+
+If you are running in a terminal without a browser — SSH session, Docker container, GitHub Codespaces, or a CI environment — use the device flow:
+
+```bash
+npx @sphyr/cli guard init
+```
+
+The wizard will print a short authorization code (e.g. `J3K9-M7PQ`) and a URL:
+
+```
+◆  Authorization code: J3K9-M7PQ
+→  Open: https://console.sphyr.io/device
+```
+
+Open the URL on any device, log in with GitHub if prompted, enter the code, and click **Authorize**. The CLI will detect the approval within 5 seconds and write your IDE configs automatically.
+
+`sphyr guard init` also auto-detects headless environments: if `stdin` is not a TTY (e.g., piped input or a non-interactive shell), the device flow starts automatically.
+
+### Behind a corporate NAT or VPN
+
+If many users on your network run `sphyr guard init` from a shared egress IP (corporate VPN, NAT'd office network, CI fleet, GitHub Codespaces region), the API may transiently rate-limit polling requests from that IP and respond with `HTTP 429 Too Many Requests` and a `Retry-After` header. The CLI handles this automatically: it sleeps for the server-specified duration and resumes polling without surfacing an error.
+
+## Environment variables
+
+| Variable              | Required                 | Default                    | Description                                                           |
+| --------------------- | ------------------------ | -------------------------- | --------------------------------------------------------------------- |
+| `SPHYR_CREDENTIAL`    | Yes (injected by `init`) | —                          | Single credential passed through to the Agent Guard HTTP endpoint     |
+| `AGENT_GUARD_MCP_URL` | No                       | `https://api.sphyr.io/mcp` | Override the upstream MCP endpoint (dev/staging only; must use HTTPS) |
+
+The bridge enforces HTTPS for `AGENT_GUARD_MCP_URL` and will throw at startup if a non-HTTPS URL is provided.
+
+## Source structure
+
+```
+packages/cli/
+  index.js                    # Entry point — two-level command dispatch
+  src/
+    commands/
+      guard.js                # runGuard()  — STDIO↔HTTP bridge
+      init.js                 # runInit()   — interactive setup wizard
+      login.js                # runLogin()  — device-flow sign-in → ~/.sphyr/config.json
+      verify.js               # runVerify() — delegates to @sphyr/sdk sphyr-mcp verify
+    lib/
+      ide-clients.js          # IDE_CLIENTS registry, config read/merge/write helpers
+      url-guard.js            # HTTPS/SSRF URL validation for AGENT_GUARD_MCP_URL
+```
+
+## Supported IDE clients
+
+The `init` wizard detects and can configure:
+
+- Claude Desktop
+- Cursor
+- VS Code (via Cline / Roo extension)
+- Antigravity
+- Zed
+- Windsurf
+
+## Development
+
+This package has no build step — it is plain ES module JavaScript targeting Node >= 22.
+
+```bash
+# From the monorepo root
+nvm use
+npm ci
+
+# Run the bridge against the live API
+AGENT_GUARD_MCP_URL=https://api.sphyr.io/mcp node packages/cli/index.js guard run
+
+# Run the init wizard
+node packages/cli/index.js guard init
+
+# Sign in
+node packages/cli/index.js login
+```
+
+## Tests
+
+Tests are not yet present in this package. The `init` wizard and bridge logic are covered by integration tests in the root `tests/` directory.
+
+## License
+
+MIT
+
+## Prerequisites
+
+- `Node.js >= 22.0.0 < 24.0.0` (enforced by the package `engines` field). Use [nvm](https://github.com/nvm-sh/nvm) and run `nvm use` from the monorepo root to switch to the correct version automatically.
+- When invoking via `npx`, ensure the Node.js version in your shell meets this requirement — `npx` inherits the active Node version and will fail with an engines mismatch error on older releases.

package/index.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sphyr
+
+/**
+ * Sphyr platform CLI
+ *
+ * Top-level commands:
+ *   login       — platform-wide device-flow sign-in (cross-product)
+ *   guard       — Agent Guard subcommand group
+ *
+ * Agent Guard subcommands (sphyr guard <subcommand>):
+ *   init        — interactive setup wizard (configures IDE MCP configs)
+ *   verify      — connectivity check (delegates to @sphyr/sdk sphyr-mcp)
+ *   run         — STDIO↔HTTP bridge (used in IDE MCP config entries)
+ *
+ * Reserved (products not yet available):
+ *   box         — future product placeholder
+ *
+ * Usage in IDE MCP config:
+ *   "command": "npx",
+ *   "args": ["-y", "-p", "@sphyr/sdk@<version>", "sphyr-mcp"]
+ */
+
+import { runGuard } from './src/commands/guard.js';
+import { runInit } from './src/commands/init.js';
+import { runLogin } from './src/commands/login.js';
+import { runVerify } from './src/commands/verify.js';
+
+const [, , topLevel, subCommand] = process.argv;
+
+switch (topLevel) {
+  case 'login':
+    runLogin();
+    break;
+
+  case 'guard':
+    switch (subCommand) {
+      case 'init':
+        runInit();
+        break;
+      case 'verify':
+        runVerify();
+        break;
+      case 'run':
+        runGuard();
+        break;
+      case undefined:
+        process.stderr.write(
+          'Usage: sphyr guard <subcommand>\n\n' +
+          'Subcommands:\n' +
+          '  init     Interactive setup wizard — configures IDE MCP configs\n' +
+          '  verify   Check connectivity to Sphyr Agent Guard\n' +
+          '  run      Start the STDIO↔HTTP MCP bridge\n',
+        );
+        process.exit(1);
+        break;
+      default:
+        process.stderr.write(
+          `Unknown subcommand: sphyr guard ${subCommand}\n` +
+          'Run "sphyr guard" for available subcommands.\n',
+        );
+        process.exit(1);
+    }
+    break;
+
+  case 'box':
+    process.stderr.write('sphyr box: not yet available.\n');
+    process.exit(1);
+    break;
+
+  case undefined:
+    process.stderr.write(
+      'Usage: sphyr <command>\n\n' +
+      'Commands:\n' +
+      '  login    Sign in to Sphyr (device flow)\n' +
+      '  guard    Agent Guard commands (init, verify, run)\n',
+    );
+    process.exit(1);
+    break;
+
+  default:
+    process.stderr.write(
+      `Unknown command: sphyr ${topLevel}\n` +
+      'Run "sphyr" for available commands.\n',
+    );
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@sphyr/cli",
+  "version": "2.0.0-beta.1",
+  "license": "MIT",
+  "description": "Sphyr platform CLI",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "sphyr": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "@sphyr/sdk": "^2.0.0-beta.1",
+    "open": "^11.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0 <24.0.0"
+  }
+}

package/src/commands/guard.js

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sphyr
+
+/**
+ * sphyr guard — STDIO-to-HTTP MCP bridge
+ *
+ * Proxies JSON-RPC lines from stdin to the Sphyr Agent Guard HTTP endpoint
+ * and writes responses to stdout. Used as the command in IDE MCP config:
+ *
+ *   "command": "npx",
+ *   "args": ["-y", "@sphyr/guard", "guard"]
+ */
+
+import readline from 'node:readline';
+import { URL as NURL } from 'node:url';
+
+const AGENT_GUARD_URL = process.env.AGENT_GUARD_MCP_URL || 'https://api.sphyr.io/mcp';
+
+function safeUrl(raw) {
+  try {
+    const u = new NURL(raw);
+    u.username = '';
+    u.password = '';
+    return u.toString();
+  } catch {
+    return '<invalid url>';
+  }
+}
+
+if (!AGENT_GUARD_URL.startsWith('https://')) {
+  throw new Error(
+    `AGENT_GUARD_MCP_URL must use HTTPS. Refusing to proxy over insecure connection: ${safeUrl(AGENT_GUARD_URL)}`,
+  );
+}
+
+const AGENT_GUARD_SAFE_URL = safeUrl(AGENT_GUARD_URL);
+
+/**
+ * Runs the STDIO-to-HTTP MCP bridge.
+ * Reads JSON-RPC lines from stdin, proxies each to the MCP HTTP endpoint,
+ * and writes the response to stdout as a single line.
+ */
+export function runGuard() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    terminal: false,
+  });
+
+  rl.on('close', () => {
+    // stdin closed (IDE shut down or pipe ended) — event loop drains naturally
+    process.exit(0);
+  });
+
+  let inFlight = 0;
+  const MAX_CONCURRENT = 10;
+
+  rl.on('line', async (line) => {
+    const content = line.trim();
+    if (!content) return;
+
+    if (inFlight >= MAX_CONCURRENT) {
+      // Drop the request and emit a JSON-RPC error to avoid unbounded concurrency.
+      let requestId = null;
+      try {
+        requestId = JSON.parse(content).id ?? null;
+      } catch {
+        /* ignore */
+      }
+      const errMessage = JSON.stringify({
+        jsonrpc: '2.0',
+        error: { code: -32000, message: 'Agent Guard CLI Bridge Error: too many concurrent requests' },
+        id: requestId,
+      });
+      process.stdout.write(errMessage + '\n');
+      return;
+    }
+
+    inFlight = inFlight + 1;
+
+    try {
+      // Attempt to extract the request ID for well-formed error responses
+      let requestId = null;
+      try {
+        const parsed = JSON.parse(content);
+        requestId = parsed.id ?? null;
+      } catch {
+        // Ignore parse errors here, let the upstream gateway handle it
+      }
+
+      try {
+        const response = await fetch(AGENT_GUARD_URL, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+          },
+          body: content,
+        });
+
+        const body = await response.text();
+        if (!response.ok) {
+          // Non-2xx response — emit a proper JSON-RPC error instead of forwarding
+          // a raw HTML error page that would corrupt the JSON-RPC stream.
+          process.stderr.write(`[guard] upstream error ${response.status}: ${body.slice(0, 200)}\n`);
+          const errMessage = JSON.stringify({
+            jsonrpc: '2.0',
+            error: {
+              code: -32000,
+              message: `Agent Guard CLI Bridge Error: upstream returned ${response.status}`,
+            },
+            id: requestId,
+          });
+          process.stdout.write(errMessage + '\n');
+          return;
+        }
+        // Ensure the response is written to stdout as a single line
+        process.stdout.write(body.replace(/\r?\n/g, '') + '\n');
+      } catch (networkError) {
+        // Log raw error (may contain credentials) to stderr only — never stdout
+        process.stderr.write(`[guard] network error: ${networkError.message}\n`);
+        // Ensure STDIO JSON-RPC clients get a properly formatted message on failure
+        const errMessage = JSON.stringify({
+          jsonrpc: '2.0',
+          error: {
+            code: -32000,
+            message: `Agent Guard CLI Bridge Error: Could not reach gateway at ${AGENT_GUARD_SAFE_URL}`,
+          },
+          id: requestId,
+        });
+        process.stdout.write(errMessage + '\n');
+      }
+    } catch (fatalError) {
+      // Write the real error to stderr for operator visibility; never expose it to the agent.
+      process.stderr.write(`[agent-guard] fatal: ${fatalError?.message ?? fatalError}\n`);
+      const fatalMsg = JSON.stringify({
+        jsonrpc: '2.0',
+        error: { code: -32603, message: 'Internal agent guard error. Check stderr for details.' },
+        id: null,
+      });
+      process.stdout.write(fatalMsg + '\n');
+    } finally {
+      inFlight = inFlight - 1;
+    }
+  });
+}