@ai-ecoverse/slicc-browsers 1.21.1 → 1.22.1

package/README.md

@@ -183,9 +183,9 @@ It also offers `storageKey(key)` and `unparseable(text)`. A Go or Rust implement
 
 ## Guard vectors
 
-A guard sits between a CDP client, such as an agent's browser tool, and the browser, and keeps the client away from protected origins. `guard-vectors.json` holds more than a hundred attacks on that promise, and every guard must pass them all. They cover navigation, redirect chains, popups, frames, request interception, cookies, storage, privileged and error pages, foreign extension worlds, debugger tricks and session overrides that would leak into a protected page.
+A guard sits between a CDP client and the browser and keeps the client away from protected origins. `guard-vectors.json` holds the attacks every guard must pass: navigation, redirects, popups, frames, interception, cookies, storage, privileged and error pages, foreign worlds, debugger tricks and session overrides.
 
-Each vector runs twice. The **control** runs it against an ordinary origin, where it must work. The **guarded** leg runs it through the guard against a protected target, where it must be refused or have no effect. A **liveness** check, made outside the guard, proves the protected target was really there. A row passes only when all three do, so a guard can't pass by breaking everything, and a test can't pass by never reaching the target.
+Each vector runs twice. The **control** runs against an ordinary origin and must work. The **guarded** leg runs through the guard against a protected target and must be refused or have no effect. A **liveness** check outside the guard proves the target was really there. All three must pass.
 
 A guard may refuse every client navigation to an `about:` URL that inherits an origin, such as `about:blank`. Refusing an ordinary navigation away from a protected page still fails.
 
@@ -195,7 +195,7 @@ For stock Playwright, Puppeteer and raw CDP clients, a guard that declares `stoc
 - `Page.addScriptToEvaluateOnNewDocument` whose `source` matches `^(?:[ \t\n]|//[^\n\r\u2028\u2029]*)*$` on the whole string without the multiline flag (no code), with any `worldName` or `runImmediately`, and its removal;
 - exactly `Emulation.setFocusEmulationEnabled`, `setEmulatedMedia`, `setDeviceMetricsOverride` and `setTouchEmulationEnabled`;
 - `Page.createIsolatedWorld` on a frame the guard already classifies as ordinary: strip `grantUniveralAccess` and `contentSecurityPolicy`, return no `executionContextId` for any other frame; `Runtime.addBinding` scoped to such a world by a non-empty `executionContextName` or its `executionContextId`, with `Runtime.bindingCalled` only from those worlds;
-- `Target.setAutoAttach`: accept the call but narrow the filter to tab targets, hold pages under the tab like pages (same URL redaction in `targetInfo`); a transport that synthesizes it declares `syntheticAutoAttach`.
+- `Target.setAutoAttach`: either narrow the filter to tab targets or hide per target; no protected-origin page, iframe or worker (dedicated, shared or service) may reach the client; pages under the tab are held like pages (same URL redaction in `targetInfo`); a transport that synthesizes it declares `syntheticAutoAttach`.
 
 The strip holds whether or not a given Chrome lets that world reach another origin. Code init scripts, main-world bindings and other overrides stay refused or harmless. Admitted display overrides and no-code init scripts must not remain in effect on a protected document — refuse that navigation, or clear them before it runs. Undeclared, they skip, never pass.
 
@@ -223,7 +223,7 @@ await fixture.close();
 You supply:
 - **a guarded client** per row: your guard's CDP connection, with `send(method, params, sessionId)`, `waitEvent(predicate, ms)` and an `events` array;
 - **an unguarded observer**: a direct CDP connection to the same browser, which runs the controls and checks liveness;
-- **origins**: the fixture server reachable as seven, the vault and an ordinary site. Point the protected hostnames at it with Chrome's `--host-resolver-rules`, so no test ever touches the real seven;
+- **origins**: the fixture server reachable as seven, the vault and an ordinary site. Point the protected hostnames at it with Chrome's `--host-resolver-rules`, so tests never touch the real seven;
 - **capabilities**: what your transport can do. A row that needs something you don't declare is skipped as `not-supported:<capability>`.
 
 | capability | means the transport can |
@@ -239,6 +239,7 @@ You supply:
 | `siteIsolationOff`, `inboundDelay`, `forwardAudit` | no site isolation; hold inbound; audit forwarded commands |
 | `secureOrigin` | HTTPS origins (service workers) |
 | `stockSetup`, `syntheticAutoAttach` | admit stock clients' setup calls; synthesize auto-attach |
+| `closeProtected` | close a protected tab |
 
 ### Reading the result
 
@@ -248,13 +249,13 @@ Each row reports `control`, `guarded` and `live` as `pass`, `fail`, `skip`, `inc
 GUARD-PASS my-guard@1a2b3c4 (vectors @ai-ecoverse/slicc-browsers@1.18.5)
 ```
 
-The run passes only when every row passes and none is missing. A skip with a reason the runner would never give, such as a made-up capability, is reported as forged, and skipped and incomplete rows are counted on the line, so the line can't overstate what was tested.
+The run passes only when every row passes and none is missing. A skip with a reason the runner would never give is forged; skipped and incomplete rows are counted on the line, so it can't overstate what was tested.
 
 To find out what a vector checks, read it in `guard-vectors.json`: each one lists its steps, each observation's `means`, its `live` condition and its expected outcome. [`schema/guard-vectors.schema.json`](schema/guard-vectors.schema.json) defines the format.
 
 ## Development
 
-You need Go 1.26, Rust stable with the `wasm32-wasip1` target, Node 24 or later, and Chrome or Chromium for the browser tests: they take `CHROME_PATH`, or the Chrome for Testing that `npx slicc-cdp install-browser` installs, and run it headless unless `CI` is set (`SLICC_HEADLESS=1` or `0` overrides).
+You need Go 1.26, Rust stable with `wasm32-wasip1`, Node 24+, and Chrome or Chromium for the browser tests: they take `CHROME_PATH`, or Chrome for Testing from `npx slicc-cdp install-browser`, and run headless unless `CI` is set (`SLICC_HEADLESS=1` or `0` overrides).
 
 | command | what it does |
 | --- | --- |

package/fixture-server.mjs

@@ -105,6 +105,13 @@ function route(req, url, send, html, redirects) {
     '/csp': () => document(url, html),
     '/sw.js': () =>
       send(200, "self.addEventListener('install',()=>self.skipWaiting())", 'text/javascript'),
+    '/worker.js': () => send(200, 'onmessage=e=>postMessage(e.data)', 'text/javascript'),
+    '/shared-worker.js': () =>
+      send(
+        200,
+        'onconnect=e=>{e.ports[0].onmessage=m=>e.ports[0].postMessage(m.data)}',
+        'text/javascript'
+      ),
   };
   if (req.method === 'OPTIONS') return send(204, '');
   if (url.pathname.startsWith('/auth')) {

package/guard-driver.mjs

@@ -197,7 +197,9 @@ export function judge(vector, side, observed) {
   }
   const skipped = Object.keys(want).filter(
     (k) =>
-      (observed?.[k] === 'not-supported' && vector.observe?.[k]?.requires?.length > 0) ||
+      (observed?.[k] === 'not-supported' &&
+        ((vector.observe?.[k]?.requires?.length ?? 0) > 0 ||
+          (vector.observe?.[k]?.unless?.length ?? 0) > 0)) ||
       (vector.observe?.[k]?.dependsOn ?? []).some((d) => refused.includes(d))
   );
   const incomplete = Object.keys(want).filter(
@@ -310,7 +312,9 @@ const capabilities = (value) =>
     ? value.flatMap(capabilities)
     : value && typeof value === 'object'
       ? Object.entries(value).flatMap(([key, item]) =>
-          key === 'requires' && Array.isArray(item) ? item : capabilities(item)
+          (key === 'requires' || key === 'unless') && Array.isArray(item)
+            ? item
+            : capabilities(item)
         )
       : [];
 
@@ -389,6 +393,17 @@ function skipWhy(vector, row, known, guard, declared) {
   return `skip with a reason the runner never gives: ${reason}`;
 }
 
+function observationWhy(vector, row, declared) {
+  return (row.notSupported ?? []).flatMap((name) => {
+    const observation = vector?.observe?.[name];
+    if (!observation) return [`not-supported observation ${name} the vector lacks`];
+    const missing = (observation.requires ?? []).some((cap) => !declared.includes(cap));
+    const unless = (observation.unless ?? []).some((cap) => declared.includes(cap));
+    if (missing || unless) return [];
+    return [`not-supported:${name} while the observation should run`];
+  });
+}
+
 function forgeries(set, results, guard, capabilitiesList) {
   const vectors = new Map(set.vectors.map((v) => [v.id, v]));
   const declared = declaredCapabilities(capabilitiesList);
@@ -405,6 +420,7 @@ function forgeries(set, results, guard, capabilitiesList) {
     if (legs.includes('not-run') && vector?.kind !== 'text')
       why.push('not-run on a vector that is not kind text');
     if (legs.includes('skip')) why.push(skipWhy(vector, row, known, guard, declared));
+    why.push(...observationWhy(vector, row, declared));
     const found = why.filter(Boolean);
     if (!found.length) return [];
     const { id, target, variant, transport } = row;