@ai-ecoverse/slicc-browsers 1.7.2 → 1.7.4

package/README.md

@@ -150,8 +150,8 @@ Every CDP guard runs the vectors in `guard-vectors.json` (schema `schema/guard-v
 - `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);
+- `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>`. A row with a `page-or-browser` cookie step that would carry a `browserContextId` reports `not-supported:browserSession` without a browser session, because that parameter is only allowed on the browser target;
+- `observe?`: each observed name, as `{ "means", "dependsOn"?, "requires"?, "eitherWhen"? }`. `dependsOn` lists the refusals the observation depends on (see Refusals). `eitherWhen` is a check: when it holds on the guarded leg, that observation's expectation becomes `"either"` there (see Design-dependent outcomes);
 - `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: …`.
@@ -170,7 +170,7 @@ Any `cdp`, `page` or `children` step can take `requires`, the capabilities it ne
   - `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.
+- `{ "children": steps, "where"? }`: run these steps on each target auto-attached from then on, then resume it. `where` scopes them to the row's own target: `{ "openerId": "page" }` (opened by the row's page) or `{ "urlPrefix": url }`; other attached targets are resumed and otherwise left alone.
 - `{ "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.
@@ -194,7 +194,7 @@ Popups are observed by `Target.targetCreated` with the opener's `openerId`, or b
 
 **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.
+**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. `detached` is design-dependent on the rows whose guarded leg proves the block (the pre-action beacon plus an exact-URL block or the history form): its `eitherWhen` holds the same proof, so a guard that blocks without detaching passes, and one that neither blocks nor detaches still fails. 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`.
 
@@ -253,7 +253,10 @@ 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`.
+`skip` with `not-supported:unguarded-observer`, counted in `summary().observerSkipped`. The run's `summary()` also reports
+`skips`, the number of skipped rows per reason, and appends
+`skips <n> (<reason>=<count>, ...)` to `line` whenever any row was skipped, so a
+certification line never reads skipped rows as coverage.
 `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;
@@ -270,13 +273,16 @@ 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. Explicitly map an unavailable target to `null`: every
+relationships of the data. Map an unavailable target to `null`, or leave it out; a
+missing or `undefined` origin is treated exactly like `null`: every
 row needing that origin is reported as `skip` for control, guarded and live, with
 reason `not-applicable:no-<target>-origin`; no substitute origin is used and the
 row never passes. A guard whose whole site is protected, such as the extension
 where every `sliccy.ai` host is protected, passes `ordinary-same-site: null`.
-This also applies to origins referenced in setup, triggers, observations and
-liveness checks, not only the row target. Tags and cookie names are unique per leg. `variant`
+This also applies to origins referenced in setup and triggers, not only the row
+target. In observations and liveness checks, an `any` alternative that references
+a `null` origin is dropped and the rest are evaluated; the row skips only when
+every alternative of an `any`, or a required (`all`, `not` or plain) check, needs it. 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.
@@ -291,7 +297,7 @@ 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`
+`history`, `frameBlocked`, `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
@@ -309,7 +315,30 @@ heartbeat; alternatively a pre-action `/live?tag=...&step=pre&to=...` request an
 an exact-URL block/error from the client or unguarded frame tree. An error for a
 different URL is not evidence. `blocked` accepts either `{ url }` for one exact URL
 or `{ anyOf: [url, ...] }` for a nonempty list of exact URLs; each URL can be a
-string or `{ hops, to, index? }`. Both forms allow `session` and `frame`. Redirect
+string or `{ hops, to, index? }`. Both forms allow `session` and `frame`. With `frame`,
+the unguarded observer also reads the page's out-of-process iframe targets (matched by
+their parent frame): a site-isolated iframe isn't in the parent's frame tree, so its
+chrome-error main frame with the exact `unreachableUrl` is the block. `history` (unguarded,
+same URL forms) is for guards that replace the error page, such as with `about:blank#blocked`: it
+needs the pre-action beacon, an entry with the exact URL in the observer's
+`Page.getNavigationHistory` of the page or child, and no fixture request for that URL.
+`frameBlocked` (unguarded) is that out-of-process chrome-error iframe target, and the
+client must be unable to attach to it; the cross-site `C4` rows accept it as `errorFrame`.
+A step that the guard refuses in every context, such as `Network.clearBrowserCookies`
+in `C6.clear-cookies`, is refusable, so refusing it on both legs passes and allowing it
+is judged on its effect. A child step that fails after its child session detached is
+recorded as detached, not as a refusal, and the runner awaits a child's started
+`children` steps before any later `session: "child"` step and before the trigger. A page
+navigation waits for the load of its own `loaderId` (its `Page.frameNavigated` and then a
+load event), and a settle waits for a main-frame commit followed by its load, so a stale
+load event never ends a wait. After a child's `children` steps that include `Page.enable`,
+the runner waits, bounded at 5 s, for the child's first document to commit and load before
+any later child step. `{ "settle": { "beacon", "required": true, "dependsOn"? } }` waits
+for that beacon at the fixture and fails the row with `settle: no beacon from <origin>
+within <ms>ms` when it never arrives, unless a refusal it `dependsOn` was recorded; the rows
+whose `allowedBeacon` comes from an earlier document settle on it before their trigger.
+Beacons use `navigator.sendBeacon`, with a `fetch(…, { keepalive: true })` fallback. An observation that reads a background step's `as` result
+waits for that step, up to 10 s, and fails with `<as> did not complete within …` past it. Redirect
 vectors list every nested hop URL and the final destination because Chromium
 reports the URL intercepted by the guard. A matching block still requires the
 pre-action beacon alongside it; an unrelated error cannot certify the chain.
@@ -331,7 +360,7 @@ fixture log. A setup beacon on the same origin and tag cannot settle an unfinish
 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, tls })`, defaulting to a random loopback port.
+`fixtureServer({ host, port, tls, latency })`, defaulting to a random loopback port. `latency(url)` returns milliseconds to hold that response, for timing tests.
 Pass `tls: { key, cert }` to serve HTTPS using Node TLS key and certificate
 values. The returned origin, request logs, redirect URLs and document heartbeats
 use `https://<Host>` with TLS, so `served`, `hops` and `liveCheck` compare against
@@ -491,8 +520,9 @@ semantic-release cuts one version from `main` for all three packages (`.github/w
 1. The tag `vX.Y.Z` and a GitHub release are the Go module's release. `scripts/major-guard.mjs` fails the release when the major doesn't fit the module path in `go.mod` (no suffix allows v0 and v1, `/vN` only vN). The workflow then asks `proxy.golang.org` for the new version and `pkg.go.dev` to fetch it; both only warn.
 2. **npm:** with the repository variable `SLICC_BROWSERS_NPM_PUBLISH` set to `true`, the package is stamped with the version and published through npm trusted publishing (OIDC, with provenance). A version that is already on npm is skipped.
 3. **crates.io:** with the repository variable `SLICC_BROWSERS_CRATES_PUBLISH` set to `true`, `Cargo.toml` is stamped with the version and `cargo publish` runs with a short-lived token from crates.io trusted publishing (`rust-lang/crates-io-auth-action`). A version that is already on crates.io is skipped.
+4. **Cert line:** after the npm publish, the workflow runs `npm pack @ai-ecoverse/slicc-browsers@X.Y.Z` against the registry and appends `cert: @ai-ecoverse/slicc-browsers@X.Y.Z sha256=<hex> gitHead=<sha>` to the `vX.Y.Z` GitHub release and the job summary, once; the cert lane copies it from there.
 
-A run started by hand publishes what's missing without a new release: `gh workflow run release.yml --ref main` when `main`'s head has its tag, or `gh workflow run release.yml --ref main -f tag=vX.Y.Z` for any existing tag.
+A run started by hand publishes what's missing without a new release: `gh workflow run release.yml --ref main` when `main`'s head has its tag, or `gh workflow run release.yml --ref main -f tag=vX.Y.Z` for any existing tag. `gh workflow run release.yml --ref main -f cert-only=true` only adds the cert line for the latest npm version.
 
 **Go module versions.** A pushed tag is the release: `proxy.golang.org` caches it and `sum.golang.org` records its hash for good. Never move or delete a pushed tag; retract a bad version in `go.mod` and release anew. A `BREAKING CHANGE` needs a `/vN` module path first.
 

package/fixture-server.mjs

@@ -76,7 +76,7 @@ function route(req, url, send, html) {
   return send(404, 'missing', 'text/plain');
 }
 
-export async function fixtureServer({ host = '127.0.0.1', port = 0, tls } = {}) {
+export async function fixtureServer({ host = '127.0.0.1', port = 0, tls, latency } = {}) {
   let entries = [];
   const scheme = tls ? 'https' : 'http';
   const handler = (req, res) => {
@@ -105,7 +105,9 @@ export async function fixtureServer({ host = '127.0.0.1', port = 0, tls } = {})
         'text/html',
         headers
       );
-    route(req, url, send, html);
+    const wait = latency?.(url) ?? 0;
+    if (wait > 0) setTimeout(() => route(req, url, send, html), wait);
+    else route(req, url, send, html);
   };
   const server = tls ? createSecureServer(tls, handler) : createServer(handler);
   await new Promise((resolve, reject) => {

package/guard-driver.mjs

@@ -1,7 +1,7 @@
 const q = JSON.stringify;
 
 export const beacon = (log, tag) =>
-  `try { navigator.sendBeacon(${q(log)} + '/beacon?tag=' + ${q(tag)} + '&origin=' + encodeURIComponent(location.origin)); } catch {}`;
+  `try { const u = ${q(log)} + '/beacon?tag=' + ${q(tag)} + '&origin=' + encodeURIComponent(location.origin); if (!navigator.sendBeacon(u)) fetch(u, { keepalive: true, mode: 'no-cors' }).catch(() => {}); } 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); })()`;
@@ -91,13 +91,31 @@ export async function instrument(client, sessionId, log, tag) {
   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
+export function loadedAfter(events, sessionId, loaderId) {
+  const committed = events.findIndex(
+    (e) =>
+      e.method === 'Page.frameNavigated' &&
+      e.sessionId === sessionId &&
+      !e.params?.frame?.parentId &&
+      e.params?.frame?.loaderId === loaderId
+  );
+  return (
+    committed >= 0 &&
+    events
+      .slice(committed + 1)
+      .some((e) => e.method === 'Page.loadEventFired' && e.sessionId === sessionId)
   );
-  await client.send('Page.navigate', { url }, sessionId);
-  await loaded;
+}
+
+export async function load(client, sessionId, url, ms = 20000) {
+  const start = client.events.length;
+  const { loaderId } = await client.send('Page.navigate', { url }, sessionId);
+  if (!loaderId) return;
+  const deadline = Date.now() + ms;
+  while (!loadedAfter(client.events.slice(start), sessionId, loaderId)) {
+    if (Date.now() > deadline) throw new Error(`load of ${url} timed out`);
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
 }
 
 export function popup(client, openerId, ms = 10000) {
@@ -125,7 +143,11 @@ export function judge(vector, side, observed) {
     (vector.observe?.[k]?.dependsOn ?? []).some((d) => refused.includes(d))
   );
   const mismatches = Object.entries(want)
-    .filter(([k, v]) => !skipped.includes(k) && !matches(v, observed?.[k]))
+    .filter(
+      ([k, v]) =>
+        !skipped.includes(k) &&
+        !matches(observed?.[`${k}.either`] === true ? 'either' : v, observed?.[k])
+    )
     .map(([k, v]) => `${k}: got ${q(observed?.[k])}, want ${q(v)}`);
   return { pass: mismatches.length === 0, refused, skipped, mismatches };
 }