@vellumai/assistant 0.6.2 → 0.6.4

package/src/__tests__/host-browser-e2e-self-hosted-capability.test.ts

@@ -0,0 +1,286 @@
+/**
+ * End-to-end smoke test for the self-hosted **capability-token**
+ * WebSocket round-trip over `/v1/browser-relay`.
+ *
+ * This file is the Phase 3 complement to `host-browser-e2e-cloud.test.ts`:
+ * it exercises the same mock-chrome-extension → runtime → HostBrowserProxy
+ * path, but the extension authenticates with a capability token minted
+ * by `mintHostBrowserCapability()` instead of a guardian-bound JWT.
+ *
+ * Invariants covered:
+ *
+ *   1. `/v1/browser-relay` accepts capability tokens directly.
+ *   2. The WS upgrade handler derives the registry-key guardianId from
+ *      the capability claims so host_browser_request frames route
+ *      back to the right connection.
+ *   3. A full `Browser.getVersion` request round-trips through the
+ *      mock fixture and resolves on the proxy side.
+ *
+ * If this test fails, the self-hosted transport cutover is broken.
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ── Module mocks (must be declared before the real imports below) ────
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+mock.module("../config/loader.js", () => ({
+  getConfig: () => ({
+    ui: {},
+    model: "test",
+    provider: "test",
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0 },
+    secretDetection: { enabled: false },
+    contextWindow: { maxInputTokens: 200000 },
+    services: {
+      inference: {
+        mode: "your-own",
+        provider: "anthropic",
+        model: "claude-opus-4-6",
+      },
+      "image-generation": {
+        mode: "your-own",
+        provider: "gemini",
+        model: "gemini-3.1-flash-image-preview",
+      },
+      "web-search": { mode: "your-own", provider: "inference-provider-native" },
+    },
+  }),
+}));
+
+// ── Real imports (after mocks) ──────────────────────────────────────
+
+import type { Conversation } from "../daemon/conversation.js";
+import { HostBrowserProxy } from "../daemon/host-browser-proxy.js";
+import type { ServerMessage } from "../daemon/message-protocol.js";
+import { getDb, initializeDb } from "../memory/db.js";
+import { mintHostBrowserCapability } from "../runtime/capability-tokens.js";
+import {
+  __resetChromeExtensionRegistryForTests,
+  getChromeExtensionRegistry,
+} from "../runtime/chrome-extension-registry.js";
+import { RuntimeHttpServer } from "../runtime/http-server.js";
+import * as pendingInteractions from "../runtime/pending-interactions.js";
+
+initializeDb();
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Wrap a HostBrowserProxy in a sendToClient that routes
+ * host_browser_request / host_browser_cancel frames through the
+ * ChromeExtensionRegistry for the given guardianId, and registers the
+ * corresponding pending interaction so `/v1/host-browser-result` can
+ * resolve it back through the proxy. Mirrors the cloud e2e test's
+ * `createBoundProxy` helper.
+ */
+function createBoundProxy(
+  guardianId: string,
+  conversationId: string,
+): { proxy: HostBrowserProxy; conversation: Conversation } {
+  let proxyRef: HostBrowserProxy | null = null;
+  const conversation = {
+    resolveHostBrowser(
+      requestId: string,
+      response: { content: string; isError: boolean },
+    ) {
+      proxyRef?.resolve(requestId, response);
+    },
+  } as unknown as Conversation;
+
+  const sendToClient = (msg: ServerMessage) => {
+    if ((msg as { type: string }).type === "host_browser_request") {
+      const requestId = (msg as { requestId: string }).requestId;
+      pendingInteractions.register(requestId, {
+        conversation,
+        conversationId,
+        kind: "host_browser",
+      });
+    }
+    const ok = getChromeExtensionRegistry().send(guardianId, msg);
+    if (!ok) {
+      throw new Error(
+        `chrome-extension host_browser send failed: no active connection for guardian ${guardianId}`,
+      );
+    }
+  };
+
+  const proxy = new HostBrowserProxy(sendToClient);
+  proxyRef = proxy;
+  return { proxy, conversation };
+}
+
+// ── Tests ───────────────────────────────────────────────────────────
+
+describe("host_browser self-hosted capability-token e2e round-trip", () => {
+  let server: RuntimeHttpServer;
+  let port: number;
+  let runtimeBaseUrl: string;
+
+  beforeEach(async () => {
+    // Each test gets a clean DB and a fresh registry so connection
+    // state doesn't leak between cases.
+    const db = getDb();
+    db.run("DELETE FROM contact_channels");
+    db.run("DELETE FROM contacts");
+    pendingInteractions.clear();
+    __resetChromeExtensionRegistryForTests();
+
+    port = 19600 + Math.floor(Math.random() * 200);
+    runtimeBaseUrl = `http://127.0.0.1:${port}`;
+    server = new RuntimeHttpServer({ port });
+    await server.start();
+  });
+
+  afterEach(async () => {
+    await server?.stop();
+    pendingInteractions.clear();
+    __resetChromeExtensionRegistryForTests();
+  });
+
+  test("capability token round-trips Browser.getVersion over WS result transport", async () => {
+    const guardianId = `self-hosted-guardian-${crypto.randomUUID()}`;
+
+    // Mint the capability token the chrome extension would have
+    // received from the native messaging pair flow. No JWT is minted
+    // anywhere in this test — the `/v1/browser-relay` upgrade handler
+    // must accept this token directly.
+    const { token } = mintHostBrowserCapability(guardianId);
+
+    const { createMockChromeExtension } =
+      await import("./fixtures/mock-chrome-extension.js");
+    // WS result transport: the extension returns results over the same
+    // `/v1/browser-relay` WebSocket it received the request on. This
+    // is the canonical self-hosted return path when the socket is
+    // healthy.
+    const mockExt = createMockChromeExtension({
+      runtimeBaseUrl,
+      token,
+      resultTransport: "ws",
+    });
+    await mockExt.start();
+    await mockExt.waitForConnection();
+
+    // Give the open handler a tick to register the connection in the
+    // ChromeExtensionRegistry. If the capability-token branch of the
+    // upgrade handler is broken, waitForRegistryEntry() will throw
+    // before the Browser.getVersion call runs.
+    await waitForRegistryEntry(guardianId);
+
+    const { proxy } = createBoundProxy(guardianId, "conv-cap-happy-ws");
+
+    const result = await proxy.request(
+      { cdpMethod: "Browser.getVersion" },
+      "conv-cap-happy-ws",
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("Chrome/MockTest");
+
+    const received = mockExt.receivedRequests();
+    expect(received).toHaveLength(1);
+    expect(received[0].cdpMethod).toBe("Browser.getVersion");
+    expect(received[0].conversationId).toBe("conv-cap-happy-ws");
+
+    proxy.dispose();
+    await mockExt.stop();
+  });
+
+  test("capability token round-trips Browser.getVersion over HTTP POST fallback", async () => {
+    // HTTP result transport: the extension POSTs results back to
+    // `/v1/host-browser-result` with the same capability token used
+    // for the WS handshake. This exercises the capability-token-aware
+    // auth on the POST route and proves the HTTP fallback path
+    // resolves the pending interaction end-to-end.
+    const guardianId = `self-hosted-guardian-${crypto.randomUUID()}`;
+    const { token } = mintHostBrowserCapability(guardianId);
+
+    const { createMockChromeExtension } =
+      await import("./fixtures/mock-chrome-extension.js");
+    const mockExt = createMockChromeExtension({
+      runtimeBaseUrl,
+      token,
+      resultTransport: "http",
+    });
+    await mockExt.start();
+    await mockExt.waitForConnection();
+    await waitForRegistryEntry(guardianId);
+
+    const { proxy } = createBoundProxy(guardianId, "conv-cap-happy-http");
+
+    const result = await proxy.request(
+      { cdpMethod: "Browser.getVersion" },
+      "conv-cap-happy-http",
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("Chrome/MockTest");
+
+    const received = mockExt.receivedRequests();
+    expect(received).toHaveLength(1);
+    expect(received[0].cdpMethod).toBe("Browser.getVersion");
+    expect(received[0].conversationId).toBe("conv-cap-happy-http");
+
+    proxy.dispose();
+    await mockExt.stop();
+  });
+
+  test("an invalid capability token is rejected with 401", async () => {
+    // Sanity check: the capability branch must not be a rubber stamp
+    // — a malformed token should still 401 the upgrade. If this ever
+    // starts passing on a junk token the self-hosted security
+    // posture has regressed.
+    const { createMockChromeExtension } =
+      await import("./fixtures/mock-chrome-extension.js");
+    const mockExt = createMockChromeExtension({
+      runtimeBaseUrl,
+      token: "not-a-real-token.xxxxxxxxxxxxx",
+    });
+    await mockExt.start();
+    // The upgrade will fail; waitForConnection will time out. We
+    // intentionally give it a short window and swallow the timeout.
+    let connected = false;
+    try {
+      await mockExt.waitForConnection(500);
+      connected = true;
+    } catch {
+      // expected
+    }
+    expect(connected).toBe(false);
+    await mockExt.stop();
+  });
+});
+
+// ── Local wait helpers ──────────────────────────────────────────────
+
+async function waitFor(
+  predicate: () => boolean,
+  timeoutMs = 2000,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() > deadline) {
+      throw new Error(
+        `waitFor: predicate did not become true within ${timeoutMs}ms`,
+      );
+    }
+    await new Promise((r) => setTimeout(r, 10));
+  }
+}
+
+async function waitForRegistryEntry(
+  guardianId: string,
+  timeoutMs = 2000,
+): Promise<void> {
+  await waitFor(
+    () => getChromeExtensionRegistry().get(guardianId) !== undefined,
+    timeoutMs,
+  );
+}

package/src/__tests__/host-browser-e2e-self-hosted.test.ts

@@ -0,0 +1,374 @@
+/**
+ * End-to-end smoke test for the self-hosted native-messaging capability
+ * bootstrap path.
+ *
+ * This test exercises the full flow at the subprocess boundary:
+ *
+ *   1. A minimal Bun HTTP server mounts the real
+ *      `handleBrowserExtensionPair` route from the assistant runtime.
+ *   2. The compiled native helper binary
+ *      (`clients/chrome-extension/native-host/dist/index.js`) is spawned as
+ *      a child process and pointed at that server via the `--assistant-port`
+ *      CLI flag.
+ *   3. The test writes a Chrome-native-messaging-framed
+ *      `{ type: "request_token" }` to the helper's stdin.
+ *   4. The helper POSTs `/v1/browser-extension-pair` on the test server,
+ *      gets back a capability token + guardianId, and echoes them to stdout
+ *      as a `token_response` frame.
+ *   5. The test asserts the returned token verifies via
+ *      `verifyHostBrowserCapability` — i.e. a fresh install can pair the
+ *      Chrome extension via the native helper end-to-end without any
+ *      shortcuts.
+ *
+ * The test **skips gracefully** if the native helper hasn't been built
+ * (`clients/chrome-extension/native-host/dist/index.js` missing). Run
+ * `bun run build` in that package first to enable the full path.
+ */
+
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+
+import {
+  mintHostBrowserCapability,
+  resetCapabilityTokenSecretForTests,
+  setCapabilityTokenSecretForTests,
+  verifyHostBrowserCapability,
+} from "../runtime/capability-tokens.js";
+import {
+  ALLOWED_EXTENSION_ORIGINS,
+  handleBrowserExtensionPair,
+} from "../runtime/routes/browser-extension-pair-routes.js";
+
+// ---------------------------------------------------------------------------
+// Native helper binary discovery + skip guard
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the path to the compiled native helper. The helper lives in a
+ * sibling package under `clients/chrome-extension/native-host/`, so we
+ * walk up from `assistant/src/__tests__/` to the repo root and then back
+ * down into the native-host package.
+ */
+function resolveHelperBinary(): string {
+  // `import.meta.dir` gives us `.../assistant/src/__tests__`. The repo
+  // root is three levels up. Past that, the native host lives at
+  // `clients/chrome-extension/native-host/dist/index.js`.
+  return resolve(
+    import.meta.dir,
+    "..",
+    "..",
+    "..",
+    "clients",
+    "chrome-extension",
+    "native-host",
+    "dist",
+    "index.js",
+  );
+}
+
+const HELPER_BINARY = resolveHelperBinary();
+const HELPER_EXISTS = existsSync(HELPER_BINARY);
+
+const ALLOWED_ORIGIN = (() => {
+  const first = Array.from(ALLOWED_EXTENSION_ORIGINS)[0];
+  if (!first) {
+    throw new Error(
+      "ALLOWED_EXTENSION_ORIGINS must contain at least one extension origin for tests",
+    );
+  }
+  return first;
+})();
+
+const SKIP_REASON =
+  "clients/chrome-extension/native-host/dist/index.js is missing — run `bun run build` in that package to enable the E2E smoke test.";
+
+// ---------------------------------------------------------------------------
+// Chrome native messaging framing (4-byte LE length prefix + UTF-8 JSON)
+// ---------------------------------------------------------------------------
+
+/**
+ * These helpers are duplicated from the native-host package's
+ * `protocol.ts` so this test is self-contained and does not reach across
+ * package boundaries at import time. The framing is fixed by the Chrome
+ * native messaging protocol spec, so there is no risk of drift.
+ */
+function encodeFrame(payload: unknown): Buffer {
+  const json = Buffer.from(JSON.stringify(payload), "utf8");
+  const len = Buffer.alloc(4);
+  len.writeUInt32LE(json.length, 0);
+  return Buffer.concat([len, json]);
+}
+
+function decodeFrames(buf: Buffer): {
+  frames: unknown[];
+  remainder: Buffer;
+} {
+  const frames: unknown[] = [];
+  let offset = 0;
+  while (buf.length - offset >= 4) {
+    const len = buf.readUInt32LE(offset);
+    if (buf.length - offset - 4 < len) break;
+    const body = buf.subarray(offset + 4, offset + 4 + len);
+    frames.push(JSON.parse(body.toString("utf8")));
+    offset += 4 + len;
+  }
+  return { frames, remainder: buf.subarray(offset) };
+}
+
+// ---------------------------------------------------------------------------
+// Minimal pair-endpoint HTTP server using the real route handler
+// ---------------------------------------------------------------------------
+
+interface PairServer {
+  server: ReturnType<typeof Bun.serve>;
+  port: number;
+  stop: () => void;
+}
+
+/**
+ * Boots a minimal Bun.serve that mounts the real
+ * `handleBrowserExtensionPair` route. This is intentionally a narrower
+ * surface than `RuntimeHttpServer` — we want to exercise the exact same
+ * route handler the daemon uses in production, but without pulling in the
+ * full runtime's dependency graph (which would drag in the workspace DB,
+ * conversation manager, etc. and make the test flaky + slow).
+ */
+function startPairServer(): PairServer {
+  const server = Bun.serve({
+    port: 0,
+    hostname: "127.0.0.1",
+    async fetch(req, srv) {
+      const url = new URL(req.url);
+      if (url.pathname === "/v1/browser-extension-pair") {
+        return handleBrowserExtensionPair(req, {
+          requestIP: (_req) => srv.requestIP(_req),
+        });
+      }
+      return new Response("not found", { status: 404 });
+    },
+  });
+  return {
+    server,
+    port: server.port as number,
+    stop: () => server.stop(true),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Subprocess helper
+// ---------------------------------------------------------------------------
+
+interface HelperRunResult {
+  frames: unknown[];
+  stderr: string;
+  exitCode: number | null;
+}
+
+function runHelper(options: {
+  extensionOrigin: string;
+  assistantPort: number;
+  stdinBytes: Buffer;
+  timeoutMs?: number;
+}): Promise<HelperRunResult> {
+  const args: string[] = [
+    HELPER_BINARY,
+    options.extensionOrigin,
+    "--assistant-port",
+    String(options.assistantPort),
+  ];
+
+  const child: ChildProcessWithoutNullStreams = spawn("node", args, {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: { ...process.env },
+  });
+
+  const stdoutChunks: Buffer[] = [];
+  const stderrChunks: Buffer[] = [];
+  child.stdout.on("data", (chunk: Buffer) => stdoutChunks.push(chunk));
+  child.stderr.on("data", (chunk: Buffer) => stderrChunks.push(chunk));
+
+  child.stdin.write(options.stdinBytes);
+  child.stdin.end();
+
+  return new Promise<HelperRunResult>((resolvePromise, rejectPromise) => {
+    const timeout = setTimeout(() => {
+      child.kill("SIGKILL");
+      rejectPromise(
+        new Error(
+          `helper binary timed out after ${options.timeoutMs ?? 5000}ms`,
+        ),
+      );
+    }, options.timeoutMs ?? 5000);
+
+    child.on("error", (err) => {
+      clearTimeout(timeout);
+      rejectPromise(err);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timeout);
+      const stdout = Buffer.concat(stdoutChunks);
+      const stderr = Buffer.concat(stderrChunks).toString("utf8");
+      try {
+        const { frames } = decodeFrames(stdout);
+        resolvePromise({ frames, stderr, exitCode: code });
+      } catch (err) {
+        rejectPromise(err as Error);
+      }
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("host-browser E2E — self-hosted native messaging path", () => {
+  let pairServer: PairServer | null = null;
+
+  beforeAll(() => {
+    // Pin the capability-token secret to a deterministic test value so
+    // the token the route mints can round-trip through
+    // `verifyHostBrowserCapability` in this process. Both sides of the
+    // flow share the same in-process module, so setting the secret once
+    // is enough for both mint + verify to agree.
+    resetCapabilityTokenSecretForTests();
+    setCapabilityTokenSecretForTests(randomBytes(32));
+
+    if (!HELPER_EXISTS) return;
+    pairServer = startPairServer();
+  });
+
+  afterAll(() => {
+    if (pairServer) pairServer.stop();
+    resetCapabilityTokenSecretForTests();
+  });
+
+  if (!HELPER_EXISTS) {
+    // Native helper hasn't been built; emit a warning so the gap is
+    // visible in test output without registering a placeholder test.
+    console.warn(`[host-browser-e2e] ${SKIP_REASON}`);
+  } else {
+    test("pair flow: request_token -> token_response -> verifiable capability token", async () => {
+      // Narrow for TS — pairServer is always set in this branch thanks to
+      // the beforeAll guard that mirrors HELPER_EXISTS.
+      const srv = pairServer!;
+
+      const result = await runHelper({
+        extensionOrigin: ALLOWED_ORIGIN,
+        assistantPort: srv.port,
+        stdinBytes: encodeFrame({ type: "request_token" }),
+      });
+
+      // Helper should have exited cleanly after writing one token_response
+      // frame. Pipe any stderr into the assertion message to make
+      // debugging failures easier.
+      expect(result.exitCode, `helper stderr: ${result.stderr}`).toBe(0);
+      expect(result.frames).toHaveLength(1);
+
+      const frame = result.frames[0] as {
+        type: string;
+        token?: string;
+        expiresAt?: string;
+        guardianId?: string;
+      };
+      expect(frame.type).toBe("token_response");
+      expect(typeof frame.token).toBe("string");
+      expect(frame.token!.length).toBeGreaterThan(0);
+      expect(typeof frame.expiresAt).toBe("string");
+
+      // Gap 3 regression guard: the helper must surface the
+      // guardianId returned by /v1/browser-extension-pair on the
+      // native-messaging frame so the chrome extension's
+      // bootstrapLocalToken() can persist it. The route's
+      // resolveLocalGuardianId() falls back to the literal string
+      // "local" when no vellum guardian is bootstrapped, which is
+      // the case in this test environment, so we assert against the
+      // exact value as well as a non-empty type guard.
+      expect(typeof frame.guardianId).toBe("string");
+      expect(frame.guardianId!.length).toBeGreaterThan(0);
+      expect(frame.guardianId).toBe("local");
+
+      // The returned token must verify via the in-process capability
+      // verifier — this is the core invariant the native-messaging
+      // bootstrap promises. The daemon is the only party that could
+      // have signed this, so a successful verification proves the
+      // end-to-end pair flow worked.
+      const claims = verifyHostBrowserCapability(frame.token!);
+      expect(claims).not.toBeNull();
+      expect(claims?.capability).toBe("host_browser_command");
+      expect(typeof claims?.guardianId).toBe("string");
+      expect(claims?.guardianId.length).toBeGreaterThan(0);
+      // The frame's guardianId should match the claim's guardianId —
+      // both originate from the same `resolveLocalGuardianId()` call
+      // inside the route handler.
+      expect(frame.guardianId).toBe(claims?.guardianId);
+      // expiresAt in the response frame should agree with the numeric
+      // claim expiry to within ISO-string precision.
+      const iso = new Date(claims!.expiresAt).toISOString();
+      expect(frame.expiresAt).toBe(iso);
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Dev-only daemon-token fallback (per-instance protected dir)
+  // -------------------------------------------------------------------------
+
+  describe("dev daemon-token fallback path", () => {
+    let tmpDir: string;
+
+    beforeAll(() => {
+      tmpDir = mkdtempSync(join(tmpdir(), "vellum-daemon-token-test-"));
+    });
+
+    afterAll(() => {
+      rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    test("a token written to a local file round-trips through verifyHostBrowserCapability", () => {
+      // Emulate the `writeDaemonTokenFallback` lifecycle: mint a fresh
+      // capability token, persist it to a 0600 file (the production
+      // helper writes to `<protectedDir>/daemon-token`, but we use a
+      // tempdir so the test doesn't clobber real dev state), then read
+      // it back and verify.
+      //
+      // This path is what the Mac app's manual "paste daemon token"
+      // pairing UI ends up exercising — the file on disk is the only
+      // transport. If the bytes on disk don't round-trip through
+      // `verifyHostBrowserCapability`, manual pairing is broken.
+      resetCapabilityTokenSecretForTests();
+      setCapabilityTokenSecretForTests(randomBytes(32));
+
+      const { token, expiresAt } = mintHostBrowserCapability("local");
+      expect(expiresAt).toBeGreaterThan(Date.now());
+
+      const tokenPath = join(tmpDir, "daemon-token");
+      writeFileSync(tokenPath, token, { mode: 0o600 });
+      // Explicitly chmod in case the umask clobbered the mode arg to
+      // writeFileSync (best-effort — some filesystems ignore this).
+      try {
+        chmodSync(tokenPath, 0o600);
+      } catch {
+        /* ignore */
+      }
+
+      const readBack = readFileSync(tokenPath, "utf8");
+      expect(readBack).toBe(token);
+
+      const claims = verifyHostBrowserCapability(readBack);
+      expect(claims).not.toBeNull();
+      expect(claims?.capability).toBe("host_browser_command");
+      expect(claims?.guardianId).toBe("local");
+    });
+  });
+});