@ai-ecoverse/slicc-browsers 1.6.0 → 1.7.0

package/README.md

@@ -237,6 +237,121 @@ It exports:
 - every `{name}` is in `placeholders`;
 - no URL uses a port from 9222 to 9229.
 
+## Reference runner
+
+`guard-runner.mjs` is dependency-free browser ESM. `run(set, options)` returns
+`{ results, summary(metadata) }`; the module also exports `summary`. Results have
+`id`, `target`, `variant`, `control`, `guarded`, `live`, boolean observations and
+errors. Statuses are `pass`, `fail`, `skip` and `not-run`. Text vectors are reported
+as `not-run`; they are not silently certified. A missing observation check is an
+error before execution.
+
+Supply a CDP client with `send(method, params, sessionId): Promise<object>`,
+`waitEvent(predicate, milliseconds): Promise<event>` and an append-only `events`
+array of `{ method, params, sessionId }`. Rejections should expose the protocol
+error as `error.cdp`, or an error message. `client` carries the guarded leg;
+`unguarded`, when supplied, carries unguarded controls and observation reads.
+There is no fallback from observer reads to the guarded client. A bare client
+means guarded transport only; rows requiring an observer report
+`skip` with `not-supported:unguarded-observer`, counted in `summary().observerSkipped`.
+`clientFactory({ variant, detachDelay, vector, target, slot })` is called per row
+and may return either a client or `{ client, unguarded, close, transportVariant }`.
+The factory can configure the guard's own transport delay from this metadata;
+the runner never reaches into the guard. `transportVariant: true` acknowledges
+that configuration, and every result records that boolean (false by default).
+`slot` allows pooling browsers while keeping each row's clients independent.
+The optional `close` releases the row's clients; release pooled browsers after
+`run` completes. Each parallel slot needs an independent browser for
+browser-wide settings. Without a factory execution is serial. Cookie and storage
+rows use fresh browser contexts when `capabilities.browserContexts` is true;
+otherwise they run serially. `capabilities` is an object of booleans or an array
+of supported names. `capabilities.scope` selects owner-specific rows.
+
+Map `ordinary`, `ordinary-same-site`, `seven`, `vault`, `vault-x`, `apex`, `own`
+and `client` to origins. Optionally map `plain`, `cross` and `log`; their defaults
+are `ordinary`, `client` and `ordinary`. Origins must preserve the site
+relationships of the data. Tags and cookie names are unique per leg. `variant`
+selects one variant or an array; omission selects all. `parallel` defaults to 1.
+`log(row)` receives completed rows. A variant supplies the wait before an
+explicit `Target.detachFromTarget` step and for a `settle.variant` step.
+
+Every runnable vector has a declarative `liveCheck`; every observation has a
+declarative `check`. Each check declares its `observer`: `fixture` reads request
+logs, `client` reads already-delivered transport data, and `unguarded` requires
+an independent CDP observer. `all` needs the observers for every operand; `any`
+can use an available fixture or client alternative without an unguarded observer.
+Unavailable optional observer alternatives are false, never substituted with guarded reads.
+Checks include: `beacon`, `served`, `header` with
+`on`, `event` with `where`, `result` with `path` and `equals`, `cookie` with `from`,
+`compare`, `refused`, `reached`, `attached`, `delivered`, `title`, `expression`,
+`hops` (each exact nested redirect URL), `detached`, `loaded`, `pre`, `blocked`,
+`registration`, `state` and `filtered`. The diagnostic `executed` and `live`
+checks are not valid liveness proofs.
+Compose checks with `all`, `any` or `not`. Predicates support nested partial
+objects, `$contains`, `$regex`, `$some`, nonempty `$every`, and `$encoded` with
+`{ value, prefix }` for a base64-encoded value with an optional prefix. Reads of titles and
+expressions use the unguarded observer. A `refused` check can declare `refusal.match` to match protocol errors. Transport timeouts, timeout sentinel values and evaluation exceptions fail result,
+comparison and observer-read
+observations; they are never comparable values. Registration refusals must match the
+step's declared expression; dependent observations are omitted and reported by
+the existing result evaluator.
+
+`liveCheck` applies only to the guarded leg. Controls are judged by their positive
+observations: a missing or failing effect fails the control. Guarded liveness
+requires the exact target URL in the fixture log or a target-origin `/live`
+heartbeat; alternatively a pre-action `/live?tag=...&step=pre&to=...` request and
+an exact-URL block/error from the client or unguarded frame tree. An error for a
+different URL is not evidence. A declared setup refusal can supply liveness only
+when its `refusal.match` matched. Transport connectivity and command completion
+alone never prove liveness. Cookie and storage rows seed a canary outside the
+guard and read it back outside the guard; refused writes require unchanged
+canary state and a refusal or filtered call response. Their control can clear or
+modify state as required by its positive observations. `C5.auth` and
+`C5.guessed-id.continue-with-auth` use fixture Authorization logs and refusal of
+candidate auth ids; `C5.auth` also checks delivered auth events. Their liveness
+requires an auth request at the fixture, not a completed fetch. Neither uses a
+plain-tab baseline: headless Chromium can leave a credentials-including fetch
+to a Basic 401 pending even without an attached client.
+
+Beacon settlement uses only requests recorded after the page action starts. For
+redirect chains it also requires the exact final destination request in the
+fixture log. A setup beacon on the same origin and tag cannot settle an unfinished
+redirect chain. This does not change the observations used to judge either leg.
+
+The separately exported Node module `@ai-ecoverse/slicc-browsers/fixture` exposes
+`fixtureServer({ host, port })`, defaulting to a random loopback port. It returns
+`origin`, `port`, `log()`, `reset()` and `close()`. Log entries contain `url`,
+`method`, `headers` and `time`. Mirror that API when using another fixture.
+The server serves document, frame, redirect, CSP, authentication, data, image,
+canary and beacon paths. Configure host resolution in your test browser, not in
+the runner. `npm run test:guard` exercises Chromium twice with no guard, one target per
+invocation: controls must pass and guarded expectations must fail. For a single
+target use `GUARD_TARGET=seven npm run test:guard-target`. The fixture also serves
+`/live` image requests from stand-in documents, independently of injected code.
+
+```js
+import set from '@ai-ecoverse/slicc-browsers/guard-vectors.json' with { type: 'json' };
+import { run } from '@ai-ecoverse/slicc-browsers/guard-runner';
+import { fixtureServer } from '@ai-ecoverse/slicc-browsers/fixture';
+const fixture = await fixtureServer();
+const targets = await configureTestOrigins(fixture.port);
+const capabilities = {
+  autoAttach: true,
+  browserSession: true,
+  browserContexts: true,
+};
+const execution = await run(set, {
+  clientFactory: (metadata) => connectGuardAndObserver(metadata),
+  targets,
+  capabilities,
+  variant: ['prompt', 'lagging'],
+  parallel: 6,
+  fixture,
+});
+console.log(execution.summary({ guard: 'my-guard', sha: 'build-sha' }));
+await fixture.close();
+```
+
 ## The process source
 
 The process scan finds browsers started with a debugging port by something else:

package/fixture-server.mjs

@@ -0,0 +1,126 @@
+import { createServer } from 'node:http';
+
+const tall = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+  'base64'
+);
+const escape = (value) =>
+  value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;');
+
+function document(url, html) {
+  const p = url.searchParams;
+  const csp = p.has('csp') || url.pathname === '/csp';
+  return html(
+    'doc',
+    `<p>document ${escape(p.get('n') ?? '')}</p>${csp ? '<script>document.title="inline"; document.body.dataset.inline="true"</script>' : ''}`,
+    csp ? { 'content-security-policy': "script-src 'none'" } : {}
+  );
+}
+
+function trigger(p) {
+  const kind = p.get('k') ?? '';
+  const to = p.get('to') ?? '';
+  const frame = kind === 'iframe' ? `<iframe src="${escape(to)}"></iframe>` : '';
+  return `<p>trigger</p><button onclick="go()">Go</button>${frame}<script>const to=${JSON.stringify(to)};function go(){const k=${JSON.stringify(kind)};if(k==='href'||k==='deferred')location.href=to;if(k==='replace')location.replace(to);if(k==='popup')window.open(to);if(k==='form'){const u=new URL(to);const f=document.createElement('form');f.action=u.origin+u.pathname;for(const [name,value] of u.searchParams){const i=document.createElement('input');i.type='hidden';i.name=name;i.value=value;f.append(i);}document.body.append(f);f.submit();}return 'went';}${kind === 'deferred' ? `setTimeout(go,${Number(p.get('defer') ?? 3000)});` : ''}</script>`;
+}
+
+function route(req, url, send, html) {
+  const p = url.searchParams;
+  const routes = {
+    '/beacon': () => send(204, ''),
+    '/hop': () =>
+      send(Number(p.get('code') ?? 302), 'moved', 'text/plain', { location: p.get('to') ?? '/' }),
+    '/data': () => send(200, `real-${p.get('n') ?? ''}`, 'text/plain'),
+    '/live': () => send(200, tall, 'image/png'),
+    '/img': () => send(200, tall, 'image/png'),
+    '/script': () =>
+      send(
+        200,
+        `globalThis.vectorScript=${JSON.stringify(`real-${p.get('n') ?? ''}`)}`,
+        'text/javascript'
+      ),
+    '/page': () => html('trigger', trigger(p)),
+    '/api/cookies': () => send(200, req.headers.cookie ?? 'none', 'text/plain'),
+    '/plant': () =>
+      html('plant', '<script>localStorage.setItem("canary","planted")</script>', {
+        'set-cookie': [`canary=planted-${url.hostname}; Path=/`, 'del=1; Path=/'],
+      }),
+    '/rewritten': () => html('rewritten', '<p>REWRITTEN</p>'),
+    '/framed': () => {
+      const to = p.get('url') ?? 'about:blank';
+      const log = p.get('log') ?? url.origin;
+      const pre = `${log}/live?tag=${encodeURIComponent(p.get('tag') ?? '')}&step=pre&to=${encodeURIComponent(to)}`;
+      return html(
+        'framed',
+        `<script>navigator.sendBeacon(${JSON.stringify(pre)})</script><iframe src="${escape(to)}"></iframe>`
+      );
+    },
+    '/doc': () => document(url, html),
+    '/csp': () => document(url, html),
+  };
+  if (req.method === 'OPTIONS') return send(204, '');
+  if (url.pathname.startsWith('/auth')) {
+    if (req.headers.authorization === 'Basic dTpw') return send(200, 'authed', 'text/plain');
+    return send(401, 'unauthorized', 'text/plain', {
+      'www-authenticate': `Basic realm="${escape(url.pathname)}"`,
+    });
+  }
+  if (url.pathname.startsWith('/canary'))
+    return html(
+      'canary',
+      `<p data-canary="${escape(p.get('value') ?? 'planted')}">canary-marker ${escape(url.host)}</p>`
+    );
+  const handler = routes[url.pathname];
+  if (handler) return handler();
+  return send(404, 'missing', 'text/plain');
+}
+
+export async function fixtureServer({ host = '127.0.0.1', port = 0 } = {}) {
+  let entries = [];
+  const server = createServer((req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    entries.push({
+      url: url.href,
+      method: req.method,
+      headers: { ...req.headers },
+      time: Date.now(),
+    });
+    const p = url.searchParams;
+    const cors = {
+      'access-control-allow-origin': req.headers.origin ?? '*',
+      'access-control-allow-credentials': 'true',
+      'access-control-allow-headers': '*',
+      'access-control-allow-methods': 'GET, POST, OPTIONS',
+    };
+    const send = (code, body, type = 'text/html', headers = {}) => {
+      res.writeHead(code, { 'content-type': `${type}; charset=utf-8`, ...cors, ...headers });
+      res.end(body);
+    };
+    const html = (title, body = '', headers = {}) =>
+      send(
+        200,
+        `<!doctype html><meta charset="utf-8"><title>${title}</title>${body}<img hidden src="/live?tag=${encodeURIComponent(p.get('tag') ?? p.get('n') ?? p.get('case') ?? p.get('value') ?? '')}&to=${encodeURIComponent(url.href)}">`,
+        'text/html',
+        headers
+      );
+    route(req, url, send, html);
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, resolve);
+  });
+  const address = server.address();
+  return {
+    port: address.port,
+    origin: `http://${host}:${address.port}`,
+    log: () => structuredClone(entries),
+    reset: () => {
+      entries = [];
+    },
+    close: () =>
+      new Promise((resolve, reject) => {
+        server.closeAllConnections();
+        server.close((error) => (error ? reject(error) : resolve()));
+      }),
+  };
+}