@emseepea/testing 0.25.0 → 0.25.2

package/README.md

@@ -643,8 +643,9 @@ days.
 
 Import `@emseepea/testing/chatgpt` only when you want to test the real ChatGPT
 web experience. Ordinary framework tests do not enable this adapter or install
-Playwright. This is an experimental browser
-adapter: ChatGPT controls can change, and live host qualification is pending.
+Playwright. This is an experimental browser adapter: ChatGPT controls can
+change, so adopters must qualify each capability they rely on against their
+owned account and endpoint.
 
 On your own machine, install the optional browser tooling:
 
@@ -670,6 +671,63 @@ The command verifies a
 signed-in control, not the account's identity; the human confirms that identity.
 If that control changes, pass an account-specific `--authenticated-selector`.
 
+### Use an already-authorized browser
+
+If the launched browser repeats a security challenge, stop setup. Complete
+login, MFA, CAPTCHA, and consent yourself in an ordinary browser. The setup
+helper keeps Chromium's sandbox enabled, but cannot guarantee that an
+automation-launched browser will be accepted by the login service.
+
+An existing Playwright integration can pass its owner-authorized `Page` directly
+to `runNativeChatGptJourney`. The adapter does not need to launch that browser.
+It cannot attach to an arbitrary ordinary Chrome window without a supported
+browser control interface.
+
+Chrome versions with GUI remote debugging expose it at
+`chrome://inspect/#remote-debugging`. The browser owner can select "Allow remote
+debugging for this browser instance" and approve the connection in Chrome.
+This needs no command-line browser launch.
+
+The runner must still execute on
+the browser's host; enabling this option does not give a cloud runner access
+to another computer. Use a dedicated test browser and disable debugging when
+finished.
+
+For a Chromium session that the adopter has already opened and exposed through
+Chrome DevTools Protocol (CDP), the execution command can attach locally:
+
+```sh
+npx emseepea-chatgpt --enable-native-chatgpt --scenario ./native-chatgpt.mjs \
+  --connect-cdp 'ws://127.0.0.1:9222/devtools/browser/<browser-id>' \
+  --browser-owner '<test-account-owner>'
+```
+
+This is an alternative to the setup command, not a way to solve a CAPTCHA.
+The browser owner must confirm the signed-in account and complete connection
+consent before attaching. `--browser-owner` must match the scenario's account
+owner. Use a dedicated synthetic-test browser with one browser context.
+
+The command accepts only a browser WebSocket on literal `127.0.0.1`, an explicit
+port from 1024 to 65535, and `/devtools/browser` with an optional browser ID.
+Remote hosts,
+credentials, query strings, redirects, HTTP discovery, and profile options are
+rejected.
+
+WebSocket messages and the initial send queue are capped at 16 MiB.
+Keep the debugging interface and address private, bound to loopback, and
+available only while testing; CDP grants browser control and is not an account
+authorization mechanism.
+
+Attachment opens a separate test tab in the authorized context. It does not
+read or export cookies or storage state, inspect existing tabs, launch Chrome,
+or alter login behavior or the owner's browser defaults.
+
+After the scenario's required cleanup, the runner
+closes its tab and disconnects. The owner browser and its existing tabs remain
+open. Missing browser access or incomplete authentication blocks verification.
+
+### Connect and run the owned scenario
+
 Connect your authorized HTTPS MCP endpoint through ChatGPT's current plugin
 installation flow. Complete account consent yourself. A local server requires
 a supported HTTPS tunnel before ChatGPT can reach it. See the
@@ -728,6 +786,16 @@ Return ordered, run-scoped calls matching the declared method, target, outcome,
 and optional result hash. Each call includes request/result SHA-256 values,
 endpoint SHA-256, sequence, timestamp, and `nativeClient`.
 
+Keep deterministic MCP qualification and native-host evidence separate.
+Command-line qualification can prove a resource link's shape, catalogue
+membership, exact `resources/read` result, and original bytes. A native ChatGPT
+journey separately proves whether ChatGPT materializes or rejects that link.
+
+Declare the expected `tools/call` and `resources/read` as distinct server calls.
+If ChatGPT does not issue the expected read, record the checkpoint as
+`incomplete` with category `server-observation-missing`; do not treat the
+tool-returned URI as proof of a native resource read.
+
 Set
 `nativeClient: "verified-chatgpt"` only when your authenticated server boundary
 establishes that the request came through the dedicated ChatGPT connection;

package/chatgpt/run.mjs

@@ -4,12 +4,15 @@ import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { attachOwnedBrowser, validateBrowserAttachment } from "./session.mjs";
 
 const help = `Usage: emseepea-chatgpt --enable-native-chatgpt --scenario <owned-module.mjs>
   [--profile <dedicated-directory>] [--output <private-evidence.json>]
+  Or attach: --connect-cdp <loopback-browser-WebSocket> --browser-owner <owner>
 
 The module exports authorization and createJourney({ page, runId }). It owns
-its assertions, server observations, and cleanup. Complete human setup first.
+its assertions, server observations, and cleanup. Complete human setup first,
+or explicitly confirm ownership of an already-authorized local CDP browser.
 This command never logs in, grants consent, or exports authentication state.
 `;
 
@@ -21,37 +24,49 @@ async function main() {
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--enable-native-chatgpt") continue;
-    if (!["--scenario", "--profile", "--output"].includes(arg) || values.has(arg) || !args[index + 1] || args[index + 1].startsWith("--")) throw new Error("invalid-run-options");
+    if (!["--scenario", "--profile", "--output", "--connect-cdp", "--browser-owner"].includes(arg) || values.has(arg) || !args[index + 1] || args[index + 1].startsWith("--")) throw new Error("invalid-run-options");
     values.set(arg, args[++index]);
   }
   if (!values.get("--scenario")) throw new Error("owned-scenario-required");
   const scenario = await import(pathToFileURL(resolve(values.get("--scenario"))).href);
   if (typeof scenario.createJourney !== "function" || scenario.authorization?.approved !== true || typeof scenario.authorization.accountOwner !== "string") throw new Error("owned-scenario-required");
-  const profile = resolve(values.get("--profile") ?? join(homedir(), ".emseepea", "chatgpt-browser"));
-  const record = await readFile(join(profile, "emseepea-profile.json"), "utf8").then(JSON.parse).catch(() => undefined);
-  const ownerSha256 = createHash("sha256").update(scenario.authorization.accountOwner).digest("hex");
-  if (record?.schemaVersion !== 1 || record?.humanConfirmed !== true || record?.ownerSha256 !== ownerSha256 || !["chromium", "chrome", "msedge"].includes(record?.channel)) throw new Error("human-setup-required");
+  const attached = values.has("--connect-cdp");
+  if ((attached && values.has("--profile")) || (!attached && values.has("--browser-owner"))) throw new Error("invalid-run-options");
+  if (attached) validateBrowserAttachment(values.get("--connect-cdp"), values.get("--browser-owner"), scenario.authorization.accountOwner);
+  let profile;
+  let record;
+  if (!attached) {
+    profile = resolve(values.get("--profile") ?? join(homedir(), ".emseepea", "chatgpt-browser"));
+    record = await readFile(join(profile, "emseepea-profile.json"), "utf8").then(JSON.parse).catch(() => undefined);
+    const ownerSha256 = createHash("sha256").update(scenario.authorization.accountOwner).digest("hex");
+    if (record?.schemaVersion !== 1 || record?.humanConfirmed !== true || record?.ownerSha256 !== ownerSha256 || !["chromium", "chrome", "msedge"].includes(record?.channel)) throw new Error("human-setup-required");
+  }
   let chromium;
   try { ({ chromium } = await import("playwright")); }
   catch { throw new Error("optional-playwright-dependency-required"); }
   const { runNativeChatGptJourney } = await import("../dist/chatgpt.js");
-  let context;
-  try { context = await chromium.launchPersistentContext(profile, { headless: false, ...(record.channel === "chromium" ? {} : { channel: record.channel }) }); }
-  catch { throw new Error("headed-browser-unavailable"); }
+  let session;
+  if (attached) session = await attachOwnedBrowser({ chromium, endpoint: values.get("--connect-cdp"), browserOwner: values.get("--browser-owner"), accountOwner: scenario.authorization.accountOwner });
+  else {
+    let context;
+    try { context = await chromium.launchPersistentContext(profile, { headless: false, chromiumSandbox: true, ...(record.channel === "chromium" ? {} : { channel: record.channel }) }); }
+    catch { throw new Error("headed-browser-unavailable"); }
+    session = { page: context.pages()[0] ?? await context.newPage(), close: () => context.close() };
+  }
   try {
-    const page = context.pages()[0] ?? await context.newPage();
-    await page.goto("https://chatgpt.com/", { waitUntil: "domcontentloaded" });
+    const page = session.page;
+    if (!attached) await page.goto("https://chatgpt.com/", { waitUntil: "domcontentloaded" });
     const runId = randomUUID();
     const declared = await scenario.createJourney({ page, runId });
     const evidence = await runNativeChatGptJourney({ ...declared, enabled: true, page, runId, authorization: scenario.authorization },
       resolve(values.get("--output") ?? "artifacts/native-chatgpt/evidence.json"));
     console.log(`Native ChatGPT journey ${evidence.status}. Evidence written privately.`);
     if (evidence.status !== "passed") process.exitCode = evidence.status === "failed" ? 1 : 2;
-  } finally { await context.close(); }
+  } finally { await session.close(); }
 }
 
 main().catch((error) => {
-  const categories = new Set(["explicit-opt-in-required", "invalid-run-options", "owned-scenario-required", "human-setup-required", "optional-playwright-dependency-required", "headed-browser-unavailable"]);
+  const categories = new Set(["explicit-opt-in-required", "invalid-run-options", "owned-scenario-required", "human-setup-required", "optional-playwright-dependency-required", "headed-browser-unavailable", "browser-owner-confirmation-required", "loopback-browser-endpoint-required", "owned-browser-attachment-unavailable"]);
   console.error(`Native ChatGPT journey blocked: ${categories.has(error.message) ? error.message : "journey-unavailable"}`);
   process.exitCode = 2;
 });

package/chatgpt/session.mjs

@@ -0,0 +1,83 @@
+// The owner exposes this local browser interface; this module never launches,
+// authenticates, exports storage, or bypasses a browser challenge.
+export function validateBrowserAttachment(endpoint, browserOwner, accountOwner) {
+  if (typeof accountOwner !== "string" || !accountOwner.trim() || browserOwner !== accountOwner) throw new Error("browser-owner-confirmation-required");
+  if (typeof endpoint !== "string" || endpoint.length > 256 || !/^ws:\/\/127\.0\.0\.1:[0-9]+\/devtools\/browser(?:\/[A-Za-z0-9-]+)?$/.test(endpoint)) throw new Error("loopback-browser-endpoint-required");
+  let url;
+  try { url = new URL(endpoint); }
+  catch { throw new Error("loopback-browser-endpoint-required"); }
+  if (Number(url.port) < 1024 || Number(url.port) > 65535 || !url.port || url.pathname.length > 150) throw new Error("loopback-browser-endpoint-required");
+  return url.href;
+}
+
+export async function attachOwnedBrowser({ chromium, endpoint, browserOwner, accountOwner }) {
+  const address = validateBrowserAttachment(endpoint, browserOwner, accountOwner);
+  const transport = browserTransport(address);
+  let browser;
+  let page;
+  try {
+    // Supported Playwright transport seam: Node's WebSocket rejects redirects,
+    // while Playwright's URL connector follows them. Keep browser defaults.
+    transport.open();
+    browser = await chromium.connectOverCDP(transport, { timeout: 30_000, noDefaults: true });
+    const contexts = browser.contexts();
+    if (contexts.length !== 1) throw new Error("owned-browser-context-required");
+    // A new tab shares the owner's authorized session without selecting,
+    // navigating, closing, or retaining any pre-existing private tab.
+    page = await contexts[0].newPage();
+    await page.goto("https://chatgpt.com/", { waitUntil: "domcontentloaded", timeout: 30_000 });
+    return { page, async close() {
+      try { await page.close({ runBeforeUnload: false }); }
+      finally { await browser.close(); } // CDP-connected close disconnects, not browser termination.
+    } };
+  } catch {
+    try { await page?.close({ runBeforeUnload: false }); } catch { /* redacted */ }
+    try { await browser?.close(); } catch { /* redacted */ }
+    transport.close();
+    throw new Error("owned-browser-attachment-unavailable");
+  }
+}
+
+// Only JSON framing for Playwright's public ConnectOverCDPTransport interface.
+// Playwright owns all CDP/browser semantics. No messages are retained or logged.
+function browserTransport(address) {
+  let socket;
+  let ended = false;
+  const pending = [];
+  let pendingBytes = 0;
+  const finish = () => {
+    if (ended) return;
+    ended = true;
+    pending.length = 0;
+    pendingBytes = 0;
+    transport.onclose?.("browser-connection-closed");
+  };
+  const transport = {
+    open() {
+      socket = new WebSocket(address);
+      socket.onopen = () => {
+        try { for (const message of pending) socket.send(message); pending.length = 0; pendingBytes = 0; }
+        catch { transport.close(); finish(); }
+      };
+      socket.onmessage = (event) => {
+        try {
+          if (typeof event.data !== "string" || Buffer.byteLength(event.data) > 16 * 1024 * 1024) throw new Error("bounded-message-required");
+          transport.onmessage?.(JSON.parse(event.data));
+        } catch { transport.close(); finish(); }
+      };
+      socket.onerror = finish;
+      socket.onclose = finish;
+    },
+    send(message) {
+      const encoded = JSON.stringify(message);
+      if (ended || Buffer.byteLength(encoded) > 16 * 1024 * 1024) throw new Error("bounded-message-required");
+      if (socket.readyState === WebSocket.CONNECTING) {
+        if (pending.length >= 64 || pendingBytes + Buffer.byteLength(encoded) > 16 * 1024 * 1024) throw new Error("bounded-message-required");
+        pending.push(encoded);
+        pendingBytes += Buffer.byteLength(encoded);
+      } else socket.send(encoded);
+    },
+    close() { socket?.close(); },
+  };
+  return transport;
+}

package/chatgpt/setup.mjs

@@ -49,7 +49,7 @@ async function main() {
   }
   await chmod(profile, 0o700);
   let context;
-  try { context = await chromium.launchPersistentContext(profile, { headless: false, ...(channel === "chromium" ? {} : { channel }) }); }
+  try { context = await chromium.launchPersistentContext(profile, { headless: false, chromiumSandbox: true, ...(channel === "chromium" ? {} : { channel }) }); }
   catch { throw new Error("headed-browser-unavailable"); }
   const terminal = createInterface({ input: process.stdin, output: process.stdout });
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emseepea/testing",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "description": "MCP integration and semantic testing helpers",
   "license": "MIT",
   "repository": {