playwright-write-guard 0.2.1 → 0.3.0

package/bin/suggest.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// playwright-write-guard-suggest: draft `allow` entries from an audit log. Reads one file, writes none.
+
+import { readFileSync } from 'node:fs';
+
+const USAGE = 'usage: playwright-write-guard-suggest <log.jsonl>';
+
+const args = process.argv.slice(2);
+let text;
+try {
+  if (args.length !== 1) throw new Error('usage');
+  text = readFileSync(args[0], 'utf8');
+} catch {
+  console.error(USAGE);
+  process.exit(1);
+}
+
+const KEPT = new Set(['observe', 'block', 'mocked']);
+const groups = new Map();
+for (const line of text.split(/\r\n|\r|\n/)) {
+  let e;
+  try {
+    e = JSON.parse(line);
+  } catch {
+    continue;
+  }
+  if (e === null || typeof e !== 'object' || typeof e.method !== 'string' || e.method === '') continue;
+  if (e.kind !== 'request' || !KEPT.has(e.action)) continue;
+  let u;
+  try {
+    u = new URL(e.url);
+  } catch {
+    continue;
+  }
+  const path = u.origin + u.pathname;
+  const key = JSON.stringify([e.method, path]);
+  const g = groups.get(key) ?? { method: e.method, path, count: 0, nextAction: false };
+  g.count++;
+  if (Array.isArray(e.headerNames) && e.headerNames.includes('next-action')) g.nextAction = true;
+  groups.set(key, g);
+}
+
+const rows = [...groups.values()].map((g) => ({
+  ...g,
+  url: '^' + g.path.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&') + '(?:[?#]|$)',
+}));
+// Code unit order, as Array.prototype.sort compares strings by default.
+rows.sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : a.method < b.method ? -1 : a.method > b.method ? 1 : 0));
+
+console.log(JSON.stringify({ allow: rows.map(({ method, url }) => ({ method, url })) }, null, 2));
+for (const g of rows) {
+  const hint = g.nextAction
+    ? ': carries next-action, pin its action IDs with a headers entry'
+    : g.path.endsWith('/graphql') ? ': GraphQL, add an anchored body pattern' : '';
+  console.error(`${g.count} x ${g.method} ${g.path}${hint}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-write-guard",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A read-only safety net for Playwright tests and AI browser agents: blocks writes at the network layer and refuses destructive clicks in the page.",
   "keywords": [
     "playwright",
@@ -47,7 +47,8 @@
     }
   },
   "bin": {
-    "playwright-write-guard-browser": "./bin/browser.mjs"
+    "playwright-write-guard-browser": "./bin/browser.mjs",
+    "playwright-write-guard-suggest": "./bin/suggest.mjs"
   },
   "files": [
     "src",

package/src/core.mjs

@@ -12,6 +12,7 @@
 export function compileConfig(raw) {
   const VERBS = ['save', 'delete', 'remove', 'publish', 'send', 'archive', 'pay', 'purchase',
     'log out', 'sign out', 'logout'];
+  const SUSPECT = '(?:^|[/._-])(?:(?:log|sign)[-_]?out|unsubscribe|confirm|delete|remove)(?:$|[/._?&#-])|[?&]action=';
   const fail = (path, message) => { throw new Error(`write-guard: ${path}: ${message}`); };
   const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
   const list = (v, path) => {
@@ -69,6 +70,14 @@ export function compileConfig(raw) {
   const parts = [...(cfg.defaultControls === false ? [] : [`\\b(?:${VERBS.join('|')})\\b`]),
     ...extra.map((s) => `(?:${s})`)];
 
+  if (cfg.defaultSuspectGets !== undefined && typeof cfg.defaultSuspectGets !== 'boolean') {
+    fail('defaultSuspectGets', 'must be a boolean');
+  }
+  const websocketWrites = list(cfg.websocketWrites, 'websocketWrites').map((s, i) => regex(s, `websocketWrites[${i}]`, ''));
+  const suspectGets = list(cfg.suspectGets, 'suspectGets');
+  suspectGets.forEach((s, i) => regex(s, `suspectGets[${i}]`, 'i'));
+  const suspectParts = [...(cfg.defaultSuspectGets === false ? [] : [SUSPECT]), ...suspectGets].map((s) => `(?:${s})`);
+
   return {
     policy,
     allow,
@@ -76,6 +85,8 @@ export function compileConfig(raw) {
     text: parts.length ? new RegExp(parts.join('|'), 'i') : null,
     icons: [...icons],
     websockets,
+    websocketWrites,
+    suspect: suspectParts.length ? new RegExp(suspectParts.join('|'), 'i') : null,
     log: cfg.log === undefined ? 'write-guard.jsonl' : cfg.log,
     logBodies: cfg.logBodies === true,
   };
@@ -104,6 +115,35 @@ export function decideRequest(request, config) {
     : { action: 'block', reason: `${what}; policy read-only` };
 }
 
+/**
+ * `block` (read-only) or `observe` (observe) for a string frame matching any `websocketWrites`
+ * pattern, else `allow`. A frame that is not a string is always `allow`. Runs only in Node.
+ */
+export function decideFrame(text, config) {
+  const hit = typeof text === 'string' ? config.websocketWrites.findIndex((re) => re.test(text)) : -1;
+  if (hit === -1) return { action: 'allow', reason: 'not a frame matching websocketWrites' };
+  const what = `frame matches websocketWrites[${hit}]`;
+  return config.policy === 'observe'
+    ? { action: 'observe', reason: `${what}; policy observe` }
+    : { action: 'block', reason: `${what}; policy read-only` };
+}
+
+/**
+ * `suspect: true` only for a GET or HEAD whose URL matches the compiled `suspect` pattern, tested
+ * by pathname plus search for an absolute URL and as given otherwise. Self-contained (injected into pages).
+ */
+export function decideSuspect(request, config) {
+  const method = String(request.method ?? '').toUpperCase();
+  const url = String(request.url ?? '');
+  if (method !== 'GET' && method !== 'HEAD') return { suspect: false, reason: `${method} is not a GET or HEAD` };
+  if (config.suspect === null) return { suspect: false, reason: 'no suspect pattern is configured' };
+  let tested = url;
+  try { const u = new URL(url); tested = u.pathname + u.search; } catch { /* relative or unparsable: tested as given */ }
+  return config.suspect.test(tested)
+    ? { suspect: true, reason: `${method} ${tested.slice(0, 80)} matches the suspect pattern` }
+    : { suspect: false, reason: `${method} ${tested.slice(0, 80)} matches no suspect pattern` };
+}
+
 /** `block` (read-only) or `observe` (observe) for a destructive control, else `allow`. */
 export function decideControl(control, config) {
   const label = String(control.label ?? '').trim();

package/src/fixture.mjs

@@ -1,25 +1,51 @@
 // playwright-write-guard/test: Playwright Test's `test` and `expect`, with every context guarded.
 //
-// The test's own context is guarded with `install` (which also locks context.request and
-// page.request under read-only). Worker-level locks refuse the Playwright APIs that would make
-// a context, a request client or a connection the guard cannot see (newContext, newPage,
-// request.newContext, the global fetch, and the launch and connect family) while a guarded test
-// or hook runs. Nothing else is refused: Node's own http, https and net are not seen.
-// Playwright's own creation of the test's context (and, under observe, of the request
-// fixture) is the one exception, and the window that allows it is shut again straight after.
+// The test's own context is guarded with `install`, which also judges each send through
+// context.request and page.request. The `request` fixture's sends are judged too: by the test's
+// guard in a test and its beforeEach and afterEach hooks, and with the config alone (recorded
+// nowhere) in beforeAll and afterAll. While the test's own function runs, Node's global fetch is
+// judged by the test's guard, and browser.newContext and browser.newPage return guarded contexts.
+// Worker-level locks refuse request.newContext and the launch and connect family while a guarded
+// test or hook runs, and newContext, newPage and fetch outside the test's own function. Node's
+// own http, https and net are not seen. Playwright's own creation of the test's context and of
+// the request fixture is the one exception, and the window that allows it is shut again straight
+// after.
 
 import { test as base, expect } from '@playwright/test';
 import { compileConfig } from './core.mjs';
-import { install, loadConfig } from './install.mjs';
+import { _judgeRequestClient, install, loadConfig } from './install.mjs';
 
 // Open only while Playwright builds this test's context, or its request fixture.
 let contextWindow = false;
 let requestWindow = false;
 
+// The running test's guard, its config, its testInfo and the guards of the contexts it made,
+// set while the `context` fixture is up.
+let current = null;
+
+// True while the test's own function runs: not a hook, not a fixture's setup or teardown.
+// Playwright 1.64 keeps the running step in a private field; anything else refuses.
+const inTestFunction = () => {
+  const r = current?.testInfo._timeoutManager?._running?.runnable;
+  return r?.type === 'test' && !r.fixture;
+};
+
 const refuse = (what) => new Error(
   `write-guard: ${what} is refused: it would make a context, request client or connection the guard cannot see. `
   + 'Drive the app through the test\'s own page and context.');
 
+const serviceWorkersError = (value) => new Error(
+  `write-guard: serviceWorkers is '${value}'; the guard needs 'block', or a service worker can send requests it never sees`);
+
+// A context made in the test's own function, guarded with the test's config before it is returned.
+async function guardedContext(newContext, options = {}) {
+  const { config, made } = current;
+  if (options.serviceWorkers !== undefined && options.serviceWorkers !== 'block') throw serviceWorkersError(options.serviceWorkers);
+  const context = await newContext({ ...options, serviceWorkers: 'block' });
+  made.push(await install(context, { ...config, log: null }));
+  return context;
+}
+
 export const test = base.extend({
   // The guard's config. Evaluated when a test first needs it, so a bad config file is that
   // test's error rather than a failure to load the file. `test.use` replaces it, used as given.
@@ -32,19 +58,27 @@ export const test = base.extend({
   // before the launch family is locked.
   _writeGuardWorker: [async ({ browser, playwright }, use) => {
     const restore = [];
-    const lock = (obj, name, label, open = () => false) => {
+    // `pass(original)` returns the function to call instead, or nothing to refuse.
+    const lock = (obj, name, label, pass = () => null) => {
       if (typeof obj?.[name] !== 'function') return;
-      const original = obj[name];
-      restore.push(() => { obj[name] = original; });
+      const original = obj[name].bind(obj);
+      const own = obj[name];
+      restore.push(() => { obj[name] = own; });
       obj[name] = async (...args) => {
-        if (open()) return original.apply(obj, args);
+        const call = pass(original);
+        if (call) return call(...args);
         throw refuse(label);
       };
     };
-    lock(browser, 'newContext', 'browser.newContext()', () => contextWindow);
-    lock(browser, 'newPage', 'browser.newPage()');
-    lock(playwright.request, 'newContext', 'request.newContext()', () => requestWindow);
-    lock(globalThis, 'fetch', 'fetch() (Node\'s own, from the test)');
+    lock(browser, 'newContext', 'browser.newContext()', (original) => {
+      if (contextWindow) return original;
+      return inTestFunction() ? (options) => guardedContext(original, options) : null;
+    });
+    // Playwright 1.64's newPage calls this.newContext, the guarded one above.
+    lock(browser, 'newPage', 'browser.newPage()', (original) => (inTestFunction() ? original : null));
+    lock(playwright.request, 'newContext', 'request.newContext()', (original) => (requestWindow ? original : null));
+    lock(globalThis, 'fetch', 'fetch() (Node\'s own, outside the test function)',
+      (original) => (inTestFunction() ? current.guard.guardFetch(original) : null));
     for (const type of [playwright.chromium, playwright.firefox, playwright.webkit]) {
       for (const method of ['launch', 'launchPersistentContext', 'launchServer', 'connect', 'connectOverCDP']) {
         lock(type, method, `${type.name()}.${method}()`);
@@ -74,31 +108,36 @@ export const test = base.extend({
     contextWindow = false;
     // install cannot change how the context was created; a project that asked for service
     // workers made a context the guard cannot fully see.
-    if (serviceWorkers !== 'block') {
-      throw new Error(`write-guard: serviceWorkers is '${serviceWorkers}'; the guard needs 'block', or a service worker can send requests it never sees`);
-    }
+    if (serviceWorkers !== 'block') throw serviceWorkersError(serviceWorkers);
     const guard = await install(context, { ...writeGuardConfig, log: null });
+    const made = [];
+    current = { guard, config: writeGuardConfig, testInfo, made };
     try {
       await use(context);
     } finally {
-      await testInfo.attach('write-guard.json', { body: JSON.stringify(await guard.close(), null, 2), contentType: 'application/json' });
+      current = null;
+      const attach = async (name, g) => testInfo.attach(name, { body: JSON.stringify(await g.close(), null, 2), contentType: 'application/json' });
+      await attach('write-guard.json', guard);
+      for (const [i, g] of made.entries()) await attach(`write-guard-${i + 2}.json`, g);
     }
   },
 
-  // Playwright builds the request fixture with request.newContext(), so under observe the
-  // window opens for that. Fixtures are set up in parameter order, so this one comes first.
-  // Under read-only this is where the fixture is refused, at setup, before anything is built.
-  _writeGuardRequestWindow: async ({ writeGuardConfig }, use) => {
-    if (compileConfig(writeGuardConfig).policy === 'read-only') {
-      throw new Error('write-guard: the request fixture is refused under read-only');
-    }
+  // Playwright builds the request fixture with request.newContext(), so the window opens for
+  // that. Fixtures are set up in parameter order, so this one comes first.
+  _writeGuardRequestWindow: async ({}, use) => {
     requestWindow = true;
     try { await use(); } finally { requestWindow = false; }
   },
 
-  request: async ({ _writeGuardRequestWindow, request }, use) => {
+  // Not dependent on `context`, which Playwright refuses in beforeAll and afterAll. Each call
+  // is judged by the guard of the moment: the test's while its context is up, else the config alone.
+  request: async ({ _writeGuardRequestWindow, request, writeGuardConfig, baseURL }, use) => {
     requestWindow = false;
-    await use(request);
+    const unrecorded = _judgeRequestClient(request, compileConfig(writeGuardConfig), { baseURL });
+    const client = () => (current ? current.guard.guardRequestClient(request, { baseURL }) : unrecorded);
+    await use(new Proxy(request, {
+      get: (obj, prop) => (typeof obj[prop] === 'function' ? (...args) => client()[prop](...args) : obj[prop]),
+    }));
   },
 });