@sphyr/cli 2.0.0-beta.1

package/src/commands/init.js

@@ -0,0 +1,484 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sphyr
+
+/**
+ * init.js — sphyr CLI init using RFC 8628 Device Authorization Grant.
+ *
+ * Flow (D-02 order — read BEFORE auth):
+ *   1. Detect installed IDE clients, multiselect
+ *   2. Read each selected IDE's mcpServers config (selectAndPrepareIdes)
+ *   3. Preview what will be wrapped; D-02 early-exit if nothing to wrap
+ *   4. POST /v1/device_auth to obtain device_code, user_code, verification_uri
+ *   5. Display user_code and verification_uri; best-effort open browser (TTY only)
+ *   6. Poll /v1/device_auth/token until approved, expired, or denied
+ *   7. Write a single sphyr entry per IDE via replaceWithGuardEntry (configureIdeClients)
+ *
+ * Security: Credentials are delivered in a JSON POST response body — never in
+ * URL query parameters. RFC 8252 §8.2 prohibits credentials in URI query
+ * components (browser history exposure). RFC 8628 device flow is the only
+ * supported authentication method.
+ *
+ * The loopback OAuth flow has been removed. It delivered api_key and
+ * hmac_secret as URL query parameters, violating RFC 8252 §8.2. Device flow
+ * works in all environments including headless/CI/SSH.
+ *
+ * Threat mitigations (T-128-05 through T-128-09):
+ *   T-128-05: D-09 parseDownstreamConfig rejects path-traversal/null bytes (skip-and-warn)
+ *   T-128-06: JSON.stringify(validated) is the only SPHYR_DOWNSTREAM path (no concatenation)
+ *   T-128-07: isSphyrEntry in selectAndPrepareIdes filters circular-wrap candidates
+ *   T-128-08: selectAndPrepareIdes has NO file-write side effects; writes gated by auth
+ *   T-128-09: readMcpServersForIde D-01 merge; wrappedKeys algorithm prevents delete-of-nonexistent
+ */
+
+import * as p from '@clack/prompts';
+import open from 'open';
+import fs from 'node:fs';
+import { IDE_CLIENTS, detectInstalledClients, isSphyrEntry, readMcpServersForIde, replaceWithGuardEntry, buildServerEntry } from '../lib/ide-clients.js';
+import { parseDownstreamConfig } from '@sphyr/sdk/guard-config';
+import { requireTrustedEndpoint } from '../lib/url-guard.js';
+
+const DEFAULT_API_BASE = 'https://api.sphyr.io';
+// W-10: the device flow sends/receives the credential against this base —
+// validate at module load so a poisoned env var fails loudly before any
+// network or prompt activity.
+const API_BASE = requireTrustedEndpoint(process.env.SPHYR_API_URL || DEFAULT_API_BASE, 'SPHYR_API_URL', DEFAULT_API_BASE);
+
+const BANNER = `
+  ███████╗██████╗ ██╗  ██╗██╗   ██╗██████╗
+  ██╔════╝██╔══██╗██║  ██║╚██╗ ██╔╝██╔══██╗
+  ███████╗██████╔╝███████║ ╚████╔╝ ██████╔╝
+  ╚════██║██╔═══╝ ██╔══██║  ╚██╔╝  ██╔══██╗
+  ███████║██║     ██║  ██║   ██║   ██║  ██║
+  ╚══════╝╚═╝     ╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝
+  Agent Guard — signs every MCP request automatically
+`;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * RFC 8628 §3.5 polling endpoint client (with RFC 6585 §4 transport-layer rate-limit handling).
+ * polling at base interval, +5s on slow_down. HTTP 429 sleeps for Retry-After seconds without
+ *       changing the protocol-layer interval state (per-IP rate limits are transport-layer; the
+ *       per-device_code interval is protocol-layer; they are semantically distinct).
+ *
+ * @param {object} opts
+ * @param {string} opts.tokenUrl  - Full URL for the token polling endpoint
+ * @param {string} opts.deviceCode - Device code received from the device authorization endpoint
+ * @param {number} [opts.interval=5] - Initial polling interval in seconds (RFC 8628 §3.5)
+ * @param {number} [opts.expiresIn=900] - Device code expiry in seconds (used as deadline)
+ * @returns {Promise<{credential: string}>}
+ *
+ * Implementation note: The returned promise has a pre-attached no-op .catch() to prevent
+ * Node.js unhandled-rejection warnings in tests where the rejection is handled after a
+ * vi.advanceTimersByTimeAsync() call. The caller's own
+ * .catch()/.rejects handler still receives the rejection normally.
+ */
+export function pollForToken({ tokenUrl, deviceCode, interval = 5, expiresIn = 900 }) {
+  const promise = (async () => {
+    const deadline = Date.now() + expiresIn * 1000;
+    let currentInterval = interval;
+
+    while (Date.now() < deadline) {
+      const res = await fetch(tokenUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ device_code: deviceCode }),
+      });
+
+      // RFC 6585 §4 transport-layer rate limit: per-IP throttling from the server.
+      // Distinct from RFC 8628 slow_down (which is per-device_code protocol pacing).
+      // The CLI sleeps for the server-specified Retry-After duration and retries
+      // WITHOUT altering its per-device_code interval state. NAT/VPN-collateral clients
+      // get a clear transport-level retry signal rather than a protocol-pacing signal
+      // that wouldn't help (the IP-level limit doesn't ease as the CLI's per-device_code
+      // interval grows).
+      if (res.status === 429) {
+        const retryAfterHeader = res.headers.get('Retry-After');
+        const retryAfterSec = retryAfterHeader ? parseInt(retryAfterHeader, 10) : 60;
+        const sleepMs =
+          Number.isFinite(retryAfterSec) && retryAfterSec > 0
+            ? Math.min(retryAfterSec * 1000, 60_000)
+            : 60_000;
+        await sleep(sleepMs);
+        continue; // interval unchanged — this is transport-layer, not protocol-layer
+      }
+
+      const body = await res.json();
+      if (res.ok) {
+        return body; // { credential }
+      }
+      if (body.error === 'slow_down') {
+        currentInterval += 5;
+        await sleep(currentInterval * 1000);
+        continue;
+      }
+      if (body.error === 'authorization_pending') {
+        await sleep(currentInterval * 1000);
+        continue;
+      }
+      if (body.error === 'expired_token') {
+        throw new Error('expired');
+      }
+      if (body.error === 'access_denied') {
+        throw new Error('denied');
+      }
+      throw new Error(`Device flow error: ${body.error ?? 'unknown'}`);
+    }
+    throw new Error('timeout');
+  })();
+
+  // Pre-attach no-op .catch() so the promise is never "unhandled" when rejection occurs
+  // between creation and the caller's await/catch.
+  promise.catch(() => {});
+  return promise;
+}
+
+/**
+ * Phase 1 of runInit: detect IDE clients, multiselect, read each IDE's mcpServers,
+ * run D-09 pre-validation retry loop, compute wrappedKeys, emit preview lines,
+ * and apply D-02 early-exit predicate.
+ *
+ * Returns a Map<clientId, { client, readResult, validated, wrappedKeys, rawEntryCount }>
+ * if init should proceed to auth, or null if D-02 early-exit fired.
+ *
+ * NO FILE WRITES — T-128-08: all writes are gated by auth; this phase is read-only.
+ *
+ * @returns {Promise<Map<string, object>|null>}
+ */
+// eslint-disable-next-line max-lines-per-function -- D-02 prepare phase: detect → multiselect → read → D-09 retry → preview → early-exit; sequential invariants break if split
+export async function selectAndPrepareIdes() {
+  // Step 1: Detect installed clients and multiselect
+  const detected = detectInstalledClients();
+  const availableClients = IDE_CLIENTS.filter((c) => c.configPath() !== null);
+
+  if (availableClients.length === 0) {
+    p.log.warn('No supported IDE clients detected on this system.');
+    p.outro('Run sphyr init again after installing an IDE client.');
+    return null;
+  }
+
+  const options = availableClients.map((c) => ({
+    value: c.id,
+    label: c.name,
+    hint: detected.has(c.id) ? 'detected' : 'not detected',
+  }));
+  const initialValues = availableClients.filter((c) => detected.has(c.id)).map((c) => c.id);
+
+  const selected = await p.multiselect({
+    message: 'Select IDE clients to configure:',
+    options,
+    initialValues,
+    required: false,
+  });
+  if (p.isCancel(selected)) {
+    p.cancel('Cancelled.');
+    process.exit(0);
+  }
+
+  if (selected.length === 0) {
+    p.log.info('No clients selected. Skipping config writing.');
+    p.outro('Run sphyr init again when ready.');
+    return null;
+  }
+
+  // Step 2: Read each IDE's mcpServers and build ideReadResults Map
+  /** @type {Map<string, { client: object, readResult: object, validated: object[], wrappedKeys: string[], rawEntryCount: number }>} */
+  const ideReadResults = new Map();
+
+  for (const clientId of selected) {
+    const client = IDE_CLIENTS.find((c) => c.id === clientId);
+    if (!client) continue;
+
+    // Read the raw config to compute rawEntryCount for D-02 predicate
+    const configPath = client.configPath();
+    let rawMcpServers = {};
+    if (configPath) {
+      try {
+        if (fs.existsSync(configPath)) {
+          const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+          if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+            rawMcpServers = raw[client.topLevelKey] || {};
+          }
+        }
+      } catch {
+        // Non-fatal — rawMcpServers stays {}; readMcpServersForIde will emit a warning
+      }
+    }
+    const rawEntryCount = Object.keys(rawMcpServers).length;
+
+    // Call readMcpServersForIde which performs D-01 merge inside (Plan 01).
+    // readResult.all is the D-01 merged set — already performed inside readMcpServersForIde
+    // (Plan 01); existingWrapped + newIndividual combined, new wins on name collision.
+    const readResult = readMcpServersForIde(client);
+
+    // Surface warnings from readMcpServersForIde (e.g., malformed existing SPHYR_DOWNSTREAM)
+    for (const warning of readResult.warnings) {
+      p.log.warn(warning);
+    }
+
+    // D-04 exclusion logging: emit per-entry warn for any raw mcpServers key that was
+    // excluded by isSphyrEntry. These are the "circular wrapping" entries.
+    for (const [key, entry] of Object.entries(rawMcpServers)) {
+      if (isSphyrEntry(key, entry)) {
+        p.log.warn(`[sphyr-guard-init] Skipping '${key}' — would create circular wrapping.`);
+      }
+    }
+
+    // D-09 retry loop: call parseDownstreamConfig; on field-level error, splice out the
+    // failing entry by index and retry until clean or empty.
+    let candidates = [...readResult.all]; // copy to avoid mutating readResult.all
+    let validated = [];
+    // eslint-disable-next-line no-constant-condition -- exit via break
+    while (true) {
+      if (candidates.length === 0) {
+        validated = [];
+        break;
+      }
+      try {
+        validated = parseDownstreamConfig(JSON.stringify(candidates));
+        break; // success
+      } catch (err) {
+        // Try to extract the failing entry index from the error message
+        const match = err.message.match(/SPHYR_DOWNSTREAM\[(\d+)\]/);
+        if (!match) {
+          // Unexpected error shape (e.g., "must contain at most 50 server configs") — rethrow
+          throw err;
+        }
+        const idx = parseInt(match[1], 10);
+        p.log.warn(`[sphyr-guard-init] Skipping invalid entry: ${err.message}`);
+        candidates.splice(idx, 1);
+      }
+    }
+
+    // Compute wrappedKeys: original mcpServers keys whose mapped DownstreamServerConfig
+    // entry appears in `validated` by name.
+    // wrappedKeys = original mcpServers keys whose mapped DownstreamServerConfig entry
+    // appears in `validated` by name. Used by replaceWithGuardEntry to know which entries to delete.
+    // Re-run entries that were previously only in legacy SPHYR_DOWNSTREAM (not in current mcpServers)
+    // are NOT in wrappedKeys — they don't need to be deleted from mcpServers (they never lived there).
+    const wrappedKeys = Object.entries(rawMcpServers)
+      .filter(([key, entry]) => !isSphyrEntry(key, entry))
+      .map(([key]) => key)
+      .filter((key) => validated.some((v) => v.name === key));
+
+    ideReadResults.set(clientId, { client, readResult, validated, wrappedKeys, rawEntryCount });
+  }
+
+  // Step 3: Emit preview lines per IDE
+  for (const { client, readResult, validated } of ideReadResults.values()) {
+    if (validated.length > 0) {
+      // Distinguish existing vs new entries (D-01 preview per CONTEXT.md D-02)
+      const existingNames = new Set(readResult.existingWrapped.map((e) => e.name));
+      const parts = validated.map((v) => `${v.name} (${existingNames.has(v.name) ? 'existing' : 'new'})`);
+      p.log.info(`[sphyr-guard-init] ${client.name}: will wrap ${parts.join(', ')}`);
+    } else {
+      // D-03 per-IDE note: empty config proceeds to auth with SPHYR_DOWNSTREAM=[]
+      p.log.info(
+        `[sphyr-guard-init] No downstream servers found in ${client.name} — sphyr configured without downstreams. Add servers to SPHYR_DOWNSTREAM to wrap them later.`,
+      );
+    }
+  }
+
+  // Step 4: D-02 early-exit predicate
+  // Reconciled with D-03 (Cursor review MEDIUM):
+  //   allEmpty && anyHadRawEntries  → circular-wrap case; exit early (all entries got sphyr-filtered)
+  //   allEmpty && !anyHadRawEntries → fresh-install case (D-03); proceed to auth with SPHYR_DOWNSTREAM=[]
+  //   !allEmpty                     → some IDEs have wrappable servers; proceed normally
+  const allEmpty = [...ideReadResults.values()].every((r) => r.validated.length === 0);
+  const anyHadRawEntries = [...ideReadResults.values()].some((r) => r.rawEntryCount > 0);
+
+  if (allEmpty && anyHadRawEntries) {
+    p.log.warn(
+      '[sphyr-guard-init] No wrappable servers found in any selected IDE (existing entries were all sphyr-prefixed or invalid). Add servers to your MCP config and re-run.',
+    );
+    p.outro('Nothing to configure.');
+    return null;
+  }
+
+  // Return map for auth + write phases (fresh-install case also returns here per D-03)
+  return ideReadResults;
+}
+
+/**
+ * Write sphyr-guard entries for each IDE using the pre-computed read results.
+ * Accepts ideReadResults from selectAndPrepareIdes() — performs WRITES ONLY.
+ *
+ * @param {object} credentials - { credential } from runDeviceFlow
+ * @param {Map<string, { client: object, validated: object[], wrappedKeys: string[] }>} ideReadResults
+ */
+export async function configureIdeClients(credentials, ideReadResults) {
+  const { credential } = credentials;
+
+  const results = [];
+  for (const ideData of ideReadResults.values()) {
+    const { client, validated, wrappedKeys } = ideData;
+    const configPath = client.configPath();
+    if (!configPath) continue;
+
+    const downstreamJson = JSON.stringify(validated);
+    const entry = buildServerEntry(client, credential, downstreamJson);
+
+    try {
+      replaceWithGuardEntry(configPath, client.topLevelKey, entry, wrappedKeys);
+      results.push({ client: client.name, path: configPath, status: 'written' });
+    } catch (err) {
+      results.push({ client: client.name, path: configPath, status: 'failed', error: err.message });
+    }
+  }
+
+  // Per-client summary
+  const writtenCount = results.filter((r) => r.status === 'written').length;
+  const failedCount = results.filter((r) => r.status === 'failed').length;
+
+  for (const r of results) {
+    if (r.status === 'written') {
+      p.log.success(`${r.client} configured`);
+    } else {
+      p.log.error(`${r.client}: ${r.error}`);
+    }
+  }
+
+  if (writtenCount > 0) {
+    p.outro(
+      [
+        `Sphyr is active — every MCP request will be signed automatically.`,
+        ``,
+        `  Next: restart your IDE client${writtenCount > 1 ? 's' : ''} to activate.`,
+        `  Re-run sphyr init to add IDE clients or rotate your API key.`,
+        `  Manage usage and billing → console.sphyr.io`,
+      ].join('\n'),
+    );
+  } else {
+    p.outro(
+      failedCount > 0
+        ? `Setup failed for all clients. Re-run sphyr init to try again.`
+        : `No clients configured. Re-run sphyr init when ready.`,
+    );
+  }
+}
+
+/**
+ * RFC 8628 Device Authorization Grant — CLI side.
+ * The only supported auth method for `sphyr init`.
+ *
+ * Internal function called by runInit AFTER selectAndPrepareIdes().
+ * Returns credentials { credential } on success; process.exit(1) on failure.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.apiBase] - API base URL override (for testing)
+ * @returns {Promise<{credential: string}>}
+ *
+ * Implementation note: The returned promise has a pre-attached no-op .catch() to prevent
+ * unhandled-rejection warnings in tests where cleanup (.catch) is attached asynchronously
+ * after the promise may have already settled.
+ */
+export function runDeviceFlow({ apiBase } = {}) {
+  const promise = (async () => {
+    const effectiveApiBase = apiBase || API_BASE;
+
+    process.stdout.write(BANNER + '\n');
+    p.intro('Device authorization — sign in on a separate device');
+
+    // Step 1: initiate
+    let initBody;
+    try {
+      const res = await fetch(`${effectiveApiBase}/v1/device_auth`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({}),
+      });
+      if (!res.ok) {
+        p.log.error(`Failed to initiate device flow: HTTP ${res.status}`);
+        process.exit(1);
+      }
+      initBody = await res.json();
+    } catch (err) {
+      p.log.error(`Network error: ${err.message}`);
+      process.exit(1);
+    }
+
+    const { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval } = initBody;
+
+    // Per D-01: prefer verification_uri_complete (pre-filled user_code) when provided.
+    // Fall back to verification_uri so the user_code display line remains the headless fallback.
+    const urlToOpen = verification_uri_complete ?? verification_uri;
+
+    // Step 2: display code + URL BEFORE entering poll loop (RESEARCH anti-pattern guard)
+    p.log.message(`  Authorization code: ${user_code}`, { symbol: '◆' });
+    p.log.step(`Open: ${urlToOpen}`);
+
+    // Step 3: best-effort browser launch (only if TTY — headless environments have no DISPLAY)
+    if (process.stdout.isTTY) {
+      try {
+        await open(urlToOpen);
+      } catch {
+        // Silent — the URL is already displayed for manual navigation
+      }
+    }
+
+    // Step 4: poll
+    const s = p.spinner();
+    s.start('Waiting for authorization (15 min timeout)...');
+    let credentials;
+    try {
+      credentials = await pollForToken({
+        tokenUrl: `${effectiveApiBase}/v1/device_auth/token`,
+        deviceCode: device_code,
+        interval: interval || 5,
+        expiresIn: expires_in || 900,
+      });
+    } catch (err) {
+      s.stop('Authorization failed.');
+      if (err.message === 'expired') {
+        p.log.error('Authorization timed out. Run `sphyr init` again to retry.');
+      } else if (err.message === 'denied') {
+        p.log.error('Authorization was denied.');
+      } else if (err.message === 'timeout') {
+        p.log.error('Authorization timed out (15 minutes). Run `sphyr init` again to retry.');
+      } else {
+        p.log.error(`Device flow error: ${err.message}`);
+      }
+      process.exit(1);
+    }
+    s.stop('Authorized.');
+
+    return credentials;
+  })();
+
+  // Pre-attach no-op .catch() so the promise is never "unhandled" when rejection occurs
+  // between creation and the caller's await/catch.
+  promise.catch(() => {});
+  return promise;
+}
+
+export async function runInit() {
+  // --loopback is no longer a supported flow. Emit a deprecation warning and
+  // fall through to device flow. The loopback flow stored credentials in URL
+  // query parameters (?api_key=&hmac_secret=), violating RFC 8252 §8.2.
+  if (process.argv.includes('--loopback')) {
+    p.log.warn(
+      'The --loopback flag is deprecated and has been removed. ' +
+        'Device authorization (RFC 8628) is now the only supported auth method for `sphyr init`. ' +
+        'Continuing with device flow...',
+    );
+  }
+
+  // D-02 flow order: read-before-auth (STRUCTURAL REQUIREMENT)
+  // Step 1: Read IDE configs, preview, early-exit if nothing wrappable
+  const ideReadResults = await selectAndPrepareIdes();
+
+  // D-02 early-exit: selectAndPrepareIdes returns null when all IDEs are empty
+  // AND at least one had raw entries (all-sphyr-filtered or all-invalid case).
+  // If null, we exit before auth begins — no device flow initiated.
+  if (ideReadResults === null) {
+    return;
+  }
+
+  // Step 2: Auth (runs AFTER read phase per D-02)
+  const credentials = await runDeviceFlow();
+
+  // Step 3: Write IDE configs using pre-computed read results
+  await configureIdeClients(credentials, ideReadResults);
+}

package/src/commands/login.js

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sphyr
+
+/**
+ * login.js — `sphyr login`
+ *
+ * Authenticates via the RFC 8628 device flow (reusing runDeviceFlow from init.js) and
+ * writes the resulting credentials to ~/.sphyr/config.json with 0600 permissions.
+ *
+ * The SDKs (SphyrClient / auto_instrument / autoInstrument) auto-load this file when no
+ * constructor args and no SPHYR_* env vars are present — so `sphyr login` plus one
+ * line of code is the whole setup, with zero manual copy-paste of secrets.
+ *
+ * Security: the file holds the credential (sphyr_v1_<keyId>.<signingSecret>), so the
+ * directory is created 0700 and the file written 0600 (chmod re-applied in case the file
+ * pre-existed with looser perms).
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import * as p from '@clack/prompts';
+import { runDeviceFlow } from './init.js';
+import { requireTrustedEndpoint } from '../lib/url-guard.js';
+
+const DEFAULT_MCP_URL = 'https://api.sphyr.io/mcp';
+
+export async function runLogin() {
+  // Honor HOME/USERPROFILE before the passwd DB so the write location matches where the
+  // SDK reads (and respects an explicit HOME override).
+  const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  const dir = path.join(home, '.sphyr');
+  const configPath = path.join(dir, 'config.json');
+
+  // REVIEWS Finding 7: detect legacy { api_key, hmac_secret } config and surface a clear
+  // re-auth migration message. The old two-secret format cannot be losslessly converted to
+  // a sphyr_v1_<keyId>.<signingSecret> credential (the signing-secret derivation is
+  // server-side), so re-authentication is required. A silent shim is not feasible without
+  // a server round-trip — the detection + message is the correct UX.
+  // We do NOT crash and do NOT delete the old config; the device flow will overwrite it.
+  try {
+    if (fs.existsSync(configPath)) {
+      const existing = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      if (
+        typeof existing.api_key === 'string' && existing.api_key.length > 0 &&
+        typeof existing.hmac_secret === 'string' && existing.hmac_secret.length > 0 &&
+        !existing.credential
+      ) {
+        p.log.warn(
+          'Your ~/.sphyr/config.json uses the old two-secret format. ' +
+            'Run `sphyr login` to re-authenticate with the new single-credential format.',
+        );
+      }
+    }
+  } catch {
+    // If we cannot read/parse the existing config, proceed silently — login will overwrite it.
+  }
+
+  const credentials = await runDeviceFlow();
+  const { credential } = credentials;
+
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const payload = {
+    credential,
+    // W-10: validated before persisting — this value is auto-loaded by the SDK
+    // for all future credentialed traffic, so an http:// or attacker-host
+    // override must fail loudly here, not silently survive into config.json.
+    mcp_url: requireTrustedEndpoint(process.env.SPHYR_MCP_URL || DEFAULT_MCP_URL, 'SPHYR_MCP_URL', DEFAULT_MCP_URL),
+  };
+  fs.writeFileSync(configPath, JSON.stringify(payload, null, 2) + '\n', { mode: 0o600 });
+  // writeFileSync's `mode` is ignored when the file already exists on some platforms —
+  // re-apply 0600 explicitly so a pre-existing looser-permission file is tightened.
+  try {
+    fs.chmodSync(configPath, 0o600);
+  } catch {
+    /* best-effort — non-POSIX filesystems may not support chmod */
+  }
+
+  p.log.success(`Credentials saved to ${configPath} (0600).`);
+  p.outro(
+    [
+      'You are signed in. The SDK picks these up automatically — no keys to copy:',
+      '',
+      '  Python:  from sphyr_sdk import auto_instrument; auto_instrument()',
+      '  Node:    import { autoInstrument } from "@sphyr/sdk"; autoInstrument()',
+      '',
+      'auto_instrument() reads ~/.sphyr/config.json when no arguments or SPHYR_* env',
+      'vars are set. Manage usage and billing → console.sphyr.io',
+    ].join('\n'),
+  );
+}

package/src/commands/verify.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Sphyr
+
+/**
+ * sphyr guard verify
+ *
+ * Delegates to the SDK's sphyr-mcp verify subcommand via a version-pinned npx
+ * invocation, inheriting stdio and propagating the exit code.
+ *
+ * Using the SDK's verify (not a reimplementation) ensures a single source of
+ * truth for the credential-resolution → handshake → agent_guard_up probe logic.
+ * The SDK version is pinned using the same SDK_VERSION value that buildServerEntry
+ * in ide-clients.js uses for generated IDE configs (D-17 supply-chain requirement).
+ */
+
+import { spawn } from 'node:child_process';
+import { SDK_VERSION } from '../lib/ide-clients.js';
+
+export function runVerify() {
+  const child = spawn(
+    'npx',
+    ['-y', '-p', `@sphyr/sdk@${SDK_VERSION}`, 'sphyr-mcp', 'verify', ...process.argv.slice(3)],
+    { stdio: 'inherit' },
+  );
+
+  child.on('error', (err) => {
+    process.stderr.write(`sphyr guard verify: failed to start — ${err.message}\n`);
+    process.exit(1);
+  });
+
+  child.on('close', (code) => {
+    process.exit(code ?? 1);
+  });
+}