cdp-toolkit 1.2.0 → 1.6.0

package/src/shared-tools.ts

@@ -3,7 +3,8 @@
  * (ADR-001), used by BOTH Chrome (via cdp/driver.ts's createCdpDriver()) and Firefox (via
  * bidi/driver.ts's createFirefoxDriver()). This file replaces the split that used to exist
  * between src/tools/*.ts (raw CDP, Chrome only) and src/neutral.ts (Driver-based, Firefox only)
- * for the 20 tools below.
+ * for 20 of the 23 tools below. The other three, the list_cookies/set_cookie/delete_cookies
+ * cookie group, landed here directly and never had a Chrome-only copy.
  *
  * THE HARD REQUIREMENT this file exists to satisfy: Chrome's return shape, timing, and quirks
  * stay byte-identical to what src/tools/*.ts produced before this migration: that already
@@ -33,12 +34,13 @@
  * behavior outranks the abstraction, these 7 stay two implementations; see the migration report.
  */
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type {
-  BrowserDriver, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
+  BrowserCookie, BrowserDriver, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
 } from "./driver.ts";
 import type { TargetSelector } from "./types.ts";
-import { assertLeaseOk, claimLease, leaseTtlMs, releaseLeaseFor, type LeaseBackend, type LeaseToken } from "./leases.ts";
+import { assertLeaseOk, claimLease, defaultLabel, leaseTtlMs, releaseLeaseFor, type LeaseBackend, type LeaseToken } from "./leases.ts";
+import { newTrackedPage, originIndex, type PageOrigin } from "./origins.ts";
 
 const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 const STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
@@ -133,21 +135,75 @@ function locatorOf(args: { uid?: DriverUid; selector?: string }): ElementLocator
 
 /* -------------------------------- pages (4) -------------------------------- */
 
-export async function listPages(driver: BrowserDriver, args: { all?: boolean } = {}): Promise<{ pages: PageInfo[]; count: number }> {
+/**
+ * A page listing entry, PageInfo plus provenance. STRICTLY ADDITIVE: {id, url,
+ * title, type} are unchanged in name, type and value, because consumers read
+ * them today.
+ */
+export interface ListedPage extends PageInfo {
+  /** "agent" when the creation ledger has a record for this target. Otherwise
+   *  "unknown", NEVER "human": the absence of a record is not proof that a
+   *  person opened the tab. See src/origins.ts. */
+  origin: PageOrigin;
+  /** The creating agent's label. Present only when origin is "agent". */
+  label?: string;
+  /** When this toolkit created the tab (epoch ms). Only when origin is "agent". */
+  createdAt?: number;
+  /** Present only when this target HAS a ledger record that could not be read:
+   *  the errno, or "unparseable". origin stays "unknown" because provenance is
+   *  genuinely unknown, but this field is what keeps an unreadable record from
+   *  being reported as a clean "nothing was ever recorded". */
+  originUnreadable?: string;
+}
+
+/**
+ * The reap set for the origin ledger: every target the browser currently has,
+ * INCLUDING non-page targets, regardless of what this call is listing.
+ *
+ * Using the filtered page list would be a bug with a plausible disguise: a
+ * default list_pages call drops workers and iframes, so reaping against it
+ * would delete the ledger record of any target that is alive but filtered out.
+ * Returning undefined (which listOrigins reads as "reap nothing") when the
+ * unfiltered listing fails is the same principle one step further: a failed
+ * enumeration must never be able to empty the ledger.
+ */
+async function reapSet(driver: BrowserDriver, pages: PageInfo[], all?: boolean): Promise<readonly string[] | undefined> {
+  if (all === true) return pages.map((p) => p.id);
+  try {
+    return (await driver.listPages({ all: true })).map((p) => p.id);
+  } catch {
+    return undefined;
+  }
+}
+
+export async function listPages(driver: BrowserDriver, args: { all?: boolean } = {}): Promise<{ pages: ListedPage[]; count: number }> {
   const pages = await driver.listPages({ all: args.all });
-  return { pages, count: pages.length };
+  // Never let provenance break the listing: originIndex does not throw, and a
+  // missing or unreadable ledger yields an empty map, so every page falls back
+  // to origin "unknown" exactly as a pre-ledger consumer always saw.
+  const ledger = await originIndex(backendOf(driver), await reapSet(driver, pages, args.all));
+  const annotated: ListedPage[] = pages.map((p) => {
+    const rec = ledger.get(p.id);
+    if (!rec) return { ...p, origin: "unknown" };
+    if (rec.unreadable !== undefined) return { ...p, origin: "unknown", originUnreadable: rec.unreadable };
+    return { ...p, origin: "agent", label: rec.label, createdAt: rec.createdAt };
+  });
+  return { pages: annotated, count: annotated.length };
 }
 
 export async function newPage(
   driver: BrowserDriver,
   args: { url?: string; claim?: boolean; label?: string; ttlMs?: number } = {},
 ): Promise<{ targetId: string; url: string; lease?: LeaseToken; label?: string; expiresAt?: number }> {
-  const p = await driver.newPage(args.url);
+  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
+  // Creates the tab AND writes its creation record. The record outlives any
+  // lease taken below, which is the point: a released tab is still an agent's.
+  const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label });
   if (args.claim !== true) return { targetId: p.id, url: p.url };
   // Atomic in the sense that matters: the tab is claimed before this call
   // returns, so no other agent can see it unclaimed and take it first.
   const { record, token } = await claimLease(backendOf(driver), p.id, {
-    label: typeof args.label === "string" && args.label.length ? args.label : `pid-${process.pid}`,
+    label,
     ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
   });
   return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
@@ -232,14 +288,261 @@ export const waitFor = waitForText;
 
 /* ------------------------------- evaluate (1) ------------------------------- */
 
+/**
+ * The `savePath` result shape. Deliberately carries NO form of the evaluated
+ * value: not the value, not a preview, not a truncation, not a byte prefix.
+ * The whole reason `savePath` exists is that the value may be a credential
+ * (a JWT or session token read out of localStorage), and anything this object
+ * carried would land in the caller's transcript, which is the exact leak the
+ * file sink is here to prevent. `type` is the JS typeof of the value ("null"
+ * for null), which describes the value without disclosing any of it.
+ */
+export interface EvaluateScriptSaveResult {
+  path: string;
+  bytes: number;
+  type: string;
+  target: { id: string; url: string; title: string };
+}
+
+/**
+ * Serialize an evaluated value for the file sink. `undefined` (an expression
+ * with no result) is written as JSON null rather than left unwritten, so the
+ * file always exists and always parses.
+ */
+function serializeForSink(value: unknown): string {
+  const json = JSON.stringify(value === undefined ? null : value, null, 2);
+  return json ?? "null";
+}
+
+/**
+ * THE file sink, shared by every tool that takes a `savePath`: serialize the
+ * value as JSON, write it, and report only where it went and how big it was.
+ * It returns no form of the value on purpose, so a caller of this helper
+ * cannot accidentally leak one back into a response.
+ *
+ * Path resolution matches take_heapsnapshot: an absolute path is used as-is, a
+ * relative one resolves under the artifact dir, and missing parent directories
+ * are created.
+ */
+async function writeJsonSink(savePath: string, value: unknown): Promise<{ path: string; bytes: number }> {
+  const path = savePath.startsWith("/") ? savePath : join(ARTIFACT_DIR, savePath);
+  await mkdir(dirname(path), { recursive: true });
+  const json = serializeForSink(value);
+  await writeFile(path, json, "utf8");
+  return { path, bytes: Buffer.byteLength(json, "utf8") };
+}
+
+/** True when a savePath argument actually asks for the sink. An empty string is
+ *  treated as absent, so the caller gets the value inline. */
+function sinkRequested(savePath?: string): savePath is string {
+  return savePath !== undefined && savePath !== "";
+}
+
 export async function evaluateScript(
   driver: BrowserDriver,
-  args: { target?: TargetSelector; expression: string; awaitPromise?: boolean; args?: unknown[] },
+  args: { target?: TargetSelector; expression: string; awaitPromise?: boolean; args?: unknown[]; savePath?: string },
 ): Promise<unknown> {
   if (typeof args.expression !== "string" || args.expression.length === 0) {
     throw new SharedToolError("evaluateScript: 'expression' must be a non-empty string");
   }
-  return withPage(driver, args.target, (page) => page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true }));
+  return withPage(driver, args.target, async (page) => {
+    const value = await page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true });
+    // No savePath: byte-identical to the pre-sink behavior, the value itself.
+    // A thrown page-side exception never reaches here, so it still surfaces as
+    // an error rather than being written into the file.
+    if (!sinkRequested(args.savePath)) return value;
+
+    const { path, bytes } = await writeJsonSink(args.savePath, value);
+    const result: EvaluateScriptSaveResult = {
+      path,
+      bytes,
+      type: value === null ? "null" : typeof value,
+      target: target3(page.info),
+    };
+    return result;
+  });
+}
+
+/* -------------------------------- cookies (1) -------------------------------- */
+
+/**
+ * The `savePath` result shape for list_cookies. Same rule as
+ * EvaluateScriptSaveResult: NO cookie value in any form, not even a prefix. A
+ * session cookie IS the credential, so a preview of one is a leaked one.
+ * `count` is how many cookies were written, which tells a caller the read
+ * worked without disclosing anything about what it read.
+ */
+export interface ListCookiesSaveResult {
+  path: string;
+  bytes: number;
+  count: number;
+  target: { id: string; url: string; title: string };
+}
+
+export interface ListCookiesResult {
+  cookies: BrowserCookie[];
+  count: number;
+  target: { id: string; url: string; title: string };
+}
+
+/**
+ * Cookie domain matching for the `domain` filter, deliberately small.
+ *
+ * A cookie's own domain carries a leading dot when it was set for subdomains
+ * (".example.test") and none when it was host-only ("example.test"), and a
+ * caller who types "example.test" means both. So the comparison strips a
+ * leading dot from each side and then accepts an exact match or a subdomain of
+ * the filter ("app.example.test" matches "example.test"). That is the whole
+ * rule: no wildcards, no patterns, no query language.
+ */
+function cookieDomainMatches(cookieDomain: string, filter: string): boolean {
+  const bare = (d: string) => (d.startsWith(".") ? d.slice(1) : d).toLowerCase();
+  const c = bare(cookieDomain);
+  const f = bare(filter);
+  return c === f || c.endsWith(`.${f}`);
+}
+
+/** Apply the optional name/domain filters. Exported for the unit tests, which
+ *  can then check the matching rule without standing up a browser. */
+export function filterCookies(cookies: readonly BrowserCookie[], filter: { domain?: string; name?: string }): BrowserCookie[] {
+  return cookies.filter((c) => {
+    if (filter.name !== undefined && filter.name !== "" && c.name !== filter.name) return false;
+    if (filter.domain !== undefined && filter.domain !== "" && !cookieDomainMatches(c.domain, filter.domain)) return false;
+    return true;
+  });
+}
+
+/**
+ * Read the cookies of the target page, httpOnly ones included.
+ *
+ * This is the one read that a page script cannot do: document.cookie omits
+ * every httpOnly cookie by design, which is precisely the set a session
+ * credential lives in. Both drivers answer over the protocol's own cookie
+ * store, so the flags come from the browser rather than being inferred.
+ *
+ * With `savePath` set the cookie array is written to that file as JSON and the
+ * response carries only {path, bytes, count, target}: no value, no preview, no
+ * truncation. Without it, the cookies are returned inline.
+ */
+export async function listCookies(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; domain?: string; name?: string; savePath?: string } = {},
+): Promise<ListCookiesResult | ListCookiesSaveResult> {
+  return withPage(driver, args.target, async (page) => {
+    const all = await page.getCookies();
+    const cookies = filterCookies(all, { domain: args.domain, name: args.name });
+    if (!sinkRequested(args.savePath)) {
+      return { cookies, count: cookies.length, target: target3(page.info) };
+    }
+    const { path, bytes } = await writeJsonSink(args.savePath, cookies);
+    return { path, bytes, count: cookies.length, target: target3(page.info) };
+  });
+}
+
+export interface SetCookieResult {
+  set: true;
+  target: { id: string; url: string; title: string };
+}
+
+export interface DeleteCookiesResult {
+  deleted: true;
+  target: { id: string; url: string; title: string };
+}
+
+/**
+ * THE site constraint both write tools share: a cookie has to be attributed to
+ * a site, and `url` or `domain` is how a caller says which.
+ *
+ * Checked here, above the drivers, so the refusal is ONE message on both
+ * backends rather than a CDP protocol error on one and a Firefox no-op on the
+ * other. It throws rather than defaulting to the current page's origin: a
+ * guessed domain writes a real cookie somewhere the caller did not name, and a
+ * cookie written to the wrong site is worse than a call that failed loudly.
+ *
+ * Exported for the unit tests, which pin the message without a browser.
+ */
+export function assertCookieSite(
+  args: { url?: string; domain?: string },
+  toolName: string,
+): void {
+  const hasUrl = args.url !== undefined && args.url !== "";
+  const hasDomain = args.domain !== undefined && args.domain !== "";
+  if (!hasUrl && !hasDomain) {
+    throw new Error(`${toolName} requires either 'url' or 'domain': a cookie has to be attributed to a site, and neither was given.`);
+  }
+}
+
+/** The shared 'name' check. A write tool with no name has nothing to write and
+ *  a delete tool with no name would match every cookie, so an empty one is
+ *  refused rather than treated as absent. */
+function assertCookieName(name: string | undefined, toolName: string): asserts name is string {
+  if (name === undefined || name === "") {
+    throw new Error(`${toolName} requires a non-empty 'name'.`);
+  }
+}
+
+/**
+ * Write one cookie into the target page's cookie store.
+ *
+ * The response is deliberately tiny: `{set: true, target}`. It does NOT echo
+ * the value back, because the value is frequently the credential and a caller
+ * who just supplied it does not need it repeated into their transcript. The
+ * `set: true` is earned rather than assumed: the CDP driver throws on Chrome's
+ * `{success:false}` refusal and the BiDi driver throws when it cannot derive
+ * the domain BiDi requires, so reaching this line means a backend confirmed
+ * the write.
+ */
+export async function setCookie(
+  driver: BrowserDriver,
+  args: {
+    target?: TargetSelector; name: string; value: string; url?: string; domain?: string;
+    path?: string; expires?: number; httpOnly?: boolean; secure?: boolean;
+    sameSite?: "strict" | "lax" | "none" | "default";
+  },
+): Promise<SetCookieResult> {
+  assertCookieName(args.name, "set_cookie");
+  if (typeof args.value !== "string") throw new Error("set_cookie requires a string 'value'.");
+  assertCookieSite(args, "set_cookie");
+  return withPage(driver, args.target, async (page) => {
+    await page.setCookie({
+      name: args.name,
+      value: args.value,
+      ...(args.url !== undefined ? { url: args.url } : {}),
+      ...(args.domain !== undefined ? { domain: args.domain } : {}),
+      ...(args.path !== undefined ? { path: args.path } : {}),
+      ...(args.expires !== undefined ? { expires: args.expires } : {}),
+      ...(args.httpOnly !== undefined ? { httpOnly: args.httpOnly } : {}),
+      ...(args.secure !== undefined ? { secure: args.secure } : {}),
+      ...(args.sameSite !== undefined ? { sameSite: args.sameSite } : {}),
+    });
+    return { set: true as const, target: target3(page.info) };
+  });
+}
+
+/**
+ * Remove the named cookie from the target page's cookie store.
+ *
+ * `{deleted: true, target}` and NO count, on purpose. Neither protocol reports
+ * how many cookies it removed, so any number here would be invented; a caller
+ * who needs one reads list_cookies before and after. `deleted: true` means the
+ * backend accepted and performed the deletion, not that a matching cookie
+ * existed: deleting an absent cookie is a success on both backends.
+ */
+export async function deleteCookies(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; name: string; url?: string; domain?: string; path?: string },
+): Promise<DeleteCookiesResult> {
+  assertCookieName(args.name, "delete_cookies");
+  assertCookieSite(args, "delete_cookies");
+  return withPage(driver, args.target, async (page) => {
+    await page.deleteCookies({
+      name: args.name,
+      ...(args.url !== undefined ? { url: args.url } : {}),
+      ...(args.domain !== undefined ? { domain: args.domain } : {}),
+      ...(args.path !== undefined ? { path: args.path } : {}),
+    });
+    return { deleted: true as const, target: target3(page.info) };
+  });
 }
 
 /* -------------------------------- snapshot (1) -------------------------------- */
@@ -440,7 +743,7 @@ export async function handleDialog(
 
 /* ------------------------------------- registry ------------------------------------- */
 
-/** The 20 tools this file unifies, importable by both src/index.ts (Chrome) and
+/** The 23 tools this file unifies, importable by both src/index.ts (Chrome) and
  *  src/firefox-tools.ts (Firefox). Each function is (driver, args) => Promise<result>. */
 export const SHARED_TOOLS = {
   list_pages: listPages,
@@ -450,6 +753,9 @@ export const SHARED_TOOLS = {
   navigate_page: navigatePage,
   wait_for: waitForText,
   evaluate_script: evaluateScript,
+  list_cookies: listCookies,
+  set_cookie: setCookie,
+  delete_cookies: deleteCookies,
   take_snapshot: takeSnapshot,
   click,
   hover,