@ai-ecoverse/slicc-browsers 1.8.3 → 1.8.4

package/README.md

@@ -147,6 +147,8 @@ Every CDP guard runs the vectors in `guard-vectors.json` (schema `schema/guard-v
 
 The `C8.newtab` reachability control attaches through the guard to a settled ordinary new tab, including its internal frames, then navigates that same tab to an ordinary document. Both legs must succeed, including without a guard. It requires `chromeUrlsAttach`, so an extension transport reports it as `skip` with `not-supported:chromeUrlsAttach`. The other C8 rows expect a refusal on the guarded leg and run their controls unguarded, so they don't require it and still run on extension transports. It uses the default browser context, since an incognito new tab omits the ordinary new tab's internal frames. It covers `chrome://newtab/` and directly opened `chrome://new-tab-page/`.
 
+A client may register `Fetch.enable` patterns naming a protected origin in either of two conformant ways: the guard allows registration but never pauses or forwards protected requests to the client and refuses continue, fulfil or fail calls for request ids it did not hand out; or the guard refuses registration with its declared refusal text. Setup calls explicitly naming a protected placeholder are refusable with `refusal.onlyProtected: true`, and interception-dependent observations depend on that refusal. Wildcard and ordinary-only patterns do not receive this exemption. The ordinary-origin control still runs through the guard and must succeed.
+
 **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.
@@ -169,7 +171,7 @@ The `C8.newtab` reachability control attaches through the guard to a settled ord
 
 **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"`, `browserContexts` for `Target.createBrowserContext` and `Target.disposeBrowserContext`, and `chromeUrlsAttach` for a step that must attach to a `chrome://` page to pass.
-- `{ "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.
+- `{ "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", "onlyProtected"? }` (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;
@@ -202,7 +204,7 @@ Popups are observed by `Target.targetCreated` with the opener's `openerId`, or b
 
 **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. The comparison only counts steps that ran on both legs. A step that ran on one leg only (for example a `children` step on the control's popup, when the guarded leg never gets that popup attached) doesn't fail the row by itself, and the row reports it in `ran`, as `{ "refused.5": "control-only" }` or `"guarded-only"`. Observations that depend on such a step follow their `dependsOn` on each leg. A refusable step that fails without a matching refusal, for example with an internal error or a timeout, is not a refusal: it fails the row with `<name> failed without a refusal: <message>`. A step skipped because an earlier step failed therefore never passes through `ran`, and only a matched refusal skips the observations that depend on it. A guard that allows the step must pass its control through the guard.
+**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, unless the step declares `refusal.onlyProtected: true`: its matched refusal on the guarded leg alone is conformant, and its dependent observations are skipped there. Refusing such a step on the control always fails the control, even if both legs are refused. Without that flag, refusal symmetry is unchanged. The comparison only counts steps that ran on both legs. A step that ran on one leg only (for example a `children` step on the control's popup, when the guarded leg never gets that popup attached) doesn't fail the row by itself, and the row reports it in `ran`, as `{ "refused.5": "control-only" }` or `"guarded-only"`. Observations that depend on such a step follow their `dependsOn` on each leg. A refusable step that fails without a matching refusal, for example with an internal error or a timeout, is not a refusal: it fails the row with `<name> failed without a refusal: <message>`. A step skipped because an earlier step failed therefore never passes through `ran`, and only a matched refusal skips the observations that depend on it. 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.
 

package/guard-driver.mjs

@@ -152,6 +152,32 @@ export function judge(vector, side, observed) {
   return { pass: mismatches.length === 0, refused, skipped, mismatches };
 }
 
+const ranOn = (observed, name) => typeof observed?.[name] === 'boolean';
+
+const refusalRuns = (vector, control, guarded) =>
+  Object.fromEntries(
+    refusals(vector)
+      .filter((name) => control && guarded && ranOn(control, name) !== ranOn(guarded, name))
+      .map((name) => [name, ranOn(control, name) ? 'control-only' : 'guarded-only'])
+  );
+
+const protectedRefusals = (vector) =>
+  new Set(
+    flatten(named([...(vector.setup ?? []), ...(vector.trigger ?? [])]))
+      .filter((step) => step.refusable && step.refusal.onlyProtected)
+      .map((step) => step.refusal.name)
+  );
+
+function controlRefusal(c, g, via, only, onlyProtected) {
+  if (!c) return 'no control';
+  if (c.refused.length > 0 && via !== 'guard') return 'an unguarded control was refused';
+  if (c.refused.some((name) => onlyProtected.has(name)))
+    return 'a protected-only step was refused on the control';
+  if (via === 'guard' && g && only(c, g).length > 0)
+    return `refused only on the control: ${only(c, g).join(', ')}`;
+  return null;
+}
+
 export function result(vector, run) {
   const row = {
     id: vector.id,
@@ -173,33 +199,22 @@ export function result(vector, run) {
   }
   const c = run.control ? judge(vector, 'control', run.control) : null;
   const g = run.guarded ? judge(vector, 'guarded', run.guarded) : null;
-  const ranOn = (observed, name) => typeof observed?.[name] === 'boolean';
   const both = (name) => ranOn(run.control, name) && ranOn(run.guarded, name);
   const only = (a, b) =>
     (a?.refused ?? []).filter((name) => both(name) && !(b?.refused ?? []).includes(name));
-  const ran = Object.fromEntries(
-    refusals(vector)
-      .filter(
-        (name) =>
-          run.control && run.guarded && ranOn(run.control, name) !== ranOn(run.guarded, name)
-      )
-      .map((name) => [name, ranOn(run.control, name) ? 'control-only' : 'guarded-only'])
-  );
+  const ran = refusalRuns(vector, run.control, run.guarded);
+  const onlyProtected = protectedRefusals(vector);
+  const protectedOnly = only(g, c).filter((name) => !onlyProtected.has(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}`));
+  const refusal = controlRefusal(c, g, row.via, only, onlyProtected);
+  const control = c?.pass && !refusal ? 'pass' : 'fail';
+  if (refusal) why.push(refusal);
+  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) {
+  else if (row.via === 'guard' && protectedOnly.length > 0) {
     guarded = 'fail';
-    why.push(`refused only on the protected target: ${only(g, c).join(', ')}`);
+    why.push(`refused only on the protected target: ${protectedOnly.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');

package/guard-vectors.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "setVersion": "1.8.3",
+  "setVersion": "1.8.4",
   "sources": [
     {
       "repo": "ai-ecoverse/slicc-cli",
@@ -7806,6 +7806,11 @@
                 "requestStage": "Response"
               }
             ]
+          },
+          "refusable": true,
+          "refusal": {
+            "match": "^slicc: refused",
+            "onlyProtected": true
           }
         },
         {
@@ -7875,6 +7880,7 @@
       "targets": ["seven", "vault", "vault-x", "apex"],
       "observe": {
         "candidates": {
+          "dependsOn": ["refused.2"],
           "means": "attempts is not empty",
           "check": {
             "result": "attempts",
@@ -7886,6 +7892,7 @@
           }
         },
         "refused": {
+          "dependsOn": ["refused.2"],
           "means": "every attempt was refused",
           "check": {
             "refused": ["attempts"],
@@ -7893,6 +7900,7 @@
           }
         },
         "answered": {
+          "dependsOn": ["refused.2"],
           "means": "body is 'real-{tag}'",
           "check": {
             "result": "body",
@@ -7902,6 +7910,7 @@
           }
         },
         "overridden": {
+          "dependsOn": ["refused.2"],
           "means": "the fetch reported the overridden response status",
           "check": {
             "result": "body",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-browsers",
-  "version": "1.8.3",
+  "version": "1.8.4",
   "description": "SLICC's shared browser catalog, JSON schemas and discovery conformance corpus",
   "type": "module",
   "license": "Apache-2.0",
@@ -65,14 +65,14 @@
     "trust:dry": "npx fledgling sync --dry-run -y --skip-publish",
     "release": "semantic-release",
     "test:guard": "npm run test:guard-integration && npm run test:guard-sweep",
-    "test:guard-integration": "node --test test/integration/guard-fit.test.mjs test/integration/guard-chain.test.mjs test/integration/guard-validation.test.mjs test/integration/guard-liveness.test.mjs test/integration/guard-observations.test.mjs test/integration/guard-child-latency.test.mjs test/integration/guard-adoption.test.mjs test/integration/guard-scoping.test.mjs test/integration/guard-late-pause.test.mjs test/integration/guard-legs.test.mjs test/integration/guard-diagnostics.test.mjs test/integration/guard-chrome.test.mjs test/integration/guard-scales.test.mjs",
+    "test:guard-integration": "node --test test/integration/guard-fit.test.mjs test/integration/guard-chain.test.mjs test/integration/guard-validation.test.mjs test/integration/guard-liveness.test.mjs test/integration/guard-observations.test.mjs test/integration/guard-child-latency.test.mjs test/integration/guard-adoption.test.mjs test/integration/guard-scoping.test.mjs test/integration/guard-late-pause.test.mjs test/integration/guard-legs.test.mjs test/integration/guard-fetch-enable.test.mjs test/integration/guard-diagnostics.test.mjs test/integration/guard-chrome.test.mjs test/integration/guard-scales.test.mjs",
     "test:guard-sweep": "node scripts/test-guards.mjs",
     "test:gates": "node --test test/integration/gates.test.mjs",
     "test:guard-target": "node --test test/integration/guard-runner.test.mjs",
     "test:unit:guard": "node --experimental-test-coverage --test --test-coverage-include=guard-runner.mjs --test-coverage-include=fixture-server.mjs --test-coverage-lines=100 test/unit/guard-*.test.mjs"
   },
   "devDependencies": {
-    "@ai-ecoverse/slicc-shared-web": "1.23.2",
+    "@ai-ecoverse/slicc-shared-web": "1.23.3",
     "@biomejs/biome": "2.5.15",
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",

package/schema/guard-vectors.schema.json

@@ -456,6 +456,9 @@
               "additionalProperties": false,
               "required": ["match"],
               "properties": {
+                "onlyProtected": {
+                  "type": "boolean"
+                },
                 "match": {
                   "type": "string",
                   "minLength": 1