@switchboard.spot/cli 0.2.3 → 0.2.5

package/lib/verify/index.js

@@ -48,7 +48,6 @@ const CHECK_TYPE_TO_ID = new Map([
 ]);
 
 const SERVER_SECRET_PATTERNS = [
-  { name: "SWITCHBOARD_API_KEY", pattern: /\bSWITCHBOARD_API_KEY\b/ },
   { name: "switchboard live key", pattern: /\bsb_live_[A-Za-z0-9_-]{6,}\b/ },
   { name: "switchboard test key", pattern: /\bsb_test_[A-Za-z0-9_-]{6,}\b/ },
   { name: "account session token", pattern: /\bsb_sess_[A-Za-z0-9_-]{6,}\b/ },
@@ -125,7 +124,7 @@ export async function runVerification(options = {}) {
   const scenario = validateScenario(options.scenario ?? loadScenario(options.scenarioPath));
   const report = createReport(mode);
   const artifactsDir = options.artifactsDir ?? DEFAULT_ARTIFACTS_DIR;
-  const appUrl = parseRequiredUrl(options.url, "--url");
+  const appUrl = parseRequiredUrl(options.appUrl ?? options.url, options.appUrl ? "--app-url" : "--url");
   const clientUrl = options.clientUrl ? parseRequiredUrl(options.clientUrl, "--client-url") : null;
   const timeoutMs = normalizeTimeoutMs(options.timeoutMs);
   let productionOrigin = options.productionOrigin;
@@ -194,7 +193,13 @@ export function createReport(mode) {
 }
 
 export function evaluateEvidence(report, evidence) {
-  const consoleErrors = evidence.consoleMessages.filter((message) => message.type === "error");
+  const consoleErrors = evidence.consoleMessages.filter(
+    (message) => message.type === "error" && !allowedSandboxGuardConsoleError(message, evidence),
+  );
+  const failedRequests = evidence.failedRequests.filter(
+    (request) => !allowedSandboxGuardUrls(evidence).has(request.url),
+  );
+
   addCheck(report, {
     id: CHECK_IDS.NO_CONSOLE_ERRORS,
     status: consoleErrors.length === 0 ? "passed" : "failed",
@@ -206,11 +211,11 @@ export function evaluateEvidence(report, evidence) {
 
   addCheck(report, {
     id: CHECK_IDS.NO_FAILED_REQUESTS,
-    status: evidence.failedRequests.length === 0 ? "passed" : "failed",
+    status: failedRequests.length === 0 ? "passed" : "failed",
     message:
-      evidence.failedRequests.length === 0
+      failedRequests.length === 0
         ? "No failed browser requests were observed."
-        : `${evidence.failedRequests.length} failed browser request(s) were observed.`,
+        : `${failedRequests.length} failed browser request(s) were observed.`,
   });
 
   const authLeak = browserAuthorizationFinding(evidence.requests);
@@ -456,10 +461,16 @@ async function executeScenarioCheck({
           messages: [{ role: "user", content: prompt ?? check.prompt }],
         },
       });
+      const sandboxGuarded = isSandboxCompletionGuard(result);
+      if (sandboxGuarded) evidence.allowedSandboxGuardUrls.add(result.url);
       addCheck(report, {
         id: CHECK_IDS.CHAT_COMPLETION_SUCCEEDS,
-        status: result.ok ? "passed" : "failed",
-        message: result.ok ? "Chat completion succeeded through the client gateway." : result.error,
+        status: result.ok || sandboxGuarded ? "passed" : "failed",
+        message: result.ok
+          ? "Chat completion succeeded through the client gateway."
+          : sandboxGuarded
+            ? "Sandbox chat reached the client gateway and was blocked before any real AI completion."
+            : result.error,
       });
       return;
     }
@@ -505,11 +516,12 @@ async function browserFetchJson(page, clientUrl, endpointPath, init) {
         return {
           ok: response.ok,
           status: response.status,
+          url: endpointUrl,
           data,
           error: response.ok ? null : `HTTP ${response.status}`,
         };
       } catch (error) {
-        return { ok: false, status: 0, data: null, error: error.message };
+        return { ok: false, status: 0, url: endpointUrl, data: null, error: error.message };
       }
     },
     { endpointUrl, init },
@@ -524,6 +536,32 @@ function clientEndpointUrl(clientUrl, endpointPath) {
   return url.href;
 }
 
+function isSandboxCompletionGuard(result) {
+  const error = result?.data?.error;
+
+  return (
+    result?.status === 402 &&
+    error?.type === "sandbox_completion_requires_prepaid_balance" &&
+    typeof error.message === "string" &&
+    error.message.includes("Sandbox mode does not run real AI completions") &&
+    error.message.includes("No provider was called") &&
+    error.message.includes("funded prepaid project balance") &&
+    error.message.includes("live mode")
+  );
+}
+
+function allowedSandboxGuardConsoleError(message, evidence) {
+  return (
+    allowedSandboxGuardUrls(evidence).size > 0 &&
+    /Failed to load resource/i.test(message.text ?? "") &&
+    /\b402\b/.test(message.text ?? "")
+  );
+}
+
+function allowedSandboxGuardUrls(evidence) {
+  return evidence.allowedSandboxGuardUrls ?? new Set();
+}
+
 function wireEvidence(page, evidence) {
   page.on("console", (message) => {
     evidence.consoleMessages.push({
@@ -593,6 +631,7 @@ function emptyEvidence() {
   return {
     consoleMessages: [],
     failedRequests: [],
+    allowedSandboxGuardUrls: new Set(),
     requests: [],
     responses: [],
     texts: [],
@@ -723,6 +762,7 @@ function normalizedHostname(url) {
 
 function browserChallengeTokenFor(check, clientUrl) {
   if (Object.prototype.hasOwnProperty.call(check, "browserChallengeToken")) {
+    validateBrowserChallengeToken(check.browserChallengeToken, clientUrl);
     return check.browserChallengeToken;
   }
 
@@ -730,13 +770,25 @@ function browserChallengeTokenFor(check, clientUrl) {
     return DEV_BROWSER_CHALLENGE_TOKEN;
   }
 
-  return DEFAULT_BROWSER_CHALLENGE_TOKEN;
+  throw new VerificationInputError(
+    "Hosted Switchboard verification cannot submit synthetic browser challenge tokens. Run the SDK-managed browser challenge in the real app, or target a localhost Switchboard URL for dev verification.",
+  );
 }
 
 function isLocalSwitchboardUrl(url) {
   return url instanceof URL && LOCAL_HOSTS.has(normalizedHostname(url));
 }
 
+export function validateBrowserChallengeToken(token, clientUrl) {
+  if (isLocalSwitchboardUrl(clientUrl)) return;
+
+  if (token === DEV_BROWSER_CHALLENGE_TOKEN || token === DEFAULT_BROWSER_CHALLENGE_TOKEN) {
+    throw new VerificationInputError(
+      "Synthetic browser challenge tokens are allowed only against localhost Switchboard URLs.",
+    );
+  }
+}
+
 function addFailure(report, checkId, message, finding) {
   addCheck(report, { id: checkId, status: "failed", message });
   report.findings.push({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@switchboard.spot/cli",
-  "version": "0.2.3",
-  "description": "Switchboard CLI — full dashboard parity for agents and testing",
+  "version": "0.2.5",
+  "description": "Switchboard CLI for account, project, gateway, and docs automation",
   "type": "module",
   "bin": {
     "switchboard": "bin/switchboard.js"

package/lib/commands/endUsers.js

@@ -1,51 +0,0 @@
-/**
- * End-user management commands.
- */
-
-import { accountRequest } from "../client.js";
-import { emit, globalFlags, printList } from "../output.js";
-
-export function registerEndUsersCommands(program) {
-  const endUsers = program
-    .command("end-users")
-    .description("Anonymous Client Gateway end users");
-
-  endUsers
-    .command("list")
-    .description("List end users")
-    .action(async (_opts, cmd) => {
-      const flags = globalFlags(cmd);
-      const { data } = await accountRequest("GET", "/end_users", { json: flags.json });
-      if (flags.json) {
-        emit(data, flags);
-      } else {
-        printList("End users:", data.data || [], (u) =>
-          `  ${u.id} ${u.reference} — ${u.billing_status}`,
-        );
-      }
-    });
-
-  endUsers
-    .command("block <id>")
-    .description("Block an end user")
-    .action(async (id, _opts, cmd) => {
-      const flags = globalFlags(cmd);
-      const { data } = await accountRequest("PATCH", `/end_users/${id}`, {
-        body: { billing_status: "blocked" },
-        json: flags.json,
-      });
-      emit(flags.json ? data : `Blocked ${data.reference}`, flags);
-    });
-
-  endUsers
-    .command("unblock <id>")
-    .description("Unblock an end user")
-    .action(async (id, _opts, cmd) => {
-      const flags = globalFlags(cmd);
-      const { data } = await accountRequest("PATCH", `/end_users/${id}`, {
-        body: { billing_status: "active" },
-        json: flags.json,
-      });
-      emit(flags.json ? data : `Unblocked ${data.reference}`, flags);
-    });
-}

package/lib/commands/init.js

@@ -1,78 +0,0 @@
-/**
- * Project init and agent manifest commands.
- */
-
-import fs from "fs";
-import path from "path";
-import { resolveConfig, gatewayApiUrl } from "../config.js";
-import { emit } from "../output.js";
-
-/**
- * Builds default frontend environment placeholders for Client Gateway apps.
- *
- * The generated Client Gateway URL is the only value a browser app needs by default.
- */
-function envBlock(clientUrl) {
-  return `SWITCHBOARD_CLIENT_URL=${clientUrl}
-VITE_SWITCHBOARD_CLIENT_URL=${clientUrl}
-`;
-}
-
-/**
- * Builds the agent manifest for automated setup.
- */
-export function agentManifest(config) {
-  const base = gatewayApiUrl(config);
-  const clientUrl = `${config.baseUrl.replace(/\/$/, "")}/m/<client-gateway-slug>/v1`;
-
-  return {
-    base_url: base,
-    client_url: clientUrl,
-    virtual_microservice_url: clientUrl,
-    account_api: `${config.baseUrl.replace(/\/$/, "")}/v1/account`,
-    env: envBlock(clientUrl),
-    checklist: [
-      "switchboard setup project --origin <origin> --json",
-      "export VITE_SWITCHBOARD_CLIENT_URL=<client_url from integration kit>",
-      "Use mountSwitchboardWidget({ clientUrl, target }) in browser apps",
-      "Use createSwitchboardClient({ clientUrl, storage }) only for custom UI",
-      "switchboard verify setup",
-      "switchboard launch prepare --production-origin https://app.example.com --end-user-terms-url https://app.example.com/terms --end-user-privacy-url https://app.example.com/privacy --support-email support@example.com --contact-email owner@example.com --use-case \"Browser chat for signed-in customers\"",
-      "switchboard verify publish",
-    ],
-    browser_smoke_test: `import { mountSwitchboardWidget } from "@switchboard.spot/sdk";
-
-mountSwitchboardWidget({
-  clientUrl: import.meta.env.VITE_SWITCHBOARD_CLIENT_URL ?? "${clientUrl}",
-  target: "#switchboard",
-});`,
-    automation_note:
-      "Client Gateway auth is browser/mobile only and requires a real browser challenge. Use account/CLI APIs only for project configuration automation.",
-  };
-}
-
-export function registerInitCommand(program) {
-  program
-    .command("init")
-    .description("Write .env.local with Switchboard placeholders")
-    .option("--agent", "Print agent manifest JSON")
-    .action((opts, cmd) => {
-      const flags = cmd.opts();
-      const config = resolveConfig();
-      const clientUrl = `${config.baseUrl.replace(/\/$/, "")}/m/<client-gateway-slug>/v1`;
-      const target = path.join(process.cwd(), ".env.local");
-
-      if (!fs.existsSync(target)) {
-        fs.writeFileSync(target, envBlock(clientUrl));
-        if (!flags.quiet && !flags.json) {
-          console.log(`Wrote ${target}`);
-        }
-      } else if (!flags.quiet && !flags.json) {
-        console.log(`${target} already exists`);
-      }
-
-      if (opts.agent || flags.json) {
-        emit(agentManifest(config), { json: true });
-      }
-    });
-}

package/lib/commands/integration.js

@@ -1,38 +0,0 @@
-/**
- * Integration kit command.
- */
-
-import { accountRequest } from "../client.js";
-import { emit, globalFlags } from "../output.js";
-
-export function registerIntegrationCommands(program) {
-  const integrations = program.command("integrations").description("Integration helpers");
-
-  integrations
-    .command("show")
-    .description("Fetch integration setup JSON")
-    .option("--stack <stack>", "node or python", "node")
-    .action(async (opts, cmd) => {
-      await showIntegration(opts, cmd);
-    });
-
-  const integration = program.command("integration").description("Legacy integration helpers");
-
-  integration
-    .command("kit")
-    .description("Legacy alias for integrations show")
-    .option("--stack <stack>", "node or python", "node")
-    .action(async (opts, cmd) => {
-      await showIntegration(opts, cmd);
-    });
-}
-
-async function showIntegration(opts, cmd) {
-  const flags = globalFlags(cmd);
-  const { data } = await accountRequest(
-    "GET",
-    `/integration_kit?stack=${opts.stack}`,
-    { json: flags.json },
-  );
-  emit(data, flags);
-}

package/lib/commands/keys.js

@@ -1,106 +0,0 @@
-/**
- * API key management commands.
- */
-
-import { accountRequest } from "../client.js";
-import { saveConfig } from "../config.js";
-import { emit, globalFlags, printList } from "../output.js";
-
-function saveProjectContext(data) {
-  const updates = {};
-
-  if (data.project_id != null) {
-    updates.projectId = String(data.project_id);
-  }
-
-  updates.apiKey = null;
-
-  if (Object.keys(updates).length > 0) {
-    saveConfig(updates);
-  }
-}
-
-export function registerKeysCommands(program) {
-  const keys = program.command("keys").description("Project API keys");
-
-  keys
-    .command("list")
-    .description("List API keys for the selected project")
-    .action(async (_opts, cmd) => {
-      const flags = globalFlags(cmd);
-      const { data } = await accountRequest("GET", "/keys", { json: flags.json });
-      if (flags.json) {
-        emit(data, flags);
-      } else {
-        printList("API keys:", data.data || [], (k) =>
-          `  ${k.id} ${k.mode} ${k.key_type || "secret"} ${k.name} …${k.last_four}${k.revoked_at ? " (revoked)" : ""}`,
-        );
-      }
-    });
-
-  keys
-    .command("create")
-    .description("Create a new API key")
-    .option("--mode <mode>", "sandbox or live", "sandbox")
-    .option("--name <name>", "Key label")
-    .action(async (opts, cmd) => {
-      const flags = globalFlags(cmd);
-      const body = { mode: opts.mode, name: opts.name };
-
-      const { data } = await accountRequest("POST", "/keys", {
-        body,
-        json: flags.json,
-      });
-
-      saveProjectContext(data);
-      emit(
-        flags.json
-          ? data
-          : `Created ${data.mode} key. Plaintext (shown once): ${data.plaintext}`,
-        flags,
-      );
-    });
-
-  keys
-    .command("regenerate-sandbox")
-    .description("Revoke sandbox secret keys and create a new one")
-    .action(async (_opts, cmd) => {
-      const flags = globalFlags(cmd);
-      const { data } = await accountRequest("POST", "/keys/sandbox/regenerate", {
-        json: flags.json,
-      });
-      saveProjectContext(data);
-      emit(
-        flags.json
-          ? data
-          : `New sandbox key: ${data.plaintext}`,
-        flags,
-      );
-    });
-
-  keys
-    .command("revoke <id>")
-    .description("Revoke an API key")
-    .action(async (id, _opts, cmd) => {
-      const flags = globalFlags(cmd);
-      const { data } = await accountRequest("POST", `/keys/${id}/revoke`, {
-        json: flags.json,
-      });
-      emit(flags.json ? data : `Revoked key ${id}`, flags);
-    });
-
-  keys
-    .command("rotate <id>")
-    .description("Rotate an API key")
-    .action(async (id, _opts, cmd) => {
-      const flags = globalFlags(cmd);
-      const { data } = await accountRequest("POST", `/keys/${id}/rotate`, {
-        json: flags.json,
-      });
-      saveProjectContext(data);
-      emit(
-        flags.json ? data : `Rotated key ${id}. New plaintext: ${data.plaintext}`,
-        flags,
-      );
-    });
-}

package/lib/commands/launch.js

@@ -1,213 +0,0 @@
-/**
- * Production launch orchestration commands.
- */
-
-import { accountRequest } from "../client.js";
-import { saveConfig } from "../config.js";
-import { emit, fail, globalFlags } from "../output.js";
-import { buildProductionAccessRequestBody } from "./projects.js";
-
-export function registerLaunchCommands(program) {
-  const launch = program.command("launch").description("Production launch workflows");
-
-  launch
-    .command("prepare")
-    .description("Prepare a project for production Client Gateway launch")
-    .option("--project-id <id>", "Existing project id")
-    .option("--project-name <name>", "Create a project when no project id is provided")
-    .option("--project-slug <slug>", "Slug for a project created by this command")
-    .requiredOption(
-      "--production-origin <origin>",
-      "Exact HTTPS production origin, for example https://app.example.com",
-    )
-    .requiredOption("--end-user-terms-url <url>")
-    .requiredOption("--end-user-privacy-url <url>")
-    .option("--support-url <url>")
-    .requiredOption("--support-email <email>")
-    .requiredOption("--contact-email <email>")
-    .requiredOption("--use-case <text>")
-    .option("--expected-monthly-volume <volume>")
-    .option("--needed-billing-mode <mode>", "Billing mode needed for production", "developer_paid")
-    .option("--notes <text>")
-    .option("--idempotency-key <key>")
-    .action(async (opts, cmd) => {
-      const flags = globalFlags(cmd);
-      validateLaunchOptions(opts, flags);
-
-      const project = await ensureProject(opts, flags);
-      const idempotencyKey = opts.idempotencyKey || `launch-prepare-project-${project.id}`;
-
-      const configured = await updateLaunchProject(project.id, opts, flags);
-      const challenge = await provisionManagedTurnstile(project.id, idempotencyKey, flags);
-      const access = await requestAccessIfNeeded(project.id, configured, opts, flags);
-      const readiness = await fetchProject(project.id, flags);
-
-      emit(
-        flags.json
-          ? launchSummary(readiness, challenge, access)
-          : humanLaunchSummary(readiness, access),
-        flags,
-      );
-    });
-}
-
-export function validateLaunchOptions(opts, flags) {
-  if (!productionHttpsOrigin(opts.productionOrigin)) {
-    fail("--production-origin must be an exact HTTPS production origin", 1, flags.json);
-  }
-  if ((opts.projectName && !opts.projectSlug) || (!opts.projectName && opts.projectSlug)) {
-    fail("--project-name and --project-slug must be provided together", 1, flags.json);
-  }
-}
-
-export async function ensureProject(opts, flags, { request = accountRequest, save = saveProjectConfig } = {}) {
-  if (opts.projectId) {
-    const project = await fetchProject(opts.projectId, flags, { request });
-    save(project);
-    return project;
-  }
-
-  if (opts.projectName) {
-    const { data } = await request("POST", "/projects", {
-      body: { name: opts.projectName, slug: opts.projectSlug },
-      json: flags.json,
-    });
-    save(data);
-    return data;
-  }
-
-  const { data } = await request("GET", "/me", { json: flags.json });
-  if (!data.project?.id) {
-    fail(
-      "No default project is selected. Use --project-id or --project-name with --project-slug.",
-      1,
-      flags.json,
-    );
-  }
-  save(data.project);
-  return data.project;
-}
-
-export async function updateLaunchProject(
-  projectId,
-  opts,
-  flags,
-  { request = accountRequest, save = saveProjectConfig } = {},
-) {
-  const body = {
-    allowed_origins: [opts.productionOrigin],
-    end_user_terms_url: opts.endUserTermsUrl,
-    end_user_privacy_url: opts.endUserPrivacyUrl,
-    support_email: opts.supportEmail,
-    virtual_microservice_enabled: true,
-  };
-
-  if (opts.supportUrl) body.support_url = opts.supportUrl;
-
-  const { data } = await request("PATCH", `/projects/${projectId}`, {
-    body,
-    json: flags.json,
-  });
-  save(data);
-  return data;
-}
-
-export async function provisionManagedTurnstile(
-  projectId,
-  idempotencyKey,
-  flags,
-  { request = accountRequest } = {},
-) {
-  const { data } = await request("POST", `/projects/${projectId}/turnstile/provision`, {
-    body: { idempotency_key: `${idempotencyKey}:turnstile` },
-    json: flags.json,
-  });
-  return data;
-}
-
-export async function requestAccessIfNeeded(
-  projectId,
-  project,
-  opts,
-  flags,
-  { request = accountRequest } = {},
-) {
-  if (project.production_access_status === "approved") {
-    return {
-      object: "production_access_request",
-      project_id: project.id,
-      project_production_access_status: "approved",
-      status: "approved",
-    };
-  }
-
-  const { data } = await request("POST", `/projects/${projectId}/production_access_request`, {
-    body: buildProductionAccessRequestBody(opts),
-    json: flags.json,
-  });
-  return data;
-}
-
-export async function fetchProject(projectId, flags, { request = accountRequest } = {}) {
-  const { data } = await request("GET", `/projects/${projectId}`, { json: flags.json });
-  return data;
-}
-
-export function saveProjectConfig(project) {
-  saveConfig({
-    projectId: String(project.id),
-    apiKey: null,
-    virtualMicroserviceUrl: project.virtual_microservice_url || null,
-    endUserSession: null,
-  });
-}
-
-export function launchSummary(project, challenge, access) {
-  return {
-    object: "launch_prepare_result",
-    project_id: project.id,
-    project_slug: project.slug,
-    virtual_microservice_url: project.virtual_microservice_url,
-    browser_challenge: challenge,
-    production_access: access,
-    production_safety: project.production_safety,
-    next_steps: [
-      "Run switchboard verify setup.",
-      "Use the SDK-managed browser challenge to mint browser sessions.",
-      "Run switchboard verify publish after approval and billing readiness are complete.",
-    ],
-  };
-}
-
-export function humanLaunchSummary(project, access) {
-  const blocked = (project.production_safety?.checks || [])
-    .filter((check) => check.status !== "ready")
-    .map((check) => check.id);
-
-  return [
-    `Prepared project ${project.name} (${project.id})`,
-    `Client Gateway: ${project.virtual_microservice_url}`,
-    `Production access: ${access.project_production_access_status || access.status}`,
-    `Readiness: ${project.production_safety?.status || "unknown"}`,
-    blocked.length ? `Blocked checks: ${blocked.join(", ")}` : "Blocked checks: none",
-    "Next: run switchboard verify setup, then switchboard verify publish after approval and billing readiness.",
-  ].join("\n");
-}
-
-export function productionHttpsOrigin(origin) {
-  try {
-    const url = new URL(origin);
-    return (
-      url.protocol === "https:" &&
-      url.username === "" &&
-      url.password === "" &&
-      url.pathname === "/" &&
-      url.search === "" &&
-      url.hash === "" &&
-      !["localhost", "127.0.0.1", "::1"].includes(url.hostname) &&
-      !url.hostname.includes("*")
-    );
-  } catch {
-    return false;
-  }
-}