@ai-ecoverse/slicc-browsers 1.16.2 → 1.18.0

package/README.md

@@ -189,6 +189,8 @@ Every CDP guard runs the vectors in `guard-vectors.json` (schema `schema/guard-v
 
 `X1.after-exit` (family `X`, client lifecycle) needs `clientExit`. Through the guard, the client opens an ordinary tab, registers `Page.addScriptToEvaluateOnNewDocument` with `{beacon}`, `Network.setExtraHTTPHeaders` with `x-probe: {tag}` and `Fetch.enable` `*` with a rule that fulfils the destination with a forged `FULFILLED` page, then loads the `/page?k=href&tag={tag}&to={target}/canary/{tag}` trigger whose `go()` navigates to `{target}/canary/{tag}`. Before the exit it must see its init-script beacon, its header on the trigger request and the trigger's `Fetch.requestPaused`, matched up to `&to=`, so a guard that redacts the embedded protected URL to its origin still matches: those are the positive evidence on both legs. Then the client exits, the unguarded observer calls `go()`, and the destination must be served and read as the real `canary` document, with no beacon from `{target}`, no `x-probe` on its request, no forged body and no `Fetch.requestPaused` for it reaching the client: nothing the client registered may outlive it. The control runs the same on `{plain}` through the guard, and expects the same, since an ordinary navigation after the exit must be just as clean. A guard that keeps its upstream session, or its own init scripts, headers or interception, past the client's exit fails the row.
 
+`C4.iframe-preattach.blank` and `C4.iframe-preattach.srcdoc` read a protected frame's same-process child that committed before the client attached. The unguarded observer opens `<from>/framed` around `{target}/nest?n=<tag>&kind=blank` or `kind=srcdoc`: the protected frame holds an `about:blank` child that it fills, or an `about:srcdoc` child, each named `frame-marker-<tag>` and showing that marker, and then moves itself with `history.replaceState` to `/nest/path-secret-<tag>?query-secret=<tag>#fragment-secret-<tag>`. `from` is `{ordinary-same-site}` on the guarded leg, so both frames share the page's process under site isolation, and `{plain}` on the control. The `.shared` rows open the page from `{ordinary}` on both legs and require `siteIsolationOff`; a transport without it reports them as `skip` with `not-supported:siteIsolationOff`. The observer must find the child in the page's own frame tree and pierced document, and must see the marker or the secret through every read. Then the client attaches to the settled page and makes the same reads: `Page.getFrameTree`, `Accessibility.getFullAXTree` with the protected frame's and the child's `frameId`, `Accessibility.getPartialAXTree` of the marker element's `backendNodeId` with `fetchRelatives`, `DOM.getDocument` with `depth: -1` and `pierce: true`, `DOM.describeNode` of the child's document and `DOM.getOuterHTML` of the marker element, and `DOMSnapshot.captureSnapshot`. Each `<read>Shown` holds when a reply carries the marker or the secret path, query or fragment, and `eventsShown` when an event on the client's session does. The guarded leg expects all of them false: a refusal, an error or origin-only data passes, and a refused attach refuses every read. The control runs unguarded and expects every read to show the content. Missing evidence is `incomplete`, with `frame-read: <reason>`: no same-process child within 5000 ms (scaled by `settleScale`), an observer read that doesn't show the content (that field reads `incomplete`), a client read or attach that was never answered (an error that says `timed out` or `closed`), or a control attach without a session.
+
 The `C9` foreign extension isolated-world family requires `extensionWorld`: a browser hosting a foreign content-script extension on the ordinary fixture page. `C9.world-hidden` requires the page default context to remain visible after `Runtime.enable`, while the extension context and Runtime/Debugger identifiers remain hidden without cutting or detaching the session. `C9.world-select` probes numeric and unique context selectors, object and argument handles, promises, properties, named bindings and DOM node resolution; each command selecting the hidden world must fail with the `slicc: refused:` prefix, never an ordinary browser error. Numeric guesses also sweep ids 1–32: an id not exposed to this client must be refused, while every exposed numeric context must remain usable; none of those guarded probes may reach the fixture content-script marker. The marker combines the content script’s global lexical `root` binding with its extension-id DOM marker and `chrome.runtime.id`, and is independently required to be absent from the page default world. `C9.world-debugger` pauses inside that content script: the control must reach its frame, while the guard must refuse or hide it. The control waits up to 5000 ms (scaled by `settleScale`) for `Debugger.paused`; when it never pauses, `reachable` records `"incomplete"`, not `false`, and the row fails with `extensionWorld debugger: no Debugger.paused within <ms>ms`. The guarded leg waits up to 1500 ms, scaled by `refusalScale`. `C9.page-drivable` evaluates `self.origin`, captures a DOM snapshot and dispatches an Input click on the same ordinary page; cutting the entire session fails this regression row. All four use an unguarded control, the default browser context and observer discovery of the real extension world, not an invented isolated world. Protected default contexts remain session-cutting evidence; hiding a foreign isolated world does not weaken any seven-origin row.
 
 The integration launcher loads shared-web 1.25.2’s harness extension exactly once through `Extensions.loadUnpacked` (`ankmbodmgimjemnojmeddfcdlbocolob`), whose content script runs on HTTP(S) pages. shared-web 1.25.2 also loads it by default in its own harness. A transport unable to host a foreign content-script extension omits `extensionWorld` and reports `not-supported:extensionWorld`; an advertised capability with no observed world fails, rather than silently skipping.
@@ -205,6 +207,14 @@ Every C2 redirect probe reports `sessionEnded`. It becomes true when the guarded
 
 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 C8 protection 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/`.
 
+`C8.protected-bfcache-restore` and `.history` test history restoration on seven and vault, with both detach variants. The independent observer seeds ordinary A, protected P and ordinary B on one tab. `/bfcache?n=<tag>` has no unload handler: it retains a global and sessionStorage marker, records `pageshow.persisted` and counts key events. The guarded client must answer on B before the gate is armed. The first row restores P with the observer's `Page.navigateToHistoryEntry`; `.history` sends that navigation through the client instead. A matched client navigation refusal lets the observer restore the same entry. The unguarded control must observe a real `BackForwardCacheRestore`, persisted pageshow, the marker and protected origin in evaluate, a touched global, and positive evidence from every probe method.
+
+The rows require `inboundDelay`. The guarded client supplies `inboundDelay({ targetId, sessionId, ms, side, client, gate: true })`, a harness gate before the guard's inbound stream. It holds every browser-to-guard message until explicit release; guard-to-browser writes remain possible. The control gates only its unguarded client stream, not the independent observer session. Immediately before restoration the runner requests a gate with a 1500 ms minimum hold. The hook returns `{ targetId, sessionId, ms, gate: true, protectedObserved, ordinaryObserved, release, audit? }`. Both observed flags acknowledge delivery of the protected seed and subsequent ordinary B through the relevant stream before injection. `release()` restores delivery and returns `{ delayedEvents, firstDelayedAt, releasedAt }`, counting held restore events and recording their first hold and actual release times. Missing capability or hook is `not-supported:inboundDelay`; an unacknowledged gate, absent seed acknowledgement or no held restore event is `incomplete`. A timer-only event delay does not meet this contract.
+
+After the observer confirms the persisted protected document, the client repeatedly probes `Runtime.evaluate`, `Runtime.callFunctionOn`, `DOM.getDocument`, `Accessibility.getFullAXTree`, `Input.dispatchKeyEvent`, `Page.captureScreenshot` and `IO.read` for 2500 ms while the gate stays closed. Runtime probes write `__touched`; Input is measured by the fixture's key counter. The observer supplies a real network-resource stream for IO's positive control: the read must use that handle and show the document marker, including base64-encoded bodies. Screenshot controls must return PNG bytes captured while P is current that match the independent observer's capture of P; unrelated or merely nonempty data is not evidence. The guard must hide the marker from all received messages and events and hide the protected origin from every probe reply, not only Runtime replies, and leave both side effects absent on P. A returned screenshot while P is current fails, regardless of its encoded contents. Refused, answered and unanswered outcomes are retained individually; an unanswered call alone never proves protection. The observer measures P's marker, persisted state and side effects before and after release. Missing restore, fixture, hold or side-effect evidence is `incomplete`, even when every measured observation matches; measured leaks or side effects fail even beside missing evidence. After release the runner drains probe replies for up to 5000 ms, scaled by `settleScale`, before scanning them and judging screenshots. An unresolved reply needs a complete final forwarding ledger proving terminal non-forwarding; otherwise its missing measurement is `incomplete`. A measured failure takes precedence over incomplete evidence.
+
+`forwardAudit` gates only `commandsUnforwarded`. When advertised, `audit({ probes, final })` must return `{ complete: true, probes: [{ id, forwarded }] }` with a browser-side forwarding decision for every probe id; any probe sent while the gate is armed that was forwarded fails, even when its frame state was unknown. The gate-window audit runs before release. The final audit runs after reply settlement and certifies terminal forwarding decisions, including commands queued at release; its ledger must remain available after `release()`. An observed forward fails even beside a partial ledger. Guard-generated internal calls and the history trigger are not probe calls. A missing or partial ledger is `incomplete`. Without the capability the audit is `not-supported`, and the independent side-effect, leak and screenshot checks remain required. Each row's `evidence.control.restore` and `evidence.guarded.restore` retains gate acknowledgement/release, the restore timestamp, every probe's send time and outcome, forwarding evidence when available, and the independent side-effect reads. Cleanup releases the gate and closes only that row's targets, streams and sessions.
+
 `C8.protected-error-page` touches an allowed tab, scripts a protected navigation, and requires the guard to fail its Document request. The independent observer verifies the committed error document and the exact unreachable/reported URL pair. The session stays attached; reload, navigation to `about:blank` and close succeed, while `Target.getTargetInfo`, `Target.getTargets`, the `Target.attachedToTarget` of a fresh attach and the `targetCreated`/`targetInfoChanged` events redact URL and title to the origin (`infoRedacted`, `listRedacted`, `attachRedacted`, `eventsRedacted`), and none of them shows the full failed URL (`fullURL`). The failed URL carries a secret path, `?query` and `#fragment`; the `.query` and `.fragment` variants of this row and of `C8.protected-error-page-sticky` fail `/doc?query-secret=…` and `/doc#fragment-secret-…` instead, so no path, query or fragment secret may survive alone either. The unguarded control uses independent Fetch failure injection and keeps raw discovery values: its `fullURL` must be `true`. `C8.protected-document-restore` seeds a real protected document before attachment, navigates away, then restores it from BFCache in the same tab after the error/recovery sequence; evaluate, attach and close must be refused. A real `BackForwardCacheRestore` commit is required, so a second failed network request cannot masquerade as this control. `C8.protected-error-page-sticky` additionally fails a request after that real protected restore and requires the already-protected tab to remain locked. They run on browser-session and page-session-only transports alike, have unguarded controls and clean up their own targets. The regression tests include URL-only locking, unconditional error-page unlocking, and a plain client with only request-failure injection.
 
 `C8.network-error` and `C8.iframe-error` are ordinary-error reachability controls: request the configured `network-error` URL (default `http://nonexistent.invalid/`) directly or in an ordinary iframe, observe a failed Document request, reattach to the settled tab, evaluate and snapshot its document, then navigate the same tab to an ordinary document. Both control and guarded legs must pass. The failing URL is unchanged on the control, rather than replaced with a healthy origin, and the rows require `browserSession` but not `chromeUrlsAttach`. With Chrome for Testing 156.0.8078.4, scheme-wide `chrome-error` protection made the direct-error row fail both legs because reattachment was refused; removing it passed both rows, with readable DOM and successful recovery. The old emulator still allowed the cross-process iframe parent because the iframe TargetInfo kept the failing HTTP URL, but that layout-specific behavior is not grounds for protecting the error scheme. Plain-client controls and reachability legs also passed both rows.
@@ -218,7 +228,7 @@ A client may register `Fetch.enable` patterns naming a protected origin in eithe
 - `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-search`, `network-error`, `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-search` (`chrome-search://most-visited/`), `network-error` (`http://nonexistent.invalid/`), `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`; `extensionWorld` means it can host a foreign content-script extension isolated world on the ordinary fixture; `discovery` means session-less `Target.setDiscoverTargets` and `Target.targetCreated`/`Target.targetInfoChanged` delivery; `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`. `clientExit` means the harness can close the guarded client in the middle of a row: the client has `close()`, the `clientFactory` makes a fresh guarded client for the next leg, and an unguarded observer independent of the client outlives it.
+- `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`; `extensionWorld` means it can host a foreign content-script extension isolated world on the ordinary fixture; `discovery` means session-less `Target.setDiscoverTargets` and `Target.targetCreated`/`Target.targetInfoChanged` delivery; `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`. `clientExit` means the harness can close the guarded client in the middle of a row: the client has `close()`, the `clientFactory` makes a fresh guarded client for the next leg, and an unguarded observer independent of the client outlives it. `siteIsolationOff` means the browser runs without site isolation, so a cross-site iframe shares its parent's process.
 - `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:
@@ -264,6 +274,7 @@ Popups are observed by `Target.targetCreated` with the opener's `openerId`, or b
 - `/data?n=`: `real-<n>`, with CORS;
 - `/script?n=`: a script setting `globalThis.vectorScript` to `real-<n>`;
 - `/page?k=&to=`: a trigger page whose `go()` sends the page to `to` (`k=href`, `replace`, `popup` or `form`), and `/canary/<tag>`: a document titled `canary` with the marker;
+- `/nest?n=&kind=` (and any path under `/nest`): the `C4.iframe-preattach` frame, with its `about:blank` or `about:srcdoc` child;
 - `/img`: a 1×1 PNG;
 - `/auth`: Basic `u`:`p`, then `authed`;
 - `/rewritten` (title `rewritten`);
@@ -280,6 +291,10 @@ Popups are observed by `Target.targetCreated` with the opener's `openerId`, or b
 
 For remote/page harnesses, `fixtureClient(base)` is exported by `./guard-runner` and `./fixture-client`, or `run(set, { fixtureBase: base, ... })` constructs it. The bundled server serves CORS-safe `GET /log?since=N` as `{ from: N, entries: [...] }`, with an append-only history unaffected by `fixture.reset()`, and `POST /redirect` with a JSON-encoded string body (a simple text/plain request, without a preflight). Control requests do not appear in the log. Registration descriptors are `{ path, host?, search?, to?, code?, body, remove? }`: `path` starts with `/`, `host` selects the callback hostname, `search` distinguishes query-bearing callbacks, `to` creates a redirect with the four Location/Content-Location/Refresh/Link headers, `code` defaults to 302, an omitted `to` serves the callback body, and `remove: true` unregisters it. The bundled endpoint returns 204; custom servers must acknowledge with a successful status and actually serve the registered routes. Custom fixtures may instead supply an async `fixture.redirectSecret` hook directly; a separate log/control server can implement the same `GET /log` and `POST /redirect` contract. A Node harness using browser-only DNS aliases should pass a reachable `fixtureBase` or its direct hook.
 
+`{ "bfcacheRestore": "observer" | "history", "origin": "{protectedTarget}", "as": "restore", "requires": ["inboundDelay"] }` runs the history-restore compound probe. `{protectedTarget}` is the row target on both legs, so the unguarded control exercises the same protected fixture origin.
+
+`{ "frameRead": "blank" | "srcdoc", "from", "as": "frames", "on"?, "requires"? }` runs the `C4.iframe-preattach` compound probe: the observer's page and reads, then the client's attach and reads, with boolean evidence for ordinary `result` checks.
+
 `{ "unparseable": true, "as": "unparseable" }` runs the C8 malformed-URL compound probe on the current ordinary page: independent browser ground truth, raw/canonical destination commands, discovery/attach and cookie checks. Boolean evidence is consumed by ordinary `result` checks, with native Chrome outcomes retained in its diagnostics.
 
 **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`.
@@ -404,13 +419,13 @@ every alternative of an `any`, or a required (`all`, `not` or plain) check, need
 selects one variant or an array; omission selects all. `parallel` defaults to 1.
 With the `browserContexts` capability each leg runs in its own browser context. A `Target.createBrowserContext` that fails with a timeout is retried once, and the row's `notes` records it; any other failure fails the row.
 
-Every target created by the runner’s own unguarded observer uses `Target.createTarget` with `newWindow: true`, then verifies through `Target.getTargetInfo` that `openerId` is absent. A supplied opener or missing target evidence fails and cleans up that target (in the protected-error-page probe, the row is `incomplete` instead), rather than inheriting the active client tab (which could be seven). This includes ordinary control setup, storage canaries, protected-error history seeds and the malformed-URL observer. The row notes record `newWindow=true, openerId absent`. Intentional guarded-client creation commands and popup/opener tests keep their original parameters.
+Every target created by the runner’s own unguarded observer uses `Target.createTarget` with `newWindow: true`, then verifies through `Target.getTargetInfo` that `openerId` is absent. A supplied opener or missing target evidence fails and cleans up that target (in the protected-error-page probe, the row is `incomplete` instead), rather than inheriting the active client tab (which could be seven). This includes ordinary control setup, storage canaries, protected-error history seeds, the frame-read page and the malformed-URL observer. The row notes record `newWindow=true, openerId absent`. Intentional guarded-client creation commands and popup/opener tests keep their original parameters.
 
 `settleScale` (default 1) multiplies the bounds of waits for events the leg expects to happen: settles (beacon, served, title and load) on the control leg and `required` settles on either leg, `paused` on the control leg, page and child loads, the wait for a background step's `as` result (`<as> did not complete within <ms>ms`), the wait for the pre-action beacons, the C9 control's `Debugger.paused`, and the wait for an observation the leg expects to be `true`. Adopters on slow hosts can set 3 or 4. Every wait polls and returns as soon as its event arrives, so a larger bound only costs time when something is really missing, and each timeout error names the bound it used. An observation read from the fixture (`observer: "fixture"`, such as a beacon or a served request) that the leg expects to be `true` is polled for up to 5000 ms (scaled) instead of read once. One that the leg expects to be `false` is still read once.
 
 `refusalScale` (default 1) multiplies the bounds of waits for what the guarded leg expects to be absent, the beacon, request, title or navigation that the guard should block: settles that are not `required`, and `paused`, on the guarded leg. Such a wait runs to its full bound whenever the guard works, so `settleScale` leaves it alone. The trade-off: a larger `refusalScale` gives more sensitivity to a leak that arrives late on a slow host, because the observations after the wait see it, at the cost of that much more time per guarded row. Adopters should keep `refusalScale` at 1 or higher, never below 1; the runner refuses a `refusalScale` below 1 with `refusalScale must be a number of at least 1`.
 
-**Incomplete.** A probe that returns `incomplete` (only `errorPage` and `redirectSecret` steps) records the reason in the row's `incomplete` as `<leg> <probe>: <reason>`. Its unmeasured observations read `"incomplete"`, and so does guarded liveness when the probe never measured it. A leg whose measured observations all match is then `incomplete`, never `pass`, and `live` is `incomplete` when only its evidence is missing; a measured mismatch still makes the leg `fail`, and any row error still fails both legs. `summary()` counts `incomplete` per leg, returns the number of rows with any `incomplete` status as `incomplete`, appends `incomplete <n>` to `line`, and never passes such a run. A leg that throws keeps the errors it recorded before the throw.
+**Incomplete.** A probe that returns `incomplete` (including `errorPage`, `redirectSecret`, `frameRead` and `bfcacheRestore` steps) records the reason in the row's `incomplete` as `<leg> <probe>: <reason>`. Its unmeasured observations read `"incomplete"`, and so does guarded liveness when the probe never measured it. A leg whose measured observations all match is then `incomplete`, never `pass`, and `live` is `incomplete` when only its evidence is missing; a measured mismatch still makes the leg `fail`, and any row error still fails both legs. `summary()` counts `incomplete` per leg, returns the number of rows with any `incomplete` status as `incomplete`, appends `incomplete <n>` to `line`, and never passes such a run. A leg that throws keeps the errors it recorded before the throw.
 
 `onStart(row)` receives each row's `id`, `target`, `variant`, `transport` and `via` as the row starts. `run()` returns a promise that also has `inFlight()`, and its result has `inFlight` too. `inFlight()` lists the rows that are running now, each as `{ id, target, variant, leg, phase, step, clients }`, where `step` is the index of the current step in its `phase` (`setup`, `trigger` or `child`), and `clients` lists each client's pending CDP calls as `{ method, session, ageMs }` (`client`, plus `unguarded` when it is a separate client). With `rowTimeoutMs`, a row still running after that many milliseconds fails on its own. Its `errors` hold `row timed out after <ms>ms: <the in-flight view>`, `inFlight` holds the view, and the clients that `clientFactory` made for it are closed. The run then goes on to the next row. It is off by default, and a client passed as `client` is never closed.
 
@@ -517,7 +532,7 @@ Without `tls`, the server and logged URLs remain HTTP. It returns
 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 protection expectations must fail; the `C8.newtab` reachability control and `X1.after-exit`, whose plain client leaves nothing behind when it exits, must instead pass both legs. For a single
+invocation: controls must pass and guarded protection expectations must fail; the `C8.newtab` reachability control and `X1.after-exit`, whose plain client leaves nothing behind when it exits, must instead pass both legs. Rows that require `siteIsolationOff` run in one more Chromium launched without site isolation. 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.
 

package/bfcache-restore.mjs

@@ -0,0 +1,514 @@
+import { outcome, waitFor } from './guard-driver.mjs';
+import { createObserverTarget } from './observer-target.mjs';
+import { containsSecret } from './redirect-secret.mjs';
+
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const refusal = (out) =>
+  !out.ok &&
+  /^(slicc: refused:)|session.*(closed|not found)|no session|target.*closed/i.test(
+    out.error?.message ?? ''
+  );
+const value = (out) =>
+  out.ok && !out.result?.exceptionDetails ? out.result?.result?.value : undefined;
+const png = (data) => {
+  try {
+    return typeof data === 'string' && atob(data).startsWith('\x89PNG\r\n\x1a\n');
+  } catch {
+    return false;
+  }
+};
+const methods = [
+  'Runtime.evaluate',
+  'Runtime.callFunctionOn',
+  'DOM.getDocument',
+  'Accessibility.getFullAXTree',
+  'Input.dispatchKeyEvent',
+  'Page.captureScreenshot',
+  'IO.read',
+];
+
+async function bounded(work, ms) {
+  let timer;
+  const expired = new Promise((resolve) => {
+    timer = setTimeout(() => resolve({ ok: false, error: { message: 'no answer' } }), ms);
+  });
+  const out = await Promise.race([outcome(work), expired]);
+  clearTimeout(timer);
+  return out;
+}
+
+class Restore {
+  constructor(options) {
+    Object.assign(this, options);
+    this.marker = `bfcache-marker-${this.tag}`;
+    this.url = `${this.protectedOrigin}/bfcache?n=${encodeURIComponent(this.tag)}`;
+    this.result = { probes: [], delay: { requestedMs: this.delayMs } };
+    this.missing = [];
+    this.pending = [];
+    this.probeId = 0;
+  }
+
+  missingEvidence(reason) {
+    this.missing.push(reason);
+    return false;
+  }
+
+  read(method, params, session = method.startsWith('Target.') ? undefined : this.observer) {
+    return bounded(this.reader.send(method, params, session), this.budget);
+  }
+
+  call(method, params) {
+    return bounded(this.client.send(method, params, this.session), this.budget);
+  }
+
+  async frame() {
+    return (await this.read('Page.getFrameTree', {})).result?.frameTree?.frame;
+  }
+
+  async state() {
+    return value(
+      await this.read('Runtime.evaluate', {
+        expression:
+          '({origin:location.origin,marker:globalThis.__bfcacheMarker,stored:sessionStorage.getItem("bfcache-marker"),persisted:globalThis.__bfcachePersisted,touched:globalThis.__touched,keys:globalThis.__bfcacheKeys||0})',
+        returnByValue: true,
+      })
+    );
+  }
+
+  loaded(destination) {
+    return waitFor(async () => {
+      const f = await this.frame();
+      return (
+        f?.url === destination &&
+        !f.unreachableUrl &&
+        value(
+          await this.read('Runtime.evaluate', {
+            expression: 'document.readyState',
+            returnByValue: true,
+          })
+        ) === 'complete'
+      );
+    }, this.budget);
+  }
+
+  async attach() {
+    this.session = (
+      await bounded(
+        this.client.send('Target.attachToTarget', { targetId: this.targetId, flatten: true }),
+        this.budget
+      )
+    ).result?.sessionId;
+    return Boolean(this.session);
+  }
+
+  async seed() {
+    this.observer = (
+      await this.read('Target.attachToTarget', { targetId: this.targetId, flatten: true })
+    ).result?.sessionId;
+    if (!this.observer) return this.missingEvidence('observer attach unanswered');
+    await this.read('Page.enable', {});
+    if (!(await this.loaded(`${this.ordinary}/bfcache?n=${this.tag}-a`)))
+      return this.missingEvidence('ordinary A did not commit');
+    if (!(await this.attach())) return this.missingEvidence('initial client attach unanswered');
+    await this.call('Page.enable', {});
+    await this.read('Page.navigate', { url: this.url });
+    if (!(await this.loaded(this.url)))
+      return this.missingEvidence('protected seed did not commit');
+    const state = await this.state();
+    if (state?.marker !== this.marker || state.stored !== this.marker)
+      return this.missingEvidence('protected fixture marker absent');
+    const lock = await this.call('Runtime.evaluate', {
+      expression: 'location.origin',
+      returnByValue: true,
+    });
+    this.result.protectedLocked = refusal(lock);
+    this.result.seed = { protectedURL: this.url, lock };
+    const b = `${this.ordinary}/bfcache?n=${this.tag}-b`;
+    await this.read('Page.navigate', { url: b });
+    if (!(await this.loaded(b))) return this.missingEvidence('ordinary B did not commit');
+    await bounded(
+      this.client.send('Target.detachFromTarget', { sessionId: this.session }),
+      this.budget
+    );
+    const live = (await this.attach())
+      ? await this.call('Runtime.evaluate', { expression: 'location.href', returnByValue: true })
+      : { ok: false };
+    this.result.sessionLive = value(live) === b;
+    this.result.seed.ordinaryAnswer = live;
+    if (!this.result.sessionLive) return false;
+    await this.call('Page.enable', {});
+    const history = await this.read('Page.getNavigationHistory', {});
+    this.entry = history.result?.entries?.find((item) => item.url === this.url);
+    return Boolean(this.entry) || this.missingEvidence('protected history entry absent');
+  }
+
+  async install() {
+    const { targetId, session, delayMs: ms, side, client } = this;
+    const installed = await outcome(
+      this.delayClient.inboundDelay({ targetId, sessionId: session, ms, side, client, gate: true })
+    );
+    this.delay = installed.result;
+    this.gate = this.delay;
+    const delay = this.delay;
+    this.result.delay.seeding = {
+      protectedObserved: delay?.protectedObserved,
+      ordinaryObserved: delay?.ordinaryObserved,
+    };
+    this.result.delay.acknowledged =
+      installed.ok &&
+      delay?.ms === ms &&
+      delay.targetId === targetId &&
+      delay.sessionId === session &&
+      delay.protectedObserved === true &&
+      delay.ordinaryObserved === true &&
+      delay.gate === true;
+    return (
+      (this.result.delay.acknowledged && typeof delay.release === 'function') ||
+      this.missingEvidence('inbound delay not acknowledged')
+    );
+  }
+
+  async trigger() {
+    const params = { entryId: this.entry.id };
+    const out =
+      this.mode === 'history'
+        ? await this.call('Page.navigateToHistoryEntry', params)
+        : await this.read('Page.navigateToHistoryEntry', params);
+    this.result.trigger = out;
+    if (this.mode === 'history' && refusal(out))
+      await this.read('Page.navigateToHistoryEntry', params);
+  }
+
+  async probe(method, params, current) {
+    const sentAt = Date.now();
+    const record = { id: ++this.probeId, params, method, sentAt, protectedCurrent: current };
+    this.result.probes.push(record);
+    const work = this.client.send(method, params, this.session);
+    const out = await bounded(work, Math.min(this.budget, 250));
+    this.answer(record, out);
+    record.windowOutcome = record.outcome;
+    this.pending.push(
+      outcome(work).then((answer) => {
+        this.answer(record, answer);
+        record.answeredAt = Date.now();
+      })
+    );
+    return out;
+  }
+
+  answer(record, out) {
+    record.outcome = refusal(out)
+      ? 'refused'
+      : out.error?.message === 'no answer'
+        ? 'no answer'
+        : 'answered';
+    record.reply = out;
+  }
+
+  async round() {
+    const f = await this.frame();
+    const current = f?.url === this.url && !f.unreachableUrl;
+    const restored = this.reader.events
+      .slice(this.eventStart)
+      .some(
+        (event) =>
+          event.sessionId === this.observer &&
+          event.method === 'Page.frameNavigated' &&
+          event.params?.type === 'BackForwardCacheRestore' &&
+          event.params.frame?.url === this.url
+      );
+    if (restored && this.result.restoreAt === undefined) this.result.restoreAt = Date.now();
+    const expression =
+      'globalThis.__touched=1; JSON.stringify({origin:location.origin,marker:globalThis.__bfcacheMarker,stored:sessionStorage.getItem("bfcache-marker")})';
+    const calls = [
+      this.probe('Runtime.evaluate', { expression, returnByValue: true }, current),
+      this.probe('DOM.getDocument', { depth: -1, pierce: true }, current),
+      this.probe('Accessibility.getFullAXTree', {}, current),
+      this.probe('Page.captureScreenshot', { format: 'png' }, current),
+      this.probe('IO.read', { handle: this.stream ?? 'unavailable-stream' }, current),
+      this.probe(
+        'Input.dispatchKeyEvent',
+        { type: 'keyDown', key: 'x', code: 'KeyX', windowsVirtualKeyCode: 88 },
+        current
+      ),
+    ];
+    calls.push(
+      this.probe(
+        'Runtime.callFunctionOn',
+        {
+          executionContextId: this.contextId,
+          functionDeclaration:
+            'function(){this.__touched=1;return JSON.stringify({origin:location.origin,marker:this.__bfcacheMarker})}',
+          returnByValue: true,
+        },
+        current
+      )
+    );
+    await Promise.all(calls);
+  }
+
+  async window() {
+    this.eventStart = this.reader.events.length;
+    this.clientStart = this.client.events.length;
+    this.messageStart = this.client.messages?.length ?? 0;
+    this.result.delay.startedAt = Date.now();
+    const trigger = this.trigger();
+    const restored = await waitFor(async () => {
+      const f = await this.frame();
+      return f?.url === this.url && !f.unreachableUrl && (await this.state())?.persisted === true;
+    }, this.budget);
+    if (!restored) this.missingEvidence('protected restore before probes not observed');
+    const f = await this.frame();
+    const contextStart = this.reader.events.length;
+    await this.read('Runtime.enable', {});
+    this.contextId = this.reader.events
+      .slice(contextStart)
+      .find(
+        (event) =>
+          event.sessionId === this.observer &&
+          event.method === 'Runtime.executionContextCreated' &&
+          event.params?.context?.auxData?.isDefault &&
+          event.params.context.auxData.frameId === f?.id
+      )?.params.context.id;
+    this.result.screenshotProof = {
+      capturedAt: Date.now(),
+      url: f?.url,
+      reply: await this.read('Page.captureScreenshot', { format: 'png' }),
+    };
+    const resource = await this.read('Network.loadNetworkResource', {
+      frameId: f?.id,
+      url: this.url,
+      options: { disableCache: true, includeCredentials: false },
+    });
+    this.stream = resource.result?.resource?.stream;
+    this.result.probeStartedAt = Date.now();
+    do {
+      await this.round();
+      await pause(25);
+    } while (Date.now() - this.result.probeStartedAt < this.windowMs);
+    this.result.beforeRelease = await this.state();
+    await this.audit();
+    const released = await outcome(this.delay.release());
+    this.result.delay.release = released;
+    this.delay = undefined;
+    await trigger;
+    await this.settleProbes();
+    if (
+      !released.ok ||
+      !(released.result?.delayedEvents > 0) ||
+      !(released.result.firstDelayedAt >= this.result.delay.startedAt) ||
+      !(released.result.releasedAt >= released.result.firstDelayedAt + this.delayMs)
+    )
+      this.missingEvidence('held restore events not proven');
+  }
+
+  async settleProbes() {
+    await waitFor(
+      () => this.result.probes.every((probe) => probe.answeredAt !== undefined),
+      this.budget
+    );
+    await this.audit(true);
+    if (
+      this.result.probes.some(
+        (probe) =>
+          probe.answeredAt === undefined && !(this.finalAuditComplete && probe.forwarded === false)
+      )
+    )
+      this.missingEvidence('probe replies or terminal non-forwarding evidence unavailable');
+  }
+
+  async audit(final = false) {
+    if (!this.forwardAudit) {
+      this.result.commandsUnforwarded = 'not-supported';
+      this.notes.push('commandsUnforwarded: not-supported:forwardAudit');
+      return;
+    }
+    const audit = await outcome(
+      typeof this.gate.audit === 'function'
+        ? this.gate.audit({ probes: this.result.probes, final })
+        : Promise.reject(new Error('forwarding audit unavailable'))
+    );
+    this.result.delay[final ? 'finalAudit' : 'audit'] = audit;
+    const entries = Array.isArray(audit.result?.probes) ? audit.result.probes : [];
+    const complete =
+      audit.ok &&
+      audit.result?.complete === true &&
+      entries.length === this.result.probes.length &&
+      new Set(entries.map((entry) => entry.id)).size === entries.length &&
+      this.result.probes.every((probe) =>
+        entries.some((entry) => entry.id === probe.id && typeof entry.forwarded === 'boolean')
+      );
+    for (const probe of this.result.probes) {
+      const matches = entries.filter((entry) => entry.id === probe.id);
+      probe.forwarded = matches.some((entry) => entry.forwarded === true)
+        ? true
+        : matches.find((entry) => entry.forwarded === false)?.forwarded;
+    }
+    const forwarded =
+      this.result.commandsUnforwarded === false ||
+      this.result.probes.some((probe) => probe.forwarded);
+    this.result.commandsUnforwarded = forwarded ? false : complete ? true : 'incomplete';
+    if (final) this.finalAuditComplete = complete;
+    if (!complete) this.missingEvidence('forwarding audit unavailable');
+  }
+
+  async judge() {
+    const state = await this.state();
+    const { result, marker, protectedOrigin } = this;
+    result.sideEffect = state;
+    result.restoredObserved =
+      result.restoreAt !== undefined &&
+      state?.origin === protectedOrigin &&
+      state.marker === marker &&
+      state.stored === marker &&
+      state.persisted === true;
+    if (!result.restoredObserved) {
+      result.restoredObserved = 'incomplete';
+      this.missingEvidence('real protected BFCache restore not observed');
+    }
+    const delivered = [
+      ...result.probes.map((item) => item.reply),
+      ...this.client.events
+        .slice(this.clientStart)
+        .filter((event) => event.sessionId === this.session),
+      ...(this.client.messages?.slice(this.messageStart) ?? []),
+    ];
+    result.markerHidden = !containsSecret(delivered, marker);
+    result.originHidden = !containsSecret(
+      result.probes.map((item) => item.reply),
+      protectedOrigin
+    );
+    result.sideEffectAbsent = this.effects([result.beforeRelease, state]);
+    if (result.sideEffectAbsent === 'incomplete')
+      this.missingEvidence('side-effect read unavailable');
+    const protectedProbes = result.probes.filter((item) => item.protectedCurrent);
+    result.probesRefusedOrUnforwarded =
+      result.probes.length > 0 &&
+      result.probes.every((item) => ['refused', 'no answer'].includes(item.outcome));
+    result.probeRanInProtected = protectedProbes.some(
+      (item) =>
+        item.method === 'Runtime.evaluate' &&
+        String(value(item.reply)).includes(marker) &&
+        String(value(item.reply)).includes(protectedOrigin)
+    );
+    result.touched = state?.touched === 1;
+    result.methodsProven = methods.every((method) =>
+      protectedProbes.some((item) => item.method === method && this.proven(item, state))
+    );
+    if (this.side === 'control') this.control();
+  }
+
+  proven(probe, state) {
+    if (!probe.reply.ok || probe.reply.result?.exceptionDetails) return false;
+    if (probe.method === 'Input.dispatchKeyEvent') return state?.keys > 0;
+    if (probe.method === 'IO.read')
+      return (
+        this.stream &&
+        probe.params.handle === this.stream &&
+        containsSecret(probe.reply.result?.data, this.marker)
+      );
+    if (probe.method === 'Page.captureScreenshot') {
+      const proof = this.result.screenshotProof;
+      const data = probe.reply.result?.data;
+      return (
+        proof?.url === this.url && proof.reply.ok && png(data) && data === proof.reply.result?.data
+      );
+    }
+    return containsSecret(probe.reply, this.marker);
+  }
+
+  effects(states) {
+    const measured = (state) =>
+      state?.origin === this.protectedOrigin &&
+      state.marker === this.marker &&
+      Number.isInteger(state.keys);
+    if (
+      states.some(
+        (state) =>
+          state?.origin === this.protectedOrigin &&
+          state.marker === this.marker &&
+          (state.touched === 1 || state.keys > 0)
+      )
+    )
+      return false;
+    return states.every(measured) ? true : 'incomplete';
+  }
+
+  control() {
+    if (!this.result.methodsProven) {
+      this.result.methodsProven = 'incomplete';
+      this.missingEvidence('positive probe methods not observed');
+    }
+    if (!this.result.probeRanInProtected || !this.result.touched) {
+      if (!this.result.probeRanInProtected) this.result.probeRanInProtected = 'incomplete';
+      if (!this.result.touched) this.result.touched = 'incomplete';
+      this.missingEvidence('positive protected probes not observed');
+    }
+  }
+
+  async run() {
+    const opened = await outcome(
+      createObserverTarget(
+        this.reader,
+        { url: `${this.ordinary}/bfcache?n=${this.tag}-a`, background: true },
+        this.notes
+      )
+    );
+    if (!opened.ok) {
+      this.missingEvidence(opened.error.message);
+    } else {
+      this.targetId = opened.result.targetId;
+      try {
+        if ((await this.seed()) && (await this.install())) {
+          await this.window();
+          await this.judge();
+        }
+      } finally {
+        if (this.delay?.release) this.result.delay.release = await outcome(this.delay.release());
+        if (this.session)
+          await bounded(
+            this.client.send('Target.detachFromTarget', { sessionId: this.session }),
+            this.budget
+          );
+        if (this.stream) await this.read('IO.close', { handle: this.stream });
+        if (this.observer) await this.read('Target.detachFromTarget', { sessionId: this.observer });
+        await this.read('Target.closeTarget', { targetId: this.targetId }, undefined);
+      }
+    }
+    return this.missing.length
+      ? { ...this.result, incomplete: `bfcache-restore: ${this.missing.join('; ')}` }
+      : this.result;
+  }
+}
+
+export function bfcacheRestore({
+  client,
+  reader,
+  ordinary,
+  protectedOrigin,
+  tag,
+  mode,
+  side,
+  delayClient = client,
+  notes = [],
+  budget = 5000,
+  forwardAudit = true,
+  delayMs = 1500,
+  windowMs = delayMs + 1000,
+}) {
+  return new Restore({
+    client,
+    reader,
+    ordinary,
+    protectedOrigin,
+    tag,
+    mode,
+    side,
+    delayClient,
+    notes,
+    budget,
+    forwardAudit,
+    delayMs,
+    windowMs,
+  }).run();
+}