@ai-ecoverse/slicc-browsers 1.5.0 → 1.7.0

package/README.md

@@ -4,7 +4,7 @@ The browser catalog, JSON schemas and conformance corpus shared by the two progr
 - `slicc browsers` and `slicc launch` in [slicc-cli](https://github.com/ai-ecoverse/slicc-cli) (Go, `CGO_ENABLED=0`);
 - `playwright-cli list` and `open` in [slicc-cdp](https://github.com/ai-ecoverse/slicc-cdp) (Rust, also built for `wasm32-wasip1`).
 
-It also holds the [protected origins](#protected-origins): the origins browser control must never reach, which slicc-agent checks too.
+It also holds the [protected origins](#protected-origins): the origins browser control must never reach, which slicc-agent checks too. It also holds the [guard vectors](#guard-vectors), which every CDP guard runs: bios, slicc-cdp, slicc-extension and slicc-cli.
 
 They can't share code, so they share data. Three packages wrap the same files, at one version:
 
@@ -24,6 +24,8 @@ They can't share code, so they share data. Three packages wrap the same files, a
 | `corpus.json` | every case in one file, generated from `corpus/` by `npm run corpus` |
 | `protected.json`, `schema/protected.schema.json` | the protected-origin test vectors and their schema |
 | `protected.mjs` | the reference protected-origin matcher, in JavaScript (npm only) |
+| `guard-vectors.json`, `schema/guard-vectors.schema.json` | the guard vectors and their schema |
+| `guard-driver.mjs` | the guard vectors' beacon and canary helpers, in JavaScript (npm only) |
 
 ## Go
 
@@ -38,6 +40,7 @@ b, ok := c.Browser("chrome")
 - `(*Catalog).Browser(id)` and `(*Catalog).Priority(id)`, the index in `browsers` (its length for an unknown id).
 - `CatalogJSON()`, `CatalogSchemaJSON()`, `BrowsersSchemaJSON()`, `CorpusJSON()`, `ProtectedJSON()` and `ProtectedSchemaJSON()` return copies of the embedded files.
 - `(*Catalog).ProtectedOrigins` is `catalog.json`'s `protectedOrigins`. `Protected() (*ProtectedVectors, error)` parses `protected.json` (`Origins`, `URLs`, `Targets`, `CookieDomains`, `StorageKeys`; a target's `Opener` is `""`, `OpenerProtected`, `OpenerUnprotected` or `OpenerUnknown`).
+- `Guard() (*GuardVectors, error)` parses `guard-vectors.json`; `GuardVectorsJSON()` and `GuardVectorsSchemaJSON()` return copies of the files. `Guard()` parses it into `SchemaVersion`, `SetVersion`, `Targets`, `Variants`, `Capabilities`, `Placeholders` and `Vectors`. A `GuardExpected` is `Checks` (names to booleans) or `Text`, and a `GuardObservation` is `Means`, `DependsOn` and `Requires`. The `GuardTarget*`, `GuardOrdinary`, `GuardSameSite`, `GuardKind*`, `GuardVia*`, `GuardScopeAny`, `GuardControl`, `GuardGuarded`, `GuardCap*` and `GuardSession*` constants name the values.
 - `Corpus() ([]Case, error)` returns the cases. See [Running the corpus](#running-the-corpus) for the helpers.
 
 ## Rust
@@ -50,15 +53,17 @@ slicc-browsers = "1"
 slicc-browsers = { version = "1", features = ["corpus"] }
 ```
 
-- Always: `CATALOG`, `CATALOG_SCHEMA`, `BROWSERS_SCHEMA`, `CORPUS_SCHEMA` and `PROTECTED_SCHEMA`, each the file's text via `include_str!`, and `SCHEMA` (1). No dependencies.
+- Always: `CATALOG`, `CATALOG_SCHEMA`, `BROWSERS_SCHEMA`, `CORPUS_SCHEMA`, `PROTECTED_SCHEMA` and `GUARD_VECTORS_SCHEMA`, each the file's text via `include_str!`, and `SCHEMA` (1). No dependencies.
 - Feature `serde`: `Catalog` and the other types (`protected_origins` is a `ProtectedOrigins`), `Catalog::parse(&str)`, `catalog()` (parses `CATALOG`), `Catalog::browser` and `Catalog::priority`. It pulls in `serde` and `serde_json`.
-- Feature `corpus` (implies `serde`): `CORPUS` and `PROTECTED`, the text of `corpus.json` and `protected.json`; the module `corpus` with `corpus()`, `Case`, `Layout` and the helpers below; and the module `protected` with `vectors()`, `Vectors` and the `OPENER_*` constants. Use it from `[dev-dependencies]` only; with resolver 2 it stays out of normal builds.
+- Feature `corpus` (implies `serde`): `CORPUS`, `PROTECTED` and `GUARD_VECTORS`, the text of `corpus.json`, `protected.json` and `guard-vectors.json`; the module `corpus` with `corpus()`, `Case`, `Layout` and the helpers below; the module `protected` with `vectors()`, `Vectors` and the `OPENER_*` constants; and the module `guard` with `vectors()`, `Vectors`, `Vector`, `Step`, `Observation`, `Expected` (`Checks` or `Text`), and the `TARGET_*`, `ORDINARY*`, `KIND_*`, `VIA_*`, `SCOPE_ANY`, `CONTROL`, `GUARDED`, `CAP_*` and `SESSION_*` constants. Use it from `[dev-dependencies]` only; with resolver 2 it stays out of normal builds.
 
 Every feature builds for `wasm32-wasip1`.
 
 ## npm
 
-`import catalog from '@ai-ecoverse/slicc-browsers' with { type: 'json' }`. The exports are `.` (`catalog.json`), `./catalog.json`, `./corpus.json`, `./protected.json`, `./protected.mjs`, `./schema/catalog.schema.json`, `./schema/browsers.schema.json`, `./schema/corpus.schema.json` and `./schema/protected.schema.json`.
+`import catalog from '@ai-ecoverse/slicc-browsers' with { type: 'json' }`. The exports are `.` (`catalog.json`), `./catalog.json`, `./corpus.json`, `./protected.json`, `./protected.mjs`, `./guard-vectors.json`, `./guard-driver.mjs`, `./schema/catalog.schema.json`, `./schema/browsers.schema.json`, `./schema/corpus.schema.json`, `./schema/protected.schema.json` and `./schema/guard-vectors.schema.json`.
+
+`guard-driver.mjs` is described under [Guard vectors](#guard-vectors).
 
 `protected.mjs` is the reference matcher for [protected origins](#protected-origins): `import { protectedOrigins } from '@ai-ecoverse/slicc-browsers/protected.mjs'`, then `protectedOrigins(catalog.protectedOrigins, extraOrigins)` returns `{ url(text), target({ url, previous, opener }), cookieDomain(domain), storageKey(key) }`, each a boolean. It needs only the WHATWG `URL`, so it runs in Node and in a browser.
 
@@ -123,6 +128,230 @@ A same-site frame shares its parent's process and has no target of its own. Ever
 
 **`protected.json`** (schema `schema/protected.schema.json`): `origins`, the extra origins every vector runs with; `urls` (`url`, `protected`); `targets` (`url`, `previous?`, whether the target was protected before; `opener?`, `protected`, `unprotected` or `unknown`, and no `opener` for a target without one; `protected`); `cookieDomains` (`domain`, `protected`); `storageKeys` (`key`, `protected`). `npm run validate` runs every vector through `protected.mjs`, and no vector uses a port from 9222 to 9229.
 
+## Guard vectors
+
+Every CDP guard runs the vectors in `guard-vectors.json` (schema `schema/guard-vectors.schema.json`): bios, slicc-cdp, slicc-extension and slicc-cli. The sources are listed in `sources`:
+- slicc-cli's `protectVectors` at `2d5d981` (`test/integration/testdata/link/protect.js`), with the ids kept;
+- slicc-cdp's `test/integration/guard-vectors.json` at `4907a45`, where its `E1`, `E2`, `E3`, `E5` and `B2` are renamed `E1.onload`, `E2.binding`, `E3.bypass-csp`, `E5.console` and `B2.headers`;
+- the cert lane's E and B rows;
+- `C5.continue-request` and `C5.continue-response`, added next to `C5.document`.
+
+**Top level.**
+- `schemaVersion` (1): guards pin it.
+- `setVersion`: the package version. The release flow stamps it into the npm package and the crate (`scripts/set-crate-version.mjs`). In git, and so in the Go module, it reads `0.0.0`; Go code gets the version from the module.
+- `targets`: the names a runner maps to a scheme, host and port: `seven`, `vault`, `vault-x` (a vault branch preview), `apex`, `own` (the client page's origin, `{client}`), `ordinary` and `ordinary-same-site`. Each has a `description` and, for the protected ones, a default `host`. Nothing in the file is a URL a runner must use.
+- `variants`: the detach variants in ms. `prompt` and `lagging` are documented; a runner may add others, such as `lagging-8s`, and reports the name it ran.
+- `capabilities`: what a transport may lack. `autoAttach` covers `Target.setAutoAttach`, `children` steps and child sessions; `browserSession` covers calls on the browser session; `browserContexts` covers `Target.createBrowserContext` and `Target.disposeBrowserContext`.
+- `placeholders`: every `{name}` used in the vectors, with what it stands for. `{client}` is the client page's origin, which the runner maps.
+
+**A vector** has:
+- `id`, and `family` (`C`, `E` or `B`, the id's first letter);
+- `kind`: `cdp` (runnable steps) or `text` (rows in words, which runners report as `not-run`, never `pass`);
+- `scope`: `any`, or the one guard the vector is for;
+- `setup` and `trigger`, both lists of steps;
+- `targets`: the protected targets it runs against;
+- `requires?`: the capabilities it needs, the union of its steps' and observations' `requires`. A runner whose transport lacks one reports the vector as `skip` with the reason `not-supported:<capability>`;
+- `observe?`: each observed name, as `{ "means", "dependsOn"?, "requires"? }`. `dependsOn` lists the refusals the observation depends on (see Refusals);
+- `live`: the liveness check;
+- `control` (`origin: "ordinary"`, `via`, `expected`) and `expected`: an object of names and booleans, or text;
+- `skip?` (`target`, `reason`): `reason` starts with a code, as in `not-applicable: …`.
+
+**Steps** are declarative and transport-neutral. Any step can take `on` (`control` or `guarded`), which runs it on that leg only.
+Any `cdp`, `page` or `children` step can take `requires`, the capabilities it needs: `autoAttach` for `Target.setAutoAttach`, `children` and `session: "child"`, `browserSession` for `session: "browser"`, and `browserContexts` for `Target.createBrowserContext` and `Target.disposeBrowserContext`.
+- `{ "cdp": method, "params"?, "session"?, "as"?, "refusable"?, "refusal"? }`: a CDP call. It runs on the page session by default, on the browser with `browser`, on either with `page-or-browser` (the driver uses the page session), or on the current auto-attached target with `child`. `as` names its outcome. `refusable: true` with `refusal: { "match" }` (a regular expression for the error message or code) marks a call that a guard may refuse at registration.
+- `{ "page": action, … }`:
+  - `tab`: a new tab at `url`, in `context`, which becomes the page. `background` defaults to `true`;
+  - `navigate`: go to `url` and wait for the load;
+  - `href`, `replace`, `form`, `post`: navigate from the page, 50 ms later;
+  - `open`: `window.open` with a user gesture;
+  - `iframe`: add an iframe;
+  - `framed`: load the `/framed` page from `from`, with `url` in an iframe;
+  - `fetch`, `xhr`, `image`: load `url` and name the body (`width N` for an image, or `<status> <body>` with `status`); `background` doesn't wait;
+  - `eval`: evaluate `expression`.
+  `hops` routes `url` through `/hop` on each `origin`, with its `code`.
+- `{ "answer": { "url", "stage"?, "cdp"?, "params"?, "hold"? } }`: answer each paused request or auth challenge for `url` with that call; `hold` leaves it paused. Every other paused request continues unchanged.
+- `{ "children": steps }`: run these steps on each target auto-attached from then on, then resume it.
+- `{ "settle": { "beacon"?, "title"?, "ms"?, "variant"?, "session"? } }`: wait for a beacon from `beacon`, for the page `title`, or for the session to detach. It waits up to `ms` (10000 by default), then another 600 ms. `variant` waits the run's detach variant instead.
+- `{ "wait": ms }`.
+- `{ "guess": { "between", "cdp", "params" }, "as" }`: the call for each request id between the ids paused for the two URLs.
+- `{ "text": … }`: a step in words.
+
+Popups are observed by `Target.targetCreated` with the opener's `openerId`, or by the child's `Target.attachedToTarget`, never by the URL: a popup waiting for the debugger can still be `about:blank`.
+
+**The stand-in** serves these routes on every origin. It never listens on 9222 to 9229.
+- `/doc?n=`: an HTML page with the `data-canary` marker; `csp=1` adds `Content-Security-Policy: script-src 'none'` and an inline script that sends a beacon tagged `inline-<n>` to the log, which the CSP blocks unless it is bypassed;
+- `/hop?code=&to=` and `/framed?src=`;
+- `/data?n=`: `real-<n>`, with CORS;
+- `/img`: a 1×1 PNG;
+- `/auth`: Basic `u`:`p`, then `authed`;
+- `/rewritten` (title `rewritten`);
+- `/plant`: sets the canary;
+- `/beacon`, and `/log?n=`, which returns `{ hits, beacons }`.
+
+**The control rule.** Every vector has a control on an ordinary origin: the same setup and trigger against an unprotected origin must succeed. A missing or failing control fails the id. With `via: "guard"`, the control runs through the guard. With `via: "unguarded"`, the runner runs setup and trigger through its own CDP against the ordinary origin and against the protected stand-in, and both must show the effect. The runner reports the control's transport as `via`.
+
+**Refusals.** Each refusable step has a refusal name: its `as`, or `refused.<i>`, where `i` is its index in the vector's steps, setup then trigger, with each `children` step's steps right after it, counted from 0 before `on` is applied. When a guard refuses the step and the error matches `refusal.match`, the runner sets that name to `true` in the leg's observations. On that leg, an observation whose `dependsOn` lists the name is skipped; every other observation is checked as usual. A guard that refuses the step on every origin passes in one of two ways: through the guard, with the step refused on both legs, or with an unguarded control and the guard's matched refusal on the guarded leg. With `via: "guard"`, a refusal on one leg only fails that leg. A guard that allows the step must pass its control through the guard.
+
+**Liveness.** A runner checks `live` through its own CDP, never through the guard path: either the protected document loaded (title, marker or URL), or the guard returned its own refusal for a refusable step. A failing `live` fails the id.
+
+**Design-dependent outcomes.** A key listed in `designDependent` may expect `"either"`, which `true` and `false` both match: a guard that refuses a setup step lets the real document load, and one that blocks before commit doesn't. The hard negatives stay required.
+
+**Observability.** `observable.own: false` marks a vector the guard host's own origin can't show (headers, auth, redirects); a runner whose `own` is a static server reports it as `skip` with `not-observable`.
+
+**Applies to.** `appliesTo` lists the triggers a vector runs with (`href`, `iframe`, `popup`, `redirect`). Chrome doesn't apply some session overrides inside a cross-site iframe, so those E6 rows list `href` only.
+
+**Variants.** `variants` gives the delay in milliseconds before the client's `Target.detachFromTarget`: `prompt` 0, `lagging` 8000. A runner may add its own variant names.
+
+**Reports.** There is one row per id, target, variant and transport. `control`, `guarded` and `live` are each `pass`, `fail`, `skip` (with the skip's `reason`) or `not-run` (for text rows):
+
+```json
+{ "id": "C1.script-nav", "target": "vault", "variant": "lagging", "transport": "cli", "via": "guard", "control": "pass", "guarded": "pass", "live": "pass" }
+```
+
+**`guard-driver.mjs`** has no dependencies and no imports. It uses no Node APIs, so it runs in a plain browser page as well as in Node. It drives a client of this shape:
+- `send(method, params, sessionId)`: returns a promise of the result, and rejects with an error carrying `cdp`, the CDP error;
+- `waitEvent(predicate, ms)`: resolves with the first matching event `{ method, params, sessionId }`;
+- `events`: every event received so far.
+
+It exports:
+- `beacon(log, tag)` and `probe(log, tag)`: the sources for `{beacon}` and `{probe}`;
+- `canary.plant(value)`, `canary.read()` and `canary.untouched(value, read)`: the canary in `localStorage`, IndexedDB and the stand-in's marker;
+- `hop`, `expand(value, vars)`, and `steps(vector, side, vars)`, a leg's expanded steps, with `refusal.name` on each refusable step and `background` set on each `tab` step;
+- `refusals(vector)`: the vector's refusal names;
+- `outcome`, `call(client, step, sessionId)` and `isRefusal(outcome, step)`;
+- `instrument(client, sessionId, log, tag)`, `load(client, sessionId, url)` and `popup(client, openerId)`;
+- `judge(vector, side, observed)`: `{ pass, refused, skipped, mismatches }`, where `refused` lists the leg's refusals and `skipped` the observations that depend on them;
+- `result(vector, run)`: a report row from `{ target, variant, transport, via?, capabilities?, control, guarded, live }`. `capabilities` is the transport's; without it, the transport has them all;
+- `summary({ guard, sha, set, results })`: `set` is the parsed `guard-vectors.json`. It returns `{ set, schemaVersion, guard, sha, variants, targets, transports, results, skipped, notRun, missing, pass, line }`. `missing` lists each `{ id, target, variant, transport }` without a row, for every vector whose `scope` is `any` or the guard, every target it lists, every variant in `variants` or `results`, and every transport in `results`; `pass` needs it empty, where `line` is `GUARD-PASS <guard>@<sha> (vectors @ai-ecoverse/slicc-browsers@X.Y.Z)` or `GUARD-FAIL …`.
+
+**`npm run validate`** checks that:
+- the file matches the schema, and ids are unique;
+- every vector has a control and an `expected`, text rows included;
+- each id is in its family;
+- a `cdp` vector has a `cdp` or `page` step, and a `text` vector has neither;
+- every CDP method on the guarded leg also runs on the control;
+- a skip names one of the vector's targets;
+- `observe` defines every expected name;
+- in a vector with a refusable step, every observation, except an `as` of a step before the first refusable one, has `dependsOn`, and each name in it is a refusable step's refusal name;
+- every `Target.setAutoAttach`, `children`, child-session, browser-session and browser-context step has the matching `requires`, and a vector's `requires` is the union of its steps' and observations';
+- 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:
@@ -232,7 +461,7 @@ for case in corpus().cases {
 
 Go 1.26, Rust stable with `wasm32-wasip1`, Node ≥ 24.
 - `npm run corpus` regenerates `corpus.json` from `corpus/`; the pre-commit hook and CI fail when it's stale.
-- `npm run validate` checks `catalog.json`, `corpus.json` and `protected.json` against the schemas, runs the protected-origin vectors through `protected.mjs`, and checks what a schema can't say: unique ids, bundle ids and names, known Windows roots, rising tiers, compiling patterns, known tokens, tier order, `sevenOpen`, `six` and `auto` in each `expected.json`, and no port from 9222 to 9229.
+- `npm run validate` checks `catalog.json`, `corpus.json`, `protected.json` and `guard-vectors.json` against the schemas, runs the protected-origin vectors through `protected.mjs`, and checks what a schema can't say: unique ids, bundle ids and names, known Windows roots, rising tiers, compiling patterns, known tokens, tier order, `sevenOpen`, `six` and `auto` in each `expected.json`, and no port from 9222 to 9229.
 - `npm run lint`: the slicc lint tools (Biome, no comments, no unit tests in git, `AGENTS.md`), `gofmt`, `go mod tidy -diff`, `go vet`, golangci-lint, `cargo fmt --check` and clippy.
 - `npm test`: `validate`, the Go tests in `test/integration/`, and `cargo test --all-features`.
 - `npm run build`: the Go module, the crate (also for `wasm32-wasip1`), and `npm pack --dry-run`.

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()));
+      }),
+  };
+}

package/guard-driver.mjs

@@ -0,0 +1,213 @@
+const q = JSON.stringify;
+
+export const beacon = (log, tag) =>
+  `try { navigator.sendBeacon(${q(log)} + '/beacon?tag=' + ${q(tag)} + '&origin=' + encodeURIComponent(location.origin)); } catch {}`;
+
+export const probe = (log, tag) =>
+  `(() => { ${beacon(log, tag)} const p = btoa(location.origin + location.pathname); if (window.probeBinding) window.probeBinding(p); console.log('probe:' + p); })()`;
+
+const openCanary = `new Promise((resolve) => { const r = indexedDB.open('canary', 1); r.onupgradeneeded = () => r.result.createObjectStore('canary'); r.onsuccess = () => resolve(r.result); r.onerror = () => resolve(null); })`;
+
+export const canary = {
+  plant: (value) =>
+    `(async () => { localStorage.setItem('canary', ${q(value)}); const db = await ${openCanary}; if (!db) return false; await new Promise((resolve) => { const t = db.transaction('canary', 'readwrite'); t.objectStore('canary').put(${q(value)}, 'canary'); t.oncomplete = resolve; t.onerror = resolve; }); db.close(); return true; })()`,
+  read: () =>
+    `(async () => { const db = await ${openCanary}; const record = db ? await new Promise((resolve) => { const g = db.transaction('canary').objectStore('canary').get('canary'); g.onsuccess = () => resolve(g.result ?? null); g.onerror = () => resolve(null); }) : null; db?.close(); return { localStorage: localStorage.getItem('canary'), indexedDB: record, marker: document.querySelector('[data-canary]')?.dataset.canary ?? null }; })()`,
+  untouched: (value, read) =>
+    read?.localStorage === value && read?.indexedDB === value && read?.marker === value,
+};
+
+export const hop = (hops, end) =>
+  hops.reduceRight(
+    (to, { origin, code }) => `${origin}/hop?code=${code}&to=${encodeURIComponent(to)}`,
+    end
+  );
+
+export function expand(value, vars) {
+  if (typeof value === 'string')
+    return value.replace(/\{([A-Za-z][A-Za-z-]*)\}/g, (m, k) => (k in vars ? String(vars[k]) : m));
+  if (Array.isArray(value)) return value.map((v) => expand(v, vars));
+  if (value && typeof value === 'object')
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, expand(v, vars)]));
+  return value;
+}
+
+function named(list, n = { i: 0 }) {
+  return list.map((s) => {
+    const i = n.i++;
+    const step = s.children ? { ...s, children: named(s.children, n) } : { ...s };
+    if (s.refusable) step.refusal = { ...s.refusal, name: s.as ?? `refused.${i}` };
+    if (s.page === 'tab') step.background = s.background ?? true;
+    return step;
+  });
+}
+
+const flatten = (list) => list.flatMap((s) => [s, ...flatten(s.children ?? [])]);
+
+export const refusals = (vector) =>
+  flatten(named([...(vector.setup ?? []), ...(vector.trigger ?? [])]))
+    .filter((s) => s.refusable)
+    .map((s) => s.refusal.name);
+
+export function steps(vector, side, vars) {
+  const pick = (list) =>
+    list
+      .filter((s) => !s.on || s.on === side)
+      .map(({ on: _, ...s }) => (s.children ? { ...s, children: pick(s.children) } : s));
+  const all = { ...vars, beacon: beacon(vars.log, vars.tag), probe: probe(vars.log, vars.tag) };
+  const [setup, trigger] = [vector.setup, vector.trigger].map((list, k, both) =>
+    named(list, { i: k === 0 ? 0 : flatten(both[0]).length })
+  );
+  return { setup: expand(pick(setup), all), trigger: expand(pick(trigger), all) };
+}
+
+export async function outcome(promise) {
+  try {
+    return { ok: true, result: await promise };
+  } catch (error) {
+    return { ok: false, error: error?.cdp ?? { message: String(error?.message ?? error) } };
+  }
+}
+
+export const isRefusal = (out, step) =>
+  Boolean(step?.refusal) &&
+  !out.ok &&
+  [out.error?.message, out.error?.code]
+    .filter((v) => v !== undefined && v !== null)
+    .some((v) => new RegExp(step.refusal.match).test(String(v)));
+
+export function call(client, step, sessionId) {
+  const target = step.session === 'browser' ? undefined : sessionId;
+  return outcome(client.send(step.cdp, step.params ?? {}, target));
+}
+
+export async function instrument(client, sessionId, log, tag) {
+  await client.send('Page.enable', {}, sessionId);
+  await client.send(
+    'Page.addScriptToEvaluateOnNewDocument',
+    { source: beacon(log, tag) },
+    sessionId
+  );
+  await client.send('Page.setBypassCSP', { enabled: true }, sessionId);
+}
+
+export async function load(client, sessionId, url, ms = 20000) {
+  const loaded = client.waitEvent(
+    (e) => e.method === 'Page.loadEventFired' && e.sessionId === sessionId,
+    ms
+  );
+  await client.send('Page.navigate', { url }, sessionId);
+  await loaded;
+}
+
+export function popup(client, openerId, ms = 10000) {
+  const isPopup = (e) =>
+    (e.method === 'Target.targetCreated' || e.method === 'Target.attachedToTarget') &&
+    e.params?.targetInfo?.openerId === openerId;
+  const seen = client.events.find(isPopup);
+  if (seen) return Promise.resolve(seen.params.targetInfo);
+  return client.waitEvent(isPopup, ms).then(
+    (e) => e.params.targetInfo,
+    () => null
+  );
+}
+
+const matches = (want, got) => (want === 'either' ? typeof got === 'boolean' : got === want);
+
+export function judge(vector, side, observed) {
+  const want = side === 'control' ? vector.control.expected : vector.expected;
+  const refused = refusals(vector).filter((name) => observed?.[name] === true);
+  if (typeof want === 'string') {
+    const mismatches = observed === true ? [] : [want];
+    return { pass: mismatches.length === 0, refused, skipped: [], mismatches };
+  }
+  const skipped = Object.keys(want).filter((k) =>
+    (vector.observe?.[k]?.dependsOn ?? []).some((d) => refused.includes(d))
+  );
+  const mismatches = Object.entries(want)
+    .filter(([k, v]) => !skipped.includes(k) && !matches(v, observed?.[k]))
+    .map(([k, v]) => `${k}: got ${q(observed?.[k])}, want ${q(v)}`);
+  return { pass: mismatches.length === 0, refused, skipped, mismatches };
+}
+
+export function result(vector, run) {
+  const row = {
+    id: vector.id,
+    target: run.target,
+    variant: run.variant,
+    transport: run.transport,
+    via: run.via ?? vector.control.via,
+  };
+  if (vector.kind === 'text')
+    return { ...row, control: 'not-run', guarded: 'not-run', live: 'not-run' };
+  if (vector.skip?.target === run.target)
+    return { ...row, control: 'skip', guarded: 'skip', live: 'skip', reason: vector.skip.reason };
+  const missing = (vector.requires ?? []).find(
+    (cap) => Array.isArray(run.capabilities) && !run.capabilities.includes(cap)
+  );
+  if (missing) {
+    const reason = `not-supported:${missing}`;
+    return { ...row, control: 'skip', guarded: 'skip', live: 'skip', reason };
+  }
+  const c = run.control ? judge(vector, 'control', run.control) : null;
+  const g = run.guarded ? judge(vector, 'guarded', run.guarded) : null;
+  const only = (a, b) => (a?.refused ?? []).filter((name) => !(b?.refused ?? []).includes(name));
+  const why = [];
+  let control = c?.pass ? 'pass' : 'fail';
+  if (!c) why.push('no control');
+  else if (c.refused.length > 0 && row.via !== 'guard') {
+    control = 'fail';
+    why.push('an unguarded control was refused');
+  } else if (row.via === 'guard' && g && only(c, g).length > 0) {
+    control = 'fail';
+    why.push(`refused only on the control: ${only(c, g).join(', ')}`);
+  } else why.push(...c.mismatches.map((m) => `control ${m}`));
+  let guarded = g?.pass ? 'pass' : 'fail';
+  if (!g) why.push('no guarded run');
+  else if (row.via === 'guard' && only(g, c).length > 0) {
+    guarded = 'fail';
+    why.push(`refused only on the protected target: ${only(g, c).join(', ')}`);
+  } else if (row.via === 'unguarded' && g.refused.length > 0 && !c?.pass) {
+    guarded = 'fail';
+    why.push('refused on the protected target without a passing control');
+  } else why.push(...g.mismatches);
+  const live = run.live === true ? 'pass' : 'fail';
+  if (live === 'fail') why.push('not live');
+  return { ...row, control, guarded, live, ...(why.length ? { why: why.join('; ') } : {}) };
+}
+
+const passed = (r) =>
+  [r.control, r.guarded, r.live].every((s) => s === 'pass') ||
+  [r.control, r.guarded, r.live].every((s) => s === 'skip') ||
+  [r.control, r.guarded, r.live].every((s) => s === 'not-run');
+
+export function summary({ guard, sha, set, results }) {
+  const uniq = (k) => [...new Set(results.map((r) => r[k]))].sort();
+  const variants = [...new Set([...Object.keys(set.variants ?? {}), ...uniq('variant')])].sort();
+  const has = new Set(results.map((r) => q([r.id, r.target, r.variant, r.transport])));
+  const missing = set.vectors
+    .filter((v) => v.scope === 'any' || v.scope === guard)
+    .flatMap((v) => v.targets.map((target) => ({ id: v.id, target })))
+    .flatMap((row) => variants.map((variant) => ({ ...row, variant })))
+    .flatMap((row) => uniq('transport').map((transport) => ({ ...row, transport })))
+    .filter((r) => !has.has(q([r.id, r.target, r.variant, r.transport])));
+  const pass = results.length > 0 && missing.length === 0 && results.every(passed);
+  const name = `@ai-ecoverse/slicc-browsers@${set.setVersion}`;
+  return {
+    set: name,
+    schemaVersion: set.schemaVersion,
+    guard,
+    sha,
+    variants: uniq('variant'),
+    targets: uniq('target'),
+    transports: uniq('transport'),
+    results,
+    skipped: results
+      .filter((r) => r.control === 'skip')
+      .map(({ id, target, reason }) => ({ id, target, reason })),
+    notRun: [...new Set(results.filter((r) => r.control === 'not-run').map((r) => r.id))],
+    missing,
+    pass,
+    line: `${pass ? 'GUARD-PASS' : 'GUARD-FAIL'} ${guard}@${sha} (vectors ${name})`,
+  };
+}