@ai-ecoverse/slicc-browsers 1.8.2 → 1.8.4

package/README.md

@@ -145,14 +145,16 @@ Every CDP guard runs the vectors in `guard-vectors.json` (schema `schema/guard-v
 - `C5.continue-request` and `C5.continue-response`, added next to `C5.document`;
 - the `C8` rows for privileged pages: `C8.navigate` (a page navigates to `chrome://settings`, `chrome://password-manager`, an extension page or `file:///`; refused), `C8.view-source` (the same through `view-source:`; refused), `C8.create` (`Target.createTarget` straight on those pages; refused), `C8.browser-ui-listed` (`Target.getTargets` lists no `browser_ui` target) and `C8.browser-ui-attach` (`Target.attachToTarget` by a `browser_ui` target's id; refused). All four have an unguarded control, since the guard refuses them only on the privileged target. Two cases aren't rows, because Chrome itself blocks them, so an unguarded client can't tell a guard from none: a page's `window.open('chrome://settings')`, and an `about:` alias such as `about:settings`, which `Page.navigate` and `Target.createTarget` both turn into `about:blank#blocked`. The `about:` aliases are in `protected.json` instead.
 
-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 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/`.
+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.
 - `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`, `ordinary-same-site`, `chrome-newtab`, `chrome-new-tab-page`, `chrome-settings`, `chrome-passwords`, `chrome-extension-page` and `file-root`. Each has a `description` and, for the protected ones, a default `host`. `chrome-newtab` (`chrome://newtab/`), `chrome-new-tab-page` (`chrome://new-tab-page/`), `chrome-settings` (`chrome://settings/`), `chrome-passwords` (`chrome://password-manager/`), `chrome-extension-page` (a page of Chrome's built-in PDF viewer extension) and `file-root` (`file:///`) carry a `url`, which the runner uses unless `targets` maps the name to something else. No other URL in the file is one 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`.
+- `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`; `chromeUrlsAttach` means the transport can attach to and drive `chrome://` pages. CDP over a DevTools port can; `chrome.debugger` can't, since Chrome refuses it every `chrome://` page, even with `--extensions-on-chrome-urls`.
 - `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:
@@ -168,8 +170,8 @@ The `C8.newtab` reachability control attaches through the guard to a settled ord
 - `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.
+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", "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.
 
@@ -280,7 +282,10 @@ The optional `close` releases the row's clients; release pooled browsers after
 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.
+of supported names, and a capability that isn't declared is unsupported: a CDP
+transport over a DevTools port declares `chromeUrlsAttach: true`, and an
+extension on `chrome.debugger` leaves it out, so `C8.newtab` is skipped with
+`not-supported:chromeUrlsAttach`. `capabilities.scope` selects owner-specific rows.
 
 Map `ordinary`, `ordinary-same-site`, `seven`, `vault`, `vault-x`, `apex`, `own`
 and `client` to origins. `chrome-newtab`, `chrome-new-tab-page`, `chrome-settings`, `chrome-passwords`, `chrome-extension-page` and `file-root` default to their `url`.
@@ -411,6 +416,7 @@ const capabilities = {
   autoAttach: true,
   browserSession: true,
   browserContexts: true,
+  chromeUrlsAttach: true,
 };
 const execution = await run(set, {
   clientFactory: (metadata) => connectGuardAndObserver(metadata),

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.2",
+  "setVersion": "1.8.4",
   "sources": [
     {
       "repo": "ai-ecoverse/slicc-cli",
@@ -81,7 +81,8 @@
   "capabilities": {
     "autoAttach": "Target.setAutoAttach, the children steps and child sessions",
     "browserSession": "CDP calls on the browser session",
-    "browserContexts": "Target.createBrowserContext and Target.disposeBrowserContext"
+    "browserContexts": "Target.createBrowserContext and Target.disposeBrowserContext",
+    "chromeUrlsAttach": "attaching to and driving chrome:// pages, which CDP over a DevTools port can and chrome.debugger can't"
   },
   "placeholders": {
     "target": "the target's origin; {plain} on the control",
@@ -7805,6 +7806,11 @@
                 "requestStage": "Response"
               }
             ]
+          },
+          "refusable": true,
+          "refusal": {
+            "match": "^slicc: refused",
+            "onlyProtected": true
           }
         },
         {
@@ -7874,6 +7880,7 @@
       "targets": ["seven", "vault", "vault-x", "apex"],
       "observe": {
         "candidates": {
+          "dependsOn": ["refused.2"],
           "means": "attempts is not empty",
           "check": {
             "result": "attempts",
@@ -7885,6 +7892,7 @@
           }
         },
         "refused": {
+          "dependsOn": ["refused.2"],
           "means": "every attempt was refused",
           "check": {
             "refused": ["attempts"],
@@ -7892,6 +7900,7 @@
           }
         },
         "answered": {
+          "dependsOn": ["refused.2"],
           "means": "body is 'real-{tag}'",
           "check": {
             "result": "body",
@@ -7901,6 +7910,7 @@
           }
         },
         "overridden": {
+          "dependsOn": ["refused.2"],
           "means": "the fetch reported the overridden response status",
           "check": {
             "result": "body",
@@ -12386,7 +12396,7 @@
           },
           "session": "browser",
           "as": "attach",
-          "requires": ["browserSession"]
+          "requires": ["browserSession", "chromeUrlsAttach"]
         },
         {
           "page": "navigate",
@@ -12402,7 +12412,7 @@
         }
       ],
       "targets": ["chrome-newtab", "chrome-new-tab-page"],
-      "requires": ["browserSession"],
+      "requires": ["browserSession", "chromeUrlsAttach"],
       "observe": {
         "attached": {
           "means": "the guard attached to the settled new tab page",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-browsers",
-  "version": "1.8.2",
+  "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

@@ -81,7 +81,7 @@
     "capabilities": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["autoAttach", "browserSession", "browserContexts"],
+      "required": ["autoAttach", "browserSession", "browserContexts", "chromeUrlsAttach"],
       "properties": {
         "autoAttach": {
           "type": "string",
@@ -94,6 +94,10 @@
         "browserContexts": {
           "type": "string",
           "minLength": 1
+        },
+        "chromeUrlsAttach": {
+          "type": "string",
+          "minLength": 1
         }
       }
     },
@@ -117,7 +121,7 @@
   },
   "$defs": {
     "capability": {
-      "enum": ["autoAttach", "browserSession", "browserContexts"]
+      "enum": ["autoAttach", "browserSession", "browserContexts", "chromeUrlsAttach"]
     },
     "requires": {
       "type": "array",
@@ -452,6 +456,9 @@
               "additionalProperties": false,
               "required": ["match"],
               "properties": {
+                "onlyProtected": {
+                  "type": "boolean"
+                },
                 "match": {
                   "type": "string",
                   "minLength": 1