cdp-mcp 0.1.3 → 0.2.0

package/dist/tools/session.js

@@ -16,7 +16,7 @@ export function registerSessionTools(server) {
         sandbox: z
             .boolean()
             .optional()
-            .describe("Enable Chromium's sandbox. Default false — we add --no-sandbox. On Ubuntu 23.10+ AppArmor restricts the unprivileged user namespace Chromium's sandbox depends on, so unsandboxed launch is the working default for automation. Pass true only on a host with a working sandbox path (AppArmor userns allowance or SUID chrome_sandbox helper)."),
+            .describe("Enable Chromium's sandbox. When omitted, defaults from the CDP_SANDBOX env ('true' or '1' enable it; default false → we add --no-sandbox). On Ubuntu 23.10+ AppArmor restricts the unprivileged user namespace Chromium's sandbox depends on, so unsandboxed launch is the working default for automation. Pass true only on a host with a working sandbox path (AppArmor userns allowance or SUID chrome_sandbox helper)."),
     }, async (input) => {
         return await launchChrome({
             url: input.url,

package/dist/tools/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/tools/session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/tools/session.ts"],"names":[],"mappings":"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"}

package/dist/tools/source.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSourceTools(server: McpServer): void;

package/dist/tools/storage.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerStorageTools(server: McpServer): void;

package/dist/tools/storage.js

@@ -0,0 +1,296 @@
+import { z } from "zod";
+import { readFile, writeFile, rename, rm } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { requireSession } from "../session/state.js";
+import { ToolError } from "../util/errors.js";
+import { registerJsonTool } from "./_register.js";
+/**
+ * Session-portability tools (issue #12 items 4, 5).
+ *
+ * Cookies go through CDP `Network.*` (NOT `document.cookie`) so HttpOnly
+ * auth/session cookies — the whole reason to resume a session — round-trip.
+ * localStorage is read/written via `Runtime.evaluate` (the `Storage.*` domain
+ * is out of scope per AGENTS.md). The on-disk shape is the de-facto Playwright
+ * `storageState` JSON so a flow can be handed to/from mainstream tooling.
+ *
+ * v1 localStorage scope is the **current page origin** only: localStorage is
+ * origin-partitioned and CDP can only read/write it for a document that is
+ * actually on that origin. Cookies (the load-bearing part for auth resume) are
+ * captured/restored for all origins. Multi-origin localStorage restore would
+ * require navigating to each origin first; origins in the file that don't match
+ * the current page are reported in `origins_skipped` rather than silently lost.
+ *
+ * File read/write mirrors `screenshot path=`: no extra path filter — the
+ * operator gate is the same `--allow-remote`/non-loopback rule (README §SSE).
+ */
+const SENSITIVE_NAME = /(sess|sid|token|auth|csrf|xsrf|jwt|secret|api[-_]?key)/i;
+const sameSiteSchema = z.enum(["Strict", "Lax", "None"]);
+const storageStateSchema = z.object({
+    cookies: z
+        .array(z.object({
+        name: z.string(),
+        value: z.string(),
+        domain: z.string(),
+        path: z.string(),
+        expires: z.number().optional(),
+        httpOnly: z.boolean().optional(),
+        secure: z.boolean().optional(),
+        sameSite: sameSiteSchema.optional(),
+    }))
+        .default([]),
+    origins: z
+        .array(z.object({
+        origin: z.string(),
+        localStorage: z.array(z.object({ name: z.string(), value: z.string() })).default([]),
+    }))
+        .default([]),
+});
+const cookieParamSchema = z.object({
+    name: z.string(),
+    value: z.string(),
+    url: z.string().optional().describe("Cookie URL (provide this OR domain)."),
+    domain: z.string().optional(),
+    path: z.string().optional(),
+    secure: z.boolean().optional(),
+    httpOnly: z.boolean().optional(),
+    sameSite: sameSiteSchema.optional(),
+    expires: z.number().optional().describe("Expiry as seconds since epoch; omit for a session cookie."),
+});
+/**
+ * Write `data` to `dest` at mode 0o600, overwrite-safe and TOCTOU-safe.
+ *
+ * The storage-state file holds plaintext cookie secrets, so the 0o600
+ * postcondition must hold even on a shared, world-writable directory. Two traps:
+ *  - Node's writeFile `mode` only applies when it *creates* the file, so writing
+ *    straight to `dest` would leave an existing 0644 file world-readable.
+ *  - A *predictable* temp path lets an attacker pre-create (or symlink) it at
+ *    0644, so the secret gets written through their file and renamed into place.
+ *
+ * So: create a temp with an **unpredictable** same-directory suffix using
+ * exclusive create (`flag: "wx"` ⇒ O_CREAT|O_EXCL — fails on any pre-existing
+ * file and refuses to follow a symlink), which makes 0o600 a real creation-time
+ * guarantee, then atomically rename it over the destination (same filesystem, so
+ * the secret never exists at the destination path in a half-written/0644 state).
+ * Retry on the astronomically-unlikely name collision.
+ */
+async function writeSecretFileAtomic(dest, data) {
+    let lastErr;
+    for (let attempt = 0; attempt < 5; attempt++) {
+        const tmp = `${dest}.${randomBytes(8).toString("hex")}.tmp`;
+        try {
+            await writeFile(tmp, data, { flag: "wx", mode: 0o600 });
+        }
+        catch (e) {
+            if (e.code === "EEXIST") {
+                lastErr = e;
+                continue; // collision (or planted file/symlink) — try a fresh random name
+            }
+            throw e; // ENOENT (missing parent dir), EACCES, etc.
+        }
+        try {
+            await rename(tmp, dest);
+        }
+        catch (e) {
+            await rm(tmp, { force: true }).catch(() => { });
+            throw e;
+        }
+        return;
+    }
+    throw lastErr;
+}
+export function registerStorageTools(server) {
+    registerJsonTool(server, "export_storage_state", "Save the browser session (all cookies including HttpOnly, plus the current page origin's localStorage) to a JSON file in the de-facto Playwright storageState shape, so a flow can be resumed in a fresh session or handed to other tooling. The file preserves full cookie values (it exists to resume auth) — treat it as a secret. File write is gated by the same operator rule as screenshot path= / --allow-remote.", { path: z.string().describe("Absolute path to write the storageState JSON to.") }, async (input) => {
+        const s = requireSession();
+        const { cookies } = (await s.client.send("Network.getAllCookies"));
+        const probe = await s.client.send("Runtime.evaluate", {
+            expression: READ_ORIGIN_AND_LOCALSTORAGE,
+            returnByValue: true,
+        });
+        const probed = (probe.result?.value ?? { origin: "null", localStorage: [] });
+        const origins = probed.origin && probed.origin !== "null"
+            ? [{ origin: probed.origin, localStorage: probed.localStorage }]
+            : [];
+        const state = { cookies: cookies.map(cdpCookieToState), origins };
+        // The file holds full cookie values (incl. HttpOnly auth/session tokens) —
+        // the description says "treat it as a secret". writeSecretFileAtomic writes
+        // it 0o600 and overwrite-safe (see the helper for the threat model).
+        try {
+            await writeSecretFileAtomic(input.path, JSON.stringify(state, null, 2));
+        }
+        catch (e) {
+            if (e.code === "ENOENT") {
+                throw new ToolError("not_found", `could not write storage-state file (does the parent directory exist?): ${e.message}`);
+            }
+            throw e; // EACCES/EISDIR/etc. surface as internal_error via registerJsonTool
+        }
+        return { saved: input.path, cookies: state.cookies.length, origins: origins.length };
+    });
+    registerJsonTool(server, "load_storage_state", "Restore a session from a Playwright-shaped storageState JSON file: sets all cookies (no navigation needed), then restores localStorage for the entries whose origin matches the current page. Cookies are added on top of the existing jar (additive, not a clean-context replace), so prefer a fresh session for Playwright-equivalent semantics. Origins that don't match the current page are returned in origins_skipped (restoring them would require navigating there first). File read is gated by the same operator rule as screenshot path= / --allow-remote.", { path: z.string().describe("Absolute path to a storageState JSON file (as written by export_storage_state).") }, async (input) => {
+        const s = requireSession();
+        let raw;
+        try {
+            raw = await readFile(input.path, "utf8");
+        }
+        catch (e) {
+            if (e.code === "ENOENT") {
+                throw new ToolError("not_found", `could not read storage-state file: ${e.message}`);
+            }
+            throw e; // EACCES/EISDIR/etc. surface as internal_error rather than masquerading as not_found
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new ToolError("invalid_arg", "storage-state file is not valid JSON");
+        }
+        const result = storageStateSchema.safeParse(parsed);
+        if (!result.success) {
+            throw new ToolError("invalid_arg", `storage-state file is not a valid storageState: ${result.error.message}`);
+        }
+        const state = result.data;
+        if (state.cookies.length > 0) {
+            await s.client.send("Network.setCookies", { cookies: state.cookies.map(stateCookieToCdp) });
+        }
+        const restore = await s.client.send("Runtime.evaluate", {
+            expression: restoreLocalStorageExpr(state.origins),
+            returnByValue: true,
+        });
+        const restored = (restore.result?.value ?? { restored: [], skipped: state.origins.map((o) => o.origin) });
+        return {
+            loaded: input.path,
+            cookies: state.cookies.length,
+            origins_restored: restored.restored,
+            origins_skipped: restored.skipped,
+        };
+    });
+    registerJsonTool(server, "get_cookies", "List cookies (via CDP, so HttpOnly cookies are included) with their flags. For safe printing, the VALUE of likely session/auth cookies is redacted (httpOnly cookies, or names matching sess/sid/token/auth/csrf/jwt/secret/api-key); only value_length is shown for those. Full values are obtainable only through export_storage_state.", {
+        urls: z
+            .array(z.string())
+            .optional()
+            .describe("Restrict to cookies visible to these URLs; omit for all cookies in the browser."),
+    }, async (input) => {
+        const s = requireSession();
+        const res = (input.urls && input.urls.length > 0
+            ? await s.client.send("Network.getCookies", { urls: input.urls })
+            : await s.client.send("Network.getAllCookies"));
+        return { cookies: res.cookies.map(redactForDisplay) };
+    });
+    registerJsonTool(server, "set_cookies", "Set one or more cookies in the browser cookie jar via CDP. Each cookie needs a url OR a domain. For restoring a saved session, prefer load_storage_state; this is the lower-level primitive.", { cookies: z.array(cookieParamSchema).describe("Cookies to set.") }, async (input) => {
+        const s = requireSession();
+        if (input.cookies.length === 0)
+            throw new ToolError("missing_arg", "cookies array is empty");
+        const missing = input.cookies.find((c) => !c.url && !c.domain);
+        if (missing)
+            throw new ToolError("missing_arg", `cookie '${missing.name}' needs a url or domain`);
+        // Normalize the session-cookie sentinel the same way load_storage_state
+        // does, so an exported `expires: -1` piped in here isn't sent as a 1969 expiry.
+        await s.client.send("Network.setCookies", {
+            cookies: input.cookies.map(withSessionExpiryOmitted),
+        });
+        return { set: input.cookies.length };
+    });
+}
+function cdpCookieToState(c) {
+    return {
+        name: c.name,
+        value: c.value,
+        domain: c.domain,
+        path: c.path,
+        // CDP uses -1 (or a missing field) for session cookies; Playwright too.
+        expires: typeof c.expires === "number" ? c.expires : -1,
+        httpOnly: !!c.httpOnly,
+        secure: !!c.secure,
+        // Playwright requires sameSite; CDP may omit it. Lax is the browser default.
+        sameSite: c.sameSite ?? "Lax",
+    };
+}
+/**
+ * CDP's `Network.setCookies` reads `expires` as an absolute epoch-seconds
+ * timestamp, so the session-cookie sentinel (`-1`, which `export_storage_state`
+ * writes) must be dropped rather than forwarded — otherwise the cookie is set
+ * already-expired (1969) and silently rejected. Shared by `load_storage_state`
+ * and `set_cookies` so both restore paths normalize identically.
+ */
+function withSessionExpiryOmitted(cookie) {
+    if (typeof cookie.expires === "number" && cookie.expires >= 0)
+        return cookie;
+    const copy = { ...cookie };
+    delete copy.expires;
+    return copy;
+}
+function stateCookieToCdp(c) {
+    const param = {
+        name: c.name,
+        value: c.value,
+        domain: c.domain,
+        path: c.path,
+        secure: !!c.secure,
+        httpOnly: !!c.httpOnly,
+        expires: c.expires,
+    };
+    if (c.sameSite)
+        param.sameSite = c.sameSite;
+    // -1 / undefined means a session cookie — omit expires entirely.
+    return withSessionExpiryOmitted(param);
+}
+function redactForDisplay(c) {
+    const redacted = !!c.httpOnly || SENSITIVE_NAME.test(c.name);
+    const out = {
+        name: c.name,
+        domain: c.domain,
+        path: c.path,
+        expires: typeof c.expires === "number" ? c.expires : -1,
+        httpOnly: !!c.httpOnly,
+        secure: !!c.secure,
+        sameSite: c.sameSite ?? null,
+        redacted,
+        value_length: (c.value ?? "").length,
+    };
+    if (!redacted)
+        out.value = c.value;
+    return out;
+}
+// ---------------------------------------------------------------------------
+// In-page expressions
+/** Read the current origin and its localStorage as { origin, localStorage:[{name,value}] }. */
+const READ_ORIGIN_AND_LOCALSTORAGE = String.raw `(() => {
+  const items = [];
+  try {
+    for (let i = 0; i < localStorage.length; i++) {
+      const k = localStorage.key(i);
+      if (k === null) continue;
+      const v = localStorage.getItem(k);
+      if (v === null) continue;
+      items.push({ name: k, value: v });
+    }
+  } catch (e) {}
+  return { origin: location.origin, localStorage: items };
+})()`;
+/**
+ * For each origin in the file whose origin matches the current page, write its
+ * localStorage entries; report which origins were restored vs skipped.
+ */
+function restoreLocalStorageExpr(origins) {
+    return String.raw `(() => {
+    const origins = ${JSON.stringify(origins)};
+    const current = location.origin;
+    const restored = [];
+    const skipped = [];
+    for (const o of origins) {
+      if (o.origin !== current) {
+        skipped.push(o.origin);
+        continue;
+      }
+      // If any setItem throws (quota exceeded, storage disabled), report the
+      // origin as skipped rather than misleadingly claiming it was restored.
+      let ok = true;
+      for (const it of o.localStorage) {
+        try { localStorage.setItem(it.name, it.value); } catch (e) { ok = false; }
+      }
+      (ok ? restored : skipped).push(o.origin);
+    }
+    return { restored, skipped };
+  })()`;
+}
+//# sourceMappingURL=storage.js.map

package/dist/tools/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/tools/storage.ts"],"names":[],"mappings":"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"}

package/dist/util/browser-resolve.d.ts

@@ -0,0 +1,19 @@
+export type BrowserChoice = "chromium" | "chrome";
+export interface ResolvedBrowser {
+    /** Absolute path to the Chrome/Chromium executable. */
+    binaryPath: string;
+    /** Which logical browser this binary represents. */
+    choice: BrowserChoice;
+    /** True when the binary is snap-confined (/snap/bin/* on Linux). Triggers
+     *  the user-data-dir workaround in launch_chrome. */
+    snapConfined: boolean;
+    /** Diagnostic — which resolution step produced this. */
+    source: "CDP_TEST_BROWSER_PATH" | "which-chromium" | "playwright-cache" | "chrome-launcher-default";
+}
+export declare function getBrowserChoice(): BrowserChoice;
+export declare function resolveBrowser(choice?: BrowserChoice): ResolvedBrowser;
+/** True when the given binary is the snap-marker returned by step 4. */
+export declare function isChromeLauncherDefault(b: ResolvedBrowser): boolean;
+/** Determine the user-data-dir for snap-confined Chromium. Snap confinement
+ *  rejects /tmp/... paths; only ~/snap/<app>/current/ is writable. */
+export declare function snapUserDataDir(binaryPath: string): string;

package/dist/util/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class ToolError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare const noSession: () => ToolError;
+export declare const notPaused: () => ToolError;
+export declare const alreadySession: () => ToolError;

package/dist/util/format.d.ts

@@ -0,0 +1,20 @@
+import type { Protocol } from "devtools-protocol";
+export declare function truncate(s: string, max?: number): string;
+export declare function previewRemoteObject(obj: Protocol.Runtime.RemoteObject): string;
+export declare function describeRemote(obj: Protocol.Runtime.RemoteObject): {
+    type: string;
+    preview: string;
+    objectId?: string;
+};
+export declare function toolText(text: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function toolJson(value: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/util/log.d.ts

@@ -0,0 +1,6 @@
+export declare const log: {
+    debug: (msg: string, meta?: Record<string, unknown>) => void;
+    info: (msg: string, meta?: Record<string, unknown>) => void;
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+    error: (msg: string, meta?: Record<string, unknown>) => void;
+};

package/docs/chromium-sandboxing.md

@@ -107,6 +107,12 @@ Untrusted browsing:
 - Add host-level confinement such as AppArmor, a container, VM, or Bubblewrap.
 - Do not treat `bwrap + --no-sandbox` as equivalent to Chromium sandboxing.
 
+This outer containment also pairs with the agent-operator threat (prompt-injected
+page content steering the agent into actions or unscoped filesystem writes); see
+the agent-operator threat model and deployment hardening in
+[SECURITY.md](../SECURITY.md). A containerized outer-sandbox run mode that would
+make this contained posture the default is a direction under consideration.
+
 ## Validated hosts
 
 Hosts where `sandbox: true` has been verified working against this project, with the supporting posture:

package/docs/local-l3-e2e-setup.md

@@ -0,0 +1,199 @@
+# Local L3 e2e setup (Playwright Chromium + AppArmor)
+
+**Last updated: 2026-06-09**
+
+A step-by-step runbook for getting `npm run test:e2e` (the L3 real-browser
+suite) passing on a local Linux machine **with Chromium's sandbox on**. This is
+the practical companion to [`chromium-sandboxing.md`](./chromium-sandboxing.md);
+read that for the full `--no-sandbox` / `sandbox: true` threat model and the
+validated-hosts table.
+
+Assumes Ubuntu (23.10+/24.04). Other distributions may need no host-side work at
+all — see "Other distributions" below.
+
+## Why this is needed on Ubuntu
+
+The L3 e2e harness launches Chromium with the sandbox **on** when running
+locally; it only adds `--no-sandbox` when the `CI` env var is set
+(`test/e2e/setup/global.ts`). That is deliberate — locally we want the sandbox
+when the host can provide it.
+
+But recent Ubuntu releases ship:
+
+```sh
+kernel.apparmor_restrict_unprivileged_userns = 1
+```
+
+which blocks the unprivileged **user namespace** that Chromium's sandbox needs.
+Playwright-bundled Chromium does not ship a SUID `chrome_sandbox` helper, so on a
+stock Ubuntu host a sandbox-on launch fails before the DevTools port opens:
+
+```text
+zygote_host_impl_linux.cc: No usable sandbox!
+```
+
+From `chrome-launcher` this usually surfaces as a startup port-poll timeout or
+`ECONNREFUSED`.
+
+The fix is an AppArmor profile that grants `userns,` to the Playwright Chromium
+binary, giving it a stable named label that is allowed to create the user
+namespace. The steps below install Chromium, confirm the resolver finds it,
+attach the profile, and run the suite.
+
+## 1. Install Playwright Chromium
+
+From the repo:
+
+```sh
+npx --yes playwright install chromium
+```
+
+This drops a managed Chromium into the per-user cache:
+
+```text
+~/.cache/ms-playwright/chromium-<rev>/chrome-linux*/chrome
+```
+
+The leaf directory varies by Playwright version and arch — `chrome-linux` on
+ARM64 and older builds, `chrome-linux64` on x86_64 with the newer
+Chrome-for-Testing layout (the resolver and the AppArmor glob below cover both).
+Install it for **each OS user** that will run the suite — the cache is
+per-`$HOME`.
+
+## 2. Verify the resolver finds it
+
+The launcher resolver (`src/util/browser-resolve.ts`) finds Chromium in this
+order: an explicit `CDP_TEST_BROWSER_PATH`, then a system `chromium` on `PATH`,
+then the Playwright cache. After a build, confirm what it picks:
+
+```sh
+npm run build
+node --input-type=module \
+  -e "import('./dist/util/browser-resolve.js').then(m => console.log(JSON.stringify(m.resolveBrowser(), null, 2)))"
+```
+
+This runbook targets the **Playwright-cache** binary, so expect
+`source: "playwright-cache"` and a `binaryPath` under `~/.cache/ms-playwright/`:
+
+```json
+{
+  "binaryPath": "/home/<user>/.cache/ms-playwright/chromium-<rev>/chrome-linux/chrome",
+  "choice": "chromium",
+  "snapConfined": false,
+  "source": "playwright-cache"
+}
+```
+
+If you have a system Chromium on `PATH` (apt `/usr/bin/chromium`, snap
+`/snap/bin/chromium`), the resolver returns that first with
+`source: "which-chromium"` — that binary is *not* covered by the AppArmor
+profile below (snap brings its own confinement; apt Chromium is a separate
+sandbox story). To exercise the Playwright binary under this profile, point the
+suite at it explicitly:
+
+```sh
+export CDP_TEST_BROWSER_PATH="$(ls -d ~/.cache/ms-playwright/chromium-*/chrome-linux*/chrome | head -1)"
+```
+
+## 3. Attach the AppArmor profile
+
+First confirm the kernel knob is the restrictive default:
+
+```sh
+sysctl kernel.apparmor_restrict_unprivileged_userns   # = 1 on stock Ubuntu 24.04
+```
+
+If it is `0` (some hosts turn it off system-wide), Chromium's sandbox already
+works and you can skip to step 5.
+
+Create a profile that grants `userns,` to the Playwright Chromium binary path.
+This mirrors the shape of Ubuntu's stock `chrome` / `msedge` / `brave` profiles
+(a named-unconfined profile that opts into user namespaces):
+
+```apparmor
+# /etc/apparmor.d/cdp-mcp-chromium
+abi <abi/4.0>,
+include <tunables/global>
+
+profile cdp-mcp-chromium /home/*/.cache/ms-playwright/chromium-*/chrome-linux*/chrome flags=(unconfined) {
+  userns,
+
+  include if exists <local/cdp-mcp-chromium>
+}
+```
+
+The `chrome-linux*` component matches both the `chrome-linux` (ARM64/older) and
+`chrome-linux64` (x86_64 Chrome-for-Testing) layouts — in AppArmor `*` matches
+within a single path segment, so a too-specific `chrome-linux` would silently
+fail to attach on x86_64. The `/home/*/` glob matches any user's Playwright
+cache; if you prefer to scope it to specific accounts, replace `*` with a brace
+list of usernames, e.g. `/home/{alice,bob}/.cache/...`.
+
+Load it (profiles in `/etc/apparmor.d/` also auto-load at boot):
+
+```sh
+sudo apparmor_parser -r /etc/apparmor.d/cdp-mcp-chromium
+```
+
+## 4. Verify the label attaches
+
+Launch the bundled Chromium sandbox-on and read its AppArmor label — it must be
+the named profile, not bare `unconfined`:
+
+```sh
+BIN=$(ls -d ~/.cache/ms-playwright/chromium-*/chrome-linux*/chrome | head -1)
+"$BIN" --headless=new --no-startup-window --remote-debugging-port=0 \
+       --user-data-dir=$(mktemp -d) about:blank & pid=$!
+sleep 3; cat /proc/$pid/attr/current   # -> cdp-mcp-chromium (unconfined)
+kill $pid
+```
+
+If this prints `cdp-mcp-chromium (unconfined)`, the profile is attached. A bare
+`unconfined` means the binary path didn't match the profile's glob — re-check
+the cache path against the profile.
+
+## 5. Run L3
+
+```sh
+npm run test:e2e
+```
+
+With the sandbox on and the profile attached, the suite should pass, e.g.:
+
+```text
+Test Files  10 passed (10)
+Tests       29 passed (29)
+```
+
+## Fallback (before AppArmor is configured)
+
+The L3 harness adds `--no-sandbox` when `CI` is set, so you can run the suite
+without the profile as a lower-security stopgap:
+
+```sh
+env CI=1 npm run test:e2e
+```
+
+This keeps work moving, but the AppArmor profile is the desired long-term
+posture so that plain `npm run test:e2e` exercises sandbox-on Chromium. See
+[`chromium-sandboxing.md`](./chromium-sandboxing.md) for why `--no-sandbox`
+widens the blast radius of a compromised renderer.
+
+## Other distributions
+
+This profile work is Ubuntu-specific. Distributions that don't restrict
+unprivileged user namespaces by default (or use SELinux instead of AppArmor,
+e.g. Fedora) generally run sandbox-on Chromium without a host-side profile.
+Validate the actual host before assuming the Ubuntu steps are required — check
+`sysctl kernel.apparmor_restrict_unprivileged_userns` (absent or `0` means no
+AppArmor userns restriction to work around).
+
+## Related
+
+- [`docs/chromium-sandboxing.md`](./chromium-sandboxing.md) — the canonical
+  `--no-sandbox` / `sandbox: true` threat model, the AppArmor / userns / snap /
+  Bubblewrap mechanism map, and the validated-hosts table.
+- [`docs/known-chromium-gaps.md`](./known-chromium-gaps.md) — per-spec
+  Chromium-vs-Chrome gaps and host-OS workarounds.
+- [README §L3](../README.md) — browser selection, `CDP_TEST_BROWSER_PATH`, and
+  the per-platform support matrix.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-mcp",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Chrome DevTools Protocol MCP server — a TypeScript-aware frontend debugger for AI agents.",
   "license": "MIT",
   "author": "Leonard Janke",
@@ -28,11 +28,23 @@
     "cdp-mcp": "dist/index.js"
   },
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "import": "./dist/contract.js"
+    }
+  },
   "files": [
     "dist",
     "docs/launchd-service.md",
     "docs/systemd-service.md",
     "docs/chromium-sandboxing.md",
+    "docs/local-l3-e2e-setup.md",
     "docs/known-chromium-gaps.md"
   ],
   "scripts": {