@ai-ecoverse/slicc-browsers 1.7.1 → 1.7.3

package/README.md

@@ -151,7 +151,7 @@ Every CDP guard runs the vectors in `guard-vectors.json` (schema `schema/guard-v
 - `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);
+- `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: …`.
@@ -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`.
 
@@ -291,7 +291,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
@@ -307,7 +307,26 @@ 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
+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`. 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. 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.
+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
@@ -485,8 +504,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/guard-driver.mjs

@@ -125,7 +125,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 };
 }

package/guard-runner.mjs

@@ -108,6 +108,7 @@ class Execution {
     this.answers = [];
     this.attachSettings = new Map();
     this.childSteps = [];
+    this.childRuns = new Map();
     this.processed = new Set();
     this.eventStart = this.client.events.length;
     this.actionEventStart = this.eventStart;
@@ -245,7 +246,7 @@ class Execution {
   }
 
   async blocked(spec, observer) {
-    const url = address(spec.url);
+    const urls = (spec.anyOf ?? [spec.url]).map(address);
     const events = this.client.events.slice(this.eventStart);
     if (observer === 'client') {
       const requests = new Map(
@@ -259,10 +260,10 @@ class Execution {
             (!spec.frame ||
               event.params.frame.parentId ||
               event.sessionId === this.sessions.child) &&
-            event.params.frame.unreachableUrl === url &&
+            urls.includes(event.params.frame.unreachableUrl) &&
             event.params.frame.url.startsWith('chrome-error://')) ||
           (event.method === 'Network.loadingFailed' &&
-            requests.get(event.params.requestId) === url &&
+            urls.includes(requests.get(event.params.requestId)) &&
             (event.params.blockedReason || event.params.errorText === 'net::ERR_BLOCKED_BY_CLIENT'))
       );
     }
@@ -279,15 +280,103 @@ class Execution {
       const visit = (tree) =>
         Boolean(
           tree &&
-            ((tree.frame.unreachableUrl === url && tree.frame.url.startsWith('chrome-error://')) ||
+            ((urls.includes(tree.frame.unreachableUrl) &&
+              tree.frame.url.startsWith('chrome-error://')) ||
               (tree.childFrames ?? []).some(visit))
         );
-      return (
+      if (
         read.ok &&
         (spec.frame
           ? (read.result.frameTree.childFrames ?? []).some(visit)
           : visit(read.result.frameTree))
+      )
+        return true;
+      return spec.frame ? Boolean(await this.blockedFrameTarget(urls, targetId)) : false;
+    } finally {
+      await outcome(
+        this.reader.send('Target.detachFromTarget', { sessionId: attached.result.sessionId })
       );
+    }
+  }
+
+  async frameIds(targetId) {
+    const attached = await outcome(
+      this.reader.send('Target.attachToTarget', { targetId, flatten: true })
+    );
+    if (!attached.ok) return [];
+    try {
+      const read = await outcome(
+        this.reader.send('Page.getFrameTree', {}, attached.result.sessionId)
+      );
+      const ids = (tree) => [tree.frame.id, ...(tree.childFrames ?? []).flatMap(ids)];
+      return read.ok ? ids(read.result.frameTree) : [];
+    } finally {
+      await outcome(
+        this.reader.send('Target.detachFromTarget', { sessionId: attached.result.sessionId })
+      );
+    }
+  }
+
+  async blockedFrameTarget(urls, parentTarget) {
+    const parents = await this.frameIds(parentTarget);
+    const listed = await outcome(this.reader.send('Target.getTargets', {}));
+    if (!listed.ok) return undefined;
+    for (const info of listed.result.targetInfos) {
+      if (info.type !== 'iframe' || !parents.includes(info.parentFrameId)) continue;
+      const attached = await outcome(
+        this.reader.send('Target.attachToTarget', { targetId: info.targetId, flatten: true })
+      );
+      if (!attached.ok) continue;
+      try {
+        const read = await outcome(
+          this.reader.send('Page.getFrameTree', {}, attached.result.sessionId)
+        );
+        const frame = read.result?.frameTree?.frame;
+        if (frame?.url.startsWith('chrome-error://') && urls.includes(frame.unreachableUrl))
+          return info.targetId;
+      } finally {
+        await outcome(
+          this.reader.send('Target.detachFromTarget', { sessionId: attached.result.sessionId })
+        );
+      }
+    }
+    return undefined;
+  }
+
+  async frameBlocked(spec) {
+    const urls = (spec.anyOf ?? [spec.url]).map(address);
+    const targetId = spec.session === 'child' ? this.targets.at(-1) : this.pageTarget;
+    if (!targetId) return false;
+    const frame = await this.blockedFrameTarget(urls, targetId);
+    if (!frame) return false;
+    const attached = await outcome(
+      this.client.send('Target.attachToTarget', { targetId: frame, flatten: true })
+    );
+    if (attached.ok)
+      await outcome(
+        this.client.send('Target.detachFromTarget', { sessionId: attached.result.sessionId })
+      );
+    return !attached.ok;
+  }
+
+  async history(spec) {
+    const urls = (spec.anyOf ?? [spec.url]).map(address);
+    const targetId = spec.session === 'child' ? this.targets.at(-1) : this.pageTarget;
+    if (!targetId) return false;
+    const pre = await Promise.all(urls.map((url) => this.attemptCheck({ pre: url })));
+    if (!pre.some(Boolean)) return false;
+    const loaded = await Promise.all(urls.map((url) => this.attemptCheck({ loaded: url })));
+    const unloaded = urls.filter((_, index) => !loaded[index]);
+    if (!unloaded.length) return false;
+    const attached = await outcome(
+      this.reader.send('Target.attachToTarget', { targetId, flatten: true })
+    );
+    if (!attached.ok) return false;
+    try {
+      const read = await outcome(
+        this.reader.send('Page.getNavigationHistory', {}, attached.result.sessionId)
+      );
+      return read.ok && read.result.entries.some((entry) => unloaded.includes(entry.url));
     } finally {
       await outcome(
         this.reader.send('Target.detachFromTarget', { sessionId: attached.result.sessionId })
@@ -348,34 +437,34 @@ class Execution {
             continue;
           this.sessions.child = event.params.sessionId;
           if (info?.targetId) this.targets.push(info.targetId);
-          this.pending.push(
-            (async () => {
-              const reload = this.childSteps.findIndex((step) => step.cdp === 'Page.reload');
-              if (reload < 0) await this.execute(this.childSteps, event.params.sessionId);
-              else {
-                await this.execute(this.childSteps.slice(0, reload), event.params.sessionId);
-                const start = this.client.events.length;
-                await outcome(
-                  this.client.send('Runtime.runIfWaitingForDebugger', {}, event.params.sessionId)
-                );
-                await this.poll(
-                  () =>
-                    this.client.events
-                      .slice(start)
-                      .some(
-                        (e) =>
-                          e.method === 'Page.loadEventFired' &&
-                          e.sessionId === event.params.sessionId
-                      ),
-                  1500
-                );
-                await this.execute(this.childSteps.slice(reload), event.params.sessionId);
-              }
+          const child = event.params.sessionId;
+          const started = (async () => {
+            const reload = this.childSteps.findIndex((step) => step.cdp === 'Page.reload');
+            if (reload < 0) await this.execute(this.childSteps, event.params.sessionId);
+            else {
+              await this.execute(this.childSteps.slice(0, reload), event.params.sessionId);
+              const start = this.client.events.length;
               await outcome(
                 this.client.send('Runtime.runIfWaitingForDebugger', {}, event.params.sessionId)
               );
-            })().catch((error) => this.errors.push(String(error.message ?? error)))
-          );
+              await this.poll(
+                () =>
+                  this.client.events
+                    .slice(start)
+                    .some(
+                      (e) =>
+                        e.method === 'Page.loadEventFired' && e.sessionId === event.params.sessionId
+                    ),
+                1500
+              );
+              await this.execute(this.childSteps.slice(reload), event.params.sessionId);
+            }
+            await outcome(
+              this.client.send('Runtime.runIfWaitingForDebugger', {}, event.params.sessionId)
+            );
+          })().catch((error) => this.errors.push(String(error.message ?? error)));
+          this.childRuns.set(child, started);
+          this.pending.push(started);
         }
       }
       await sleep(10);
@@ -409,23 +498,40 @@ class Execution {
     this.calls[`answer.${p.requestId}.${event.method}`] = out;
   }
 
+  async childrenSettled() {
+    await Promise.all([...this.childRuns.values()]);
+  }
+
+  detached(session) {
+    return this.client.events
+      .slice(this.eventStart)
+      .some((e) => e.method === 'Target.detachedFromTarget' && e.params?.sessionId === session);
+  }
+
   async execute(list, childSession, phase = 'child') {
+    if (phase === 'trigger') await this.childrenSettled();
     for (const raw of list) {
       const step = expand(raw, this.vars);
       if (!supported(step.requires, this.options.capabilities) || step.text) continue;
+      if (!childSession && step.session === 'child') await this.childrenSettled();
       const session = childSession ?? this.session(step.session);
       const out = await this.operation(step, session, phase);
       if (!out) continue;
+      const gone = Boolean(childSession) && !out.ok && this.detached(childSession);
+      const refused =
+        !gone &&
+        (step.refusable
+          ? isRefusal(out, step)
+          : /refused/.test(String(out.error?.message ?? out.error)));
       this.trace.push({
         phase,
         declared: Boolean(step.refusable),
         session,
         out,
-        refused: step.refusable
-          ? isRefusal(out, step)
-          : /refused/.test(String(out.error?.message ?? out.error)),
+        refused,
+        ...(gone ? { detached: true } : {}),
       });
-      if (step.refusable) this.refused[step.refusal.name] = isRefusal(out, step);
+      if (step.refusable) this.refused[step.refusal.name] = refused;
       if (step.as && !out.result?.pending) this.calls[step.as] = out;
       if (step.cdp) (this.calls.$cdp ??= []).push({ method: step.cdp, ...out });
       this.options.debug?.({ step, out, side: this.side });
@@ -624,6 +730,7 @@ class Execution {
       );
     if (c.refused || c.reached) return this.callCheck(c);
     if (c.detached) {
+      const events = this.client.events.slice(this.eventStart, this.cleanupEventStart);
       const session = this.sessions[c.detached];
       return (
         Boolean(session) &&
@@ -669,6 +776,8 @@ class Execution {
       );
     if (c.state) return this.readState(c.state);
     if (c.blocked) return this.blocked(c.blocked, c.observer);
+    if (c.history) return this.history(c.history);
+    if (c.frameBlocked) return this.frameBlocked(c.frameBlocked);
     if (c.pre || c.loaded) return this.attemptCheck(c);
   }
 
@@ -784,6 +893,8 @@ class Execution {
         if (!supported(observation.requires, this.options.capabilities)) continue;
         if ((observation.dependsOn ?? []).some((dep) => this.refused[dep])) continue;
         observed[name] = await this.check(observation.check);
+        if (observation.eitherWhen && this.side === 'guarded')
+          observed[`${name}.either`] = await this.check(observation.eitherWhen);
       }
       this.options.debug?.({
         events: this.client.events.slice(this.eventStart),
@@ -824,7 +935,9 @@ const observerRequired = (check) => {
 const needsObserver = (vector) =>
   vector.control.via === 'unguarded' ||
   observerRequired(vector.liveCheck) ||
-  Object.values(vector.observe ?? {}).some((observation) => observerRequired(observation.check));
+  Object.values(vector.observe ?? {}).some(
+    (observation) => observerRequired(observation.check) || observerRequired(observation.eitherWhen)
+  );
 
 const inactive = (vector, target, capabilities) =>
   vector.skip?.target === target ||
@@ -938,6 +1051,28 @@ async function executeRow(job, opts, clients, set, slot, index) {
   return row;
 }
 
+const invalidBlocked = (check) =>
+  Boolean(
+    check?.blocked &&
+      ((check.blocked.url === undefined) === (check.blocked.anyOf === undefined) ||
+        (check.blocked.anyOf !== undefined &&
+          (!Array.isArray(check.blocked.anyOf) || check.blocked.anyOf.length === 0)))
+  ) ||
+  [...(check?.all ?? []), ...(check?.any ?? []), ...(check?.not ? [check.not] : [])].some(
+    invalidBlocked
+  );
+
+function validateBlocked(vectors) {
+  for (const vector of vectors)
+    if (
+      [
+        vector.liveCheck,
+        ...Object.values(vector.observe ?? {}).flatMap((o) => [o.check, o.eitherWhen]),
+      ].some(invalidBlocked)
+    )
+      throw new TypeError(`${vector.id}: blocked needs exactly one url or nonempty anyOf`);
+}
+
 function validate(set, opts) {
   if (!opts.fixture?.log) throw new TypeError('fixture.log is required');
   for (const vector of set.vectors)
@@ -954,6 +1089,7 @@ function validate(set, opts) {
   for (const vector of set.vectors)
     if (vector.kind === 'cdp' && invalidLive(vector.liveCheck))
       throw new TypeError(`${vector.id}: liveCheck needs guarded attempt evidence`);
+  validateBlocked(set.vectors);
   const variants = Array.isArray(opts.variant) ? opts.variant : [opts.variant];
   for (const name of variants)
     if (!(name in set.variants)) throw new TypeError(`Unknown variant: ${name}`);