scenescout 3.7.0 → 3.8.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # scenescout
 
+## 3.8.0
+
+### Minor Changes
+
+- 09a1ff0: Snapshots list the page's frames (same- or cross-origin, title, size, hidden ones as a count) and say their contents were not explored, and a page whose content is all in frames is no longer called a dead end. A write that a cross-origin frame, such as an embedded third-party form, sends outside the app is refused in every mode except destructive, a cross-origin frame's document is sandboxed against popups and moving the whole page, and once an embed has moved the session's page to its own site, that page's writes to another site are refused unless they are a sign-in request. On the app's own sign-in pages (a last path segment such as `login` or `sign-in`) a captcha frame's writes still go out, outside observe.
+
 ## 3.7.0
 
 ### Minor Changes

package/dist/engine/browser.js

@@ -1,4 +1,4 @@
-import { chromium, firefox, webkit } from "playwright";
+import { chromium, firefox, webkit, } from "playwright";
 import fs from "node:fs";
 import path from "node:path";
 import { elementKey, fingerprintState, isNonPageRoute, normalizePath } from "./fingerprint.js";
@@ -7,7 +7,7 @@ import { normalizeTask } from "./task.js";
 import { CLAIM_SCAN_SCRIPT, findContradictions } from "./claims.js";
 import { describeInjection, newInjections, probeQueries, probeScript, probeShape, rememberProbe } from "./injection.js";
 import { AuthLossTracker } from "./authloss.js";
-import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, displayName, missingName, } from "./collector.js";
+import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGES_SCRIPT, brokenImageIssues, frameLines, hasVisibleFrame, displayName, missingName, } from "./collector.js";
 import { OracleMonitor, formatViolations } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
@@ -20,7 +20,7 @@ import { explainLaunchFailure, isMissingBrowser } from "./launch.js";
 import { ACTION_TIMEOUT_MS, performScroll, probeFocusIndicators, probeOverlays, scrollContainer } from "./probes.js";
 import { BROWSER_MARKER, reapOrphanBrowsers } from "./reaper.js";
 import { planUploadOptions, resolveDiskUpload } from "./uploads.js";
-import { answersWithRefusal, destructiveRefusal, isDestructive, isDestructiveWire, allowsWrite, policyRefusal, isAuthExempt, } from "./policy.js";
+import { answersWithRefusal, destructiveRefusal, isDestructive, isDestructiveWire, allowsWrite, policyRefusal, foreignFrameOrigin, foreignWrite, withForeignFrameSandbox, offAppPageWrite, EmbedMoveTracker, sandboxedRedirectPage, allowsForeignWriteOnSignIn, isAuthExempt, } from "./policy.js";
 import { scanProject } from "../scan.js";
 import { analyzeDesign, DESIGN_COLLECT_SCRIPT } from "./design.js";
 import { acceptMatches, generatedUpload } from "./fixtures.js";
@@ -52,6 +52,33 @@ const CHOOSER_GRACE_MS = 2000;
 const HOVER_REVEAL_WINDOW_MS = 2500;
 /** Non-GET traffic that is auth/telemetry plumbing, not tester-caused state mutation. */
 const BENIGN_MUTATION_RE = /\/auth\/(refresh|token|session)|refresh[-_]?token|\/telemetry|\/analytics|\/heartbeat|\/sentry|\/collect\b|\/logs?\b|\/metrics\b/i;
+/**
+ * What the policy needs to know about where a request came from: the URLs of
+ * the frame that sent it and of its parents, up to but not including the top
+ * document, and that frame's own URL (null when the browser attributes it to no
+ * frame, as for a new window or a service worker).
+ */
+function requestSource(req) {
+    const frameChain = [];
+    let frame;
+    try {
+        frame = req.frame();
+    }
+    catch {
+        return { frameChain, frameUrl: null };
+    }
+    const frameUrl = frame.url();
+    const top = frame.page().mainFrame();
+    while (frame && frame !== top) {
+        frameChain.push(frame.url());
+        frame = frame.parentFrame();
+    }
+    return { frameChain, frameUrl };
+}
+/** The `why` of a top-window navigation refused as a possible frame escape; the notice words it on its own. */
+const ESCAPE_REFUSAL = "a possible frame escape";
+/** How long a snapshot waits for its frames' elements to answer. */
+const FRAME_READ_MS = 1500;
 /** In-page XPath lookup fragment for string-expression evaluates. */
 function xpathLookup(xpath) {
     return `document.evaluate(${JSON.stringify(xpath)}, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue`;
@@ -616,6 +643,7 @@ export class BrowserEngine {
         this.contradictionsReported = new Set();
         this.pendingCreations = new Set();
         this.baseUrl = opts.url.replace(/\/$/, "");
+        this.embedMoves = new EmbedMoveTracker(this.baseUrl);
         // Ownership (ownedIds/createdResources) deliberately NOT reset here: it
         // lives on the shared MemoryStore for the whole run, so re-attaching one
         // role must not discard what another role already created — otherwise
@@ -688,6 +716,17 @@ export class BrowserEngine {
             this.watchResponse(res.request(), res.status());
         });
         this.context.on("request", (req) => {
+            // Who moved the driven page, decided on its navigation's first request
+            // (this event fires before the route handler judges that page's writes).
+            if (req.isNavigationRequest() && !req.redirectedFrom()) {
+                try {
+                    if (this.page && req.frame() === this.page.mainFrame())
+                        this.embedMoves.navigationStarted(req.url(), req.headers()["referer"], this.embeddedSites());
+                }
+                catch {
+                    /* no frame: not the driven page */
+                }
+            }
             this.inFlight += 1;
             this.lastRequestStart = Date.now();
             const type = req.resourceType();
@@ -716,6 +755,13 @@ export class BrowserEngine {
                 return;
             if (this.readOnly && isDestructiveWire(pathnameOf(req.url()), req.postData()))
                 return;
+            // A foreign frame's write is refused in every mode the route handler runs in.
+            if (this.mode !== "destructive" && this.foreignWriteOf(req))
+                return;
+            if (this.mode !== "destructive" &&
+                offAppPageWrite(this.baseUrl, this.page?.url(), req.url(), this.embedMoves.movedTo) &&
+                !isAuthExempt(this.mode, method, pathnameOf(req.url()), isDestructiveWire(pathnameOf(req.url()), req.postData())))
+                return;
             const pageUrl = this.page?.url();
             if (pageUrl && this.memory) {
                 try {
@@ -731,12 +777,111 @@ export class BrowserEngine {
             await this.context.route("**/*", async (route) => {
                 const req = route.request();
                 const method = req.method();
+                // A redirect is followed by the browser without asking, so its target
+                // would load unsandboxed: a frame's redirect is answered with a
+                // sandboxed page that navigates there itself, and the next hop comes
+                // back here. Built from scratch: a redirect's framing or script
+                // headers never applied to a redirect, and would block this page.
+                const standIn = async (location, setCookie) => {
+                    const headers = {
+                        "content-type": "text/html; charset=utf-8",
+                        "content-security-policy": withForeignFrameSandbox(undefined),
+                        "cache-control": "no-store",
+                    };
+                    if (setCookie)
+                        headers["set-cookie"] = setCookie;
+                    await route.fulfill({ status: 200, headers, body: sandboxedRedirectPage(new URL(location, req.url()).href) });
+                };
+                // WebKit drops the sandbox for a frame that loads a data: URL in its own
+                // place. A top-window navigation out of the app, with no Referer, while
+                // a frame that held another site sits on a non-web URL, is that frame's
+                // escape: refused, judged on the page as it is when the request arrives.
+                if (method === "GET" && req.resourceType() === "document" && this.embedEscapeNavigation(req)) {
+                    const why = ESCAPE_REFUSAL;
+                    // Reported like any refusal, so a click whose navigation this stopped does not read as a click that did nothing.
+                    if (this.blockedRequests.length < 20)
+                        this.blockedRequests.push({ at: Date.now(), sig: `navigation to ${req.url().slice(0, 140)}`, answered: false, why });
+                    this.logAction({ action: "write-policy:blocked", target: `navigation to ${req.url().slice(0, 140)} (${why})`, url: this.page?.url() ?? "" });
+                    this.refusedByPolicy.add(req);
+                    this.oracles.notePolicyBlock();
+                    await route.abort("blockedbyclient").catch(() => { });
+                    return;
+                }
+                const frameDoc = method === "GET" && req.resourceType() === "document" ? this.frameDocumentKind(req) : null;
+                // A document loading into a frame of another origin gets the sandbox
+                // that forbids popups and top-window navigation (policy.ts says why).
+                if (frameDoc === "foreign") {
+                    try {
+                        const res = await route.fetch({ maxRedirects: 0 });
+                        const headers = res.headers();
+                        const location = res.status() >= 300 && res.status() < 400 ? headers["location"] : undefined;
+                        if (location) {
+                            await standIn(location, headers["set-cookie"]);
+                            return;
+                        }
+                        headers["content-security-policy"] = withForeignFrameSandbox(headers["content-security-policy"]);
+                        await route.fulfill({ response: res, headers });
+                        return;
+                    }
+                    catch {
+                        // Fail closed: a frame that cannot be sandboxed is not loaded.
+                        await route.abort("blockedbyclient").catch(() => { });
+                        return;
+                    }
+                }
+                // The app's own frame document can redirect into another site, whose
+                // page would then load unsandboxed. Asked first, one hop at a time; a
+                // document that does not redirect loads as it would have, sent on
+                // rather than served from here — a served document counts as public in
+                // Chromium and could no longer reach an app on localhost. The price is
+                // a second GET of the app's frame documents that are not redirects.
+                if (frameDoc === "app") {
+                    try {
+                        const res = await route.fetch({ maxRedirects: 0 });
+                        const location = res.status() >= 300 && res.status() < 400 ? res.headers()["location"] : undefined;
+                        // Every hop, not only one out of the app: Playwright does not route the
+                        // later hops of a redirect, so a chain through the app and then out
+                        // would go unseen, and each hop is then fetched once, not twice.
+                        if (location) {
+                            await standIn(location, res.headers()["set-cookie"]);
+                            return;
+                        }
+                    }
+                    catch {
+                        /* could not ask: load it as it would have loaded */
+                    }
+                    await route.continue().catch(() => { });
+                    return;
+                }
                 if (method === "GET" || method === "HEAD" || method === "OPTIONS")
                     return route.continue();
                 const url = req.url();
                 const pathname = pathnameOf(url);
+                const refuse = (why) => {
+                    const answered = answersWithRefusal(req.resourceType());
+                    if (this.blockedRequests.length < 20)
+                        this.blockedRequests.push({ at: Date.now(), sig: `${method} ${url.slice(0, 140)}`, answered, why });
+                    this.logAction({ action: "write-policy:blocked", target: `${method} ${pathname}${why ? ` (${why})` : ""}`, url: this.page?.url() ?? "" });
+                    this.refusedByPolicy.add(req);
+                    this.oracles.notePolicyBlock();
+                    // A script's request is answered with a refusal, so the page's handling
+                    // of one actually runs; a navigation is dropped (policy.ts says why).
+                    // Caught: a request the page has already cancelled rejects these, and an unhandled rejection ends the process.
+                    if (answered)
+                        return route.fulfill(policyRefusal(this.mode, method, pathname, req.headers()["origin"], why)).catch(() => { });
+                    return route.abort("blockedbyclient").catch(() => { });
+                };
+                // An embedded widget from another site writes to that site, not to the
+                // app under test: refused before any other rule, login included.
+                const foreign = this.foreignWriteOf(req);
+                if (foreign)
+                    return refuse(`sent from a frame of ${foreign}`);
                 this.rememberAuthHeader(req.headers());
                 const destructiveWire = isDestructiveWire(pathname, req.postData());
+                // An embed moved the session's page off the app: its writes out are not the app's, a sign-in excepted.
+                const offApp = offAppPageWrite(this.baseUrl, this.page?.url(), url, this.embedMoves.movedTo);
+                if (offApp && !isAuthExempt(this.mode, method, pathname, destructiveWire))
+                    return refuse(`sent from a page of ${offApp}, outside the app`);
                 // Auth/session flows must work in every mode — but never a destructive
                 // one, and in observe only the requests a login itself needs.
                 if (isAuthExempt(this.mode, method, pathname, destructiveWire))
@@ -776,17 +921,7 @@ export class BrowserEngine {
                     }
                     return route.continue();
                 }
-                const answered = answersWithRefusal(req.resourceType());
-                if (this.blockedRequests.length < 20)
-                    this.blockedRequests.push({ at: Date.now(), sig: `${method} ${url.slice(0, 140)}`, answered });
-                this.logAction({ action: "write-policy:blocked", target: `${method} ${pathname}`, url: this.page?.url() ?? "" });
-                this.refusedByPolicy.add(req);
-                this.oracles.notePolicyBlock();
-                // A script's request is answered with a refusal, so the page's handling
-                // of one actually runs; a navigation is dropped (policy.ts says why).
-                if (answered)
-                    return route.fulfill(policyRefusal(this.mode, method, pathname, req.headers()["origin"]));
-                return route.abort("blockedbyclient");
+                return refuse();
             });
         }
         // Popups / target=_blank: adopt same-origin pages as the active page (with
@@ -807,6 +942,7 @@ export class BrowserEngine {
                 if (sameOrigin) {
                     this.oracles.attach(newPage);
                     this.wireDialogHandler(newPage);
+                    this.wireEmbedMoves(newPage);
                     this.page = newPage;
                     this.refs.clear();
                     this.snapshotUrl = "";
@@ -819,6 +955,7 @@ export class BrowserEngine {
                 .catch(() => { });
         });
         this.wireDialogHandler(this.page);
+        this.wireEmbedMoves(this.page);
         try {
             await this.page.goto(opts.url, { waitUntil: "domcontentloaded", timeout: 20000 });
         }
@@ -862,6 +999,48 @@ export class BrowserEngine {
             `${this.memory.gitIgnoreNote ? ` ${this.memory.gitIgnoreNote}` : ""} Call scout_snapshot to see the current state.` +
             authWarning);
     }
+    /** Whether the page was moved off the app by one of its embeds (policy.ts EmbedMoveTracker). */
+    embedMoves = new EmbedMoveTracker("");
+    /**
+     * Frames that have held a document of another origin, with the first such
+     * origin. A frame that has since moved itself to a data: URL is still that
+     * site's; it leaves the record when it leaves the page, as every frame of a
+     * replaced document does, so nothing has to be cleared at the right moment.
+     * Sticky on purpose: a frame that went back to the app (a silent-renew frame
+     * landing on the app's callback) keeps counting as an embed, which refuses
+     * more, never less.
+     */
+    foreignFrames = new WeakMap();
+    /** The other sites the driven page embeds right now, by the frames still attached to it. */
+    embeddedSites() {
+        const out = new Set();
+        const page = this.page;
+        if (!page)
+            return out;
+        const top = page.mainFrame();
+        for (const frame of page.frames()) {
+            if (frame === top)
+                continue;
+            const origin = this.foreignFrames.get(frame) ?? foreignFrameOrigin(this.baseUrl, [frame.url()]);
+            if (origin)
+                out.add(origin);
+        }
+        return out;
+    }
+    /** Feed the page's navigations to the embed-move tracker and the foreign-frame record. Wired on every page we drive, like the dialog handler. */
+    wireEmbedMoves(page) {
+        page.on("framenavigated", (frame) => {
+            if (page !== this.page)
+                return;
+            if (frame === page.mainFrame()) {
+                this.embedMoves.pageLoaded(frame.url());
+                return;
+            }
+            const origin = foreignFrameOrigin(this.baseUrl, [frame.url()]);
+            if (origin && !this.foreignFrames.has(frame))
+                this.foreignFrames.set(frame, origin);
+        });
+    }
     /** Dialogs (confirm/alert): dismiss in read-only mode, accept otherwise. Must be wired on every page we drive, including adopted popups. */
     wireDialogHandler(page) {
         page.on("dialog", (dialog) => {
@@ -1159,6 +1338,7 @@ export class BrowserEngine {
         geometry.push(...(await probeOverlays(page)));
         const hiddenFileInputs = await this.hiddenFileInputs(page);
         const brokenImages = brokenImageIssues((await page.evaluate(BROKEN_IMAGES_SCRIPT).catch(() => null)) ?? { images: [], total: 0 }, url);
+        const { frames, nested: nestedFrames } = await this.frameInventory(page);
         const cov = memory.coverage();
         const unvisited = this.unvisitedKnownRoutes();
         const title = await page.title();
@@ -1169,13 +1349,20 @@ export class BrowserEngine {
             body +
             (geometry.length > 0 ? `\nGEOMETRY issues:\n` + geometry.map((g) => `  ⚠ ${g}`).join("\n") : "") +
             (brokenImages.length > 0 ? `\nBROKEN IMAGES:\n` + brokenImages.map((b) => `  ⚠ ${b}`).join("\n") : "") +
+            (frames.length > 0 || nestedFrames > 0
+                ? `\n` + frameLines(this.baseUrl, frames, { nested: nestedFrames, writesRefused: this.mode !== "destructive" }).join("\n")
+                : "") +
             (hiddenFileInputs.length > 0
                 ? `\nFILE INPUTS not listed above (hidden behind a styled control — a user never sees the input itself): ${hiddenFileInputs.join("; ")}. ` +
                     `scout_upload {ref} on the control that opens one, or scout_upload {} when it is the page's only file input.`
                 : "") +
             this.socketNotice() +
             formatViolations(this.oracles.drain()) +
-            (elements.length === 0 ? "\n⚠ DEAD END: no interactable elements found on this page." : ""));
+            (elements.length === 0
+                ? hasVisibleFrame(frames)
+                    ? "\n⚠ No interactable elements in the page itself: what it shows is inside the frames listed above, which were not explored."
+                    : "\n⚠ DEAD END: no interactable elements found on this page."
+                : ""));
     }
     /**
      * Resolve a ref and re-verify the live element at action time. Refs are
@@ -1314,6 +1501,121 @@ export class BrowserEngine {
     lateMark(entry) {
         return entry.at < this.actionStartedAt ? `${entry.sig} (late — likely from a previous action)` : entry.sig;
     }
+    /**
+     * The frames directly under the page, read from their <iframe> elements in
+     * one pass each, all at once. Each read gets FRAME_READ_MS: a frame that
+     * cannot answer in time (a busy ad loop in its own process) is left out on
+     * its own rather than stalling the snapshot or dropping the others. Frames
+     * inside frames, and direct frames past the first 30, are only counted.
+     */
+    async frameInventory(page) {
+        const top = page.mainFrame();
+        const all = page.frames().filter((f) => f !== top);
+        const direct = all.filter((f) => f.parentFrame() === top);
+        const read = async (frame) => {
+            let timer;
+            const box = await Promise.race([
+                frame
+                    .frameElement()
+                    .then((el) => el.evaluate((node) => {
+                    const r = node.getBoundingClientRect();
+                    return {
+                        title: (node.getAttribute("title") || node.getAttribute("name") || "").trim(),
+                        width: Math.round(r.width),
+                        height: Math.round(r.height),
+                    };
+                }))
+                    .catch(() => null),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(null), FRAME_READ_MS);
+                }),
+            ]).finally(() => clearTimeout(timer));
+            return box ? { url: frame.url(), ...box, foreign: foreignFrameOrigin(this.baseUrl, [frame.url()]) !== null } : null;
+        };
+        const frames = (await Promise.all(direct.slice(0, 30).map(read))).filter((f) => f !== null);
+        return { frames, nested: all.length - Math.min(direct.length, 30) };
+    }
+    /**
+     * Whether a document request is the top window leaving the app, with no
+     * Referer, while a frame that held another site's document now sits on a
+     * data: or blob: URL — where WebKit no longer applies its sandbox.
+     */
+    embedEscapeNavigation(req) {
+        const page = this.page;
+        if (!page || !req.isNavigationRequest() || req.redirectedFrom())
+            return false;
+        try {
+            if (req.frame() !== page.mainFrame())
+                return false;
+        }
+        catch {
+            return false;
+        }
+        if (req.headers()["referer"])
+            return false;
+        if (foreignFrameOrigin(this.baseUrl, [req.url()]) === null)
+            return false;
+        const top = page.mainFrame();
+        // data: and blob: only: where WebKit drops the sandbox. A frame the app set back to about:blank is not an escape.
+        return page.frames().some((f) => f !== top && this.foreignFrames.has(f) && /^(data|blob):/i.test(f.url()));
+    }
+    /**
+     * What a document request loads into: a frame (not the top window) of
+     * another origin than the app's, a frame of the app's own origin, or
+     * neither (null). On the app's own sign-in pages frames are left alone: a
+     * "sign in with" button is a foreign frame that has to open its popup.
+     */
+    frameDocumentKind(req) {
+        let frame;
+        try {
+            frame = req.frame();
+        }
+        catch {
+            return null;
+        }
+        if (frame === frame.page().mainFrame())
+            return null;
+        if (allowsForeignWriteOnSignIn(this.mode, this.page?.url() ?? "", this.baseUrl))
+            return null;
+        let url;
+        try {
+            url = new URL(req.url());
+        }
+        catch {
+            return null;
+        }
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return null;
+        return foreignFrameOrigin(this.baseUrl, [req.url()]) ? "foreign" : "app";
+    }
+    /**
+     * The foreign origin behind a write headed outside the app (policy.ts
+     * foreignWrite), or null — also null on the app's own sign-in page, where a
+     * captcha frame's writes must go out for a login to work.
+     */
+    foreignWriteOf(req) {
+        let unadoptedPageUrl = null;
+        try {
+            const from = req.frame().page();
+            if (this.page && from !== this.page)
+                unadoptedPageUrl = from.url();
+        }
+        catch {
+            /* no frame: a new window's first request, or a service worker */
+        }
+        // Frames still attached that hold, or held, another site: one that moved itself to data: is no longer foreign by its URL.
+        const pageHasForeignFrame = this.embeddedSites().size > 0;
+        const foreign = foreignWrite(this.baseUrl, {
+            url: req.url(),
+            originHeader: req.headers()["origin"],
+            unadoptedPageUrl,
+            pageHasForeignFrame,
+            ...requestSource(req),
+        });
+        if (foreign && allowsForeignWriteOnSignIn(this.mode, this.page?.url() ?? "", this.baseUrl))
+            return null;
+        return foreign;
+    }
     /** Report (and clear) write-policy blocks since the last action. */
     drainBlocked() {
         this.lastActionBlocked = this.blockedRequests.length;
@@ -1325,9 +1627,18 @@ export class BrowserEngine {
             .join("; ");
         const extra = this.blockedRequests.length > 5 ? ` (+${this.blockedRequests.length - 5} more)` : "";
         const answered = this.blockedRequests.some((e) => e.answered);
+        const reasons = new Set(this.blockedRequests.map((e) => e.why).filter((w) => !!w));
+        const escaped = reasons.delete(ESCAPE_REFUSAL);
+        const foreign = [...reasons];
         this.blockedRequests = [];
         return (`\n🛡 WRITE-POLICY blocked (${this.mode}): ${list}${extra}. ` +
             `This is the tester's safety policy, NOT an app bug — do not file a finding for the resulting error UI. ` +
+            (foreign.length > 0
+                ? `Refused because it was ${foreign.join("; ")}: it would reach a site embedded in the page rather than the app, which no mode but destructive allows. `
+                : "") +
+            (escaped
+                ? `A move of the whole page off the app, with no Referer, was refused: a frame that held another site now sits on a data: or blob: URL, where WebKit drops the frame's sandbox, so the move may be that frame's. No mode but destructive allows it. `
+                : "") +
             (answered
                 ? `The page's own requests were answered with a 403 in the server's place, so the page's handling of a refusal is real: an error message is correct, and a success message is a false_success violation. `
                 : "") +

package/dist/engine/collector.js

@@ -402,6 +402,59 @@ export const BROKEN_IMAGES_SCRIPT = `(() => {
   }
   return { images, total };
 })()`;
+/** A frame smaller than this in both directions is plumbing (a tracking pixel, a messaging bridge), not something a user sees. */
+const VISIBLE_FRAME_PX = 2;
+/**
+ * The snapshot's account of the page's frames. Nothing inside a frame is
+ * collected or can be acted on yet, and a page that shows its form in an
+ * embed used to look like a page with no form at all: say what is there,
+ * where it comes from, and that it was not looked inside. `nested` counts
+ * frames that are not read: nested inside others, or past the first 30; `writesRefused` is false only in
+ * destructive mode, where a foreign frame's writes do go out.
+ */
+export function frameLines(appUrl, frames, opts = {}) {
+    const visible = frames.filter((f) => f.width >= VISIBLE_FRAME_PX && f.height >= VISIBLE_FRAME_PX);
+    const hidden = frames.length - visible.length;
+    const nested = opts.nested ?? 0;
+    if (frames.length === 0 && nested === 0)
+        return [];
+    let app = "";
+    try {
+        app = new URL(appUrl).origin;
+    }
+    catch {
+        /* no origin: paths are shown in full */
+    }
+    const lines = visible.slice(0, 10).map((f) => {
+        let where = f.url || "(no address)";
+        try {
+            const u = new URL(f.url);
+            if (u.origin === app)
+                where = u.pathname + u.search;
+        }
+        catch {
+            /* about:blank, srcdoc: shown as they are */
+        }
+        const label = f.title ? ` "${f.title.slice(0, 60)}"` : "";
+        const writes = f.foreign
+            ? opts.writesRefused === false
+                ? " — its writes go out (destructive mode)"
+                : " — writes it sends outside the app are refused"
+            : "";
+        return `  ${f.foreign ? "cross-origin" : "same-origin"} ${where.slice(0, 120)}${label} ${f.width}×${f.height}${writes}`;
+    });
+    if (visible.length > 10)
+        lines.push(`  … +${visible.length - 10} more`);
+    if (hidden > 0)
+        lines.push(`  (+${hidden} hidden frame${hidden === 1 ? "" : "s"})`);
+    if (nested > 0)
+        lines.push(`  (+${nested} more frame${nested === 1 ? "" : "s"}, nested inside those or past the first 30, not read)`);
+    return [`FRAMES not explored — their controls are not listed above and cannot be acted on:`, ...lines];
+}
+/** Whether any frame on the page is one a user can see. */
+export function hasVisibleFrame(frames) {
+    return frames.some((f) => f.width >= VISIBLE_FRAME_PX && f.height >= VISIBLE_FRAME_PX);
+}
 /** Snapshot lines for images that failed to load. The origin is dropped when it is the page's own, to keep the line short. */
 export function brokenImageIssues(scan, pageUrl) {
     let origin = "";

package/dist/engine/policy.js

@@ -174,6 +174,244 @@ export function isAuthExempt(mode, method, pathname, destructiveWire) {
     return (segments.slice(-2).some((seg) => OBSERVE_AUTH_SEGMENT_RE.test(seg)) &&
         !/^(users?|accounts?|members?|password|signup|sign-up|register|verify|invite|invitations?)$/i.test(last));
 }
+/**
+ * The origin of a request's frame when that frame belongs to another site than
+ * the app: an embedded widget, such as a form, chat or payment box served by a
+ * third party. A write from one reaches that third party, not the app under
+ * test, so no mode short of destructive lets it out.
+ *
+ * `frameChain` lists the URLs of the frame that issued the request and each of
+ * its parents, stopping before the top document. A frame with no address of
+ * its own (about:blank, srcdoc) belongs to whoever created it, so it is skipped
+ * and its parent decides. Any foreign frame in the chain makes the request
+ * foreign: an app page nested inside a widget is still being driven by it.
+ * Null for the top document, same-origin frames, and requests with no frame.
+ */
+export function foreignFrameOrigin(appUrl, frameChain) {
+    let app;
+    try {
+        app = new URL(appUrl).origin;
+    }
+    catch {
+        return null;
+    }
+    for (const url of frameChain) {
+        let frame;
+        try {
+            frame = new URL(url);
+        }
+        catch {
+            continue;
+        }
+        if (frame.protocol !== "http:" && frame.protocol !== "https:")
+            continue;
+        if (frame.origin !== app)
+            return frame.origin;
+    }
+    return null;
+}
+/**
+ * The origin to name when a write started by another site is headed outside
+ * the app, or null when the write is the app's own or lands in the app.
+ *
+ * The source is foreign when the frame that sent it (or a parent) is of
+ * another origin, or when the request's Origin header names another origin
+ * than both the app and the frame it is attributed to. The second catches a
+ * foreign frame's form aimed at `_top` or `_blank`, and a popup it opens: the
+ * browser reports those against the top page or no frame at all, but the
+ * Origin header still names the frame's site. A sign-in page loaded as the
+ * whole page is not caught by it, since there the header and the page agree.
+ *
+ * A foreign write whose destination is the app itself — a sign-in provider's
+ * frame posting its reply back to the app's callback — is the app's business
+ * and is left to the ordinary rules.
+ */
+export function foreignWrite(appUrl, req) {
+    let app;
+    try {
+        app = new URL(appUrl).origin;
+    }
+    catch {
+        return null;
+    }
+    const originOf = (url) => {
+        if (!url)
+            return null;
+        try {
+            const u = new URL(url);
+            return u.protocol === "http:" || u.protocol === "https:" ? u.origin : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    if (originOf(req.url) === app)
+        return null;
+    const fromFrame = foreignFrameOrigin(appUrl, req.frameChain);
+    if (fromFrame)
+        return fromFrame;
+    const header = originOf(req.originHeader);
+    if (header && header !== app && header !== originOf(req.frameUrl))
+        return header;
+    // A popup a foreign frame opened on its own site posts from its own script
+    // before it can be closed, and there the header and the page agree. The
+    // session never drives a page it did not adopt, so its writes out are not
+    // the app's.
+    if (req.unadoptedPageUrl !== undefined && req.unadoptedPageUrl !== null)
+        return originOf(req.unadoptedPageUrl) ?? "a page the session did not open";
+    // A frame with a no-referrer policy sends "Origin: null". Out of the app,
+    // on a page that embeds another site, that is taken to be the embed.
+    if (req.originHeader === "null" && req.pageHasForeignFrame)
+        return "an embedded frame (Origin: null)";
+    return null;
+}
+/**
+ * Whether the session's page was moved off the app by one of its embeds. The
+ * sandbox forbids a frame to move the page, but WebKit drops it for a frame
+ * that loads a `data:` URL in its own place, and a Chromium service worker can
+ * serve a frame's document unseen.
+ *
+ * Decided on the navigation's first request, given the other sites the page
+ * embeds at that moment (the engine asks the frames still attached, so a route
+ * change, a 204 or a download changes nothing). A move from a page with no
+ * embeds, or one carrying the app as its Referer — a click on the app's page —
+ * is the tester's: a hosted sign-in page, even one the app also embeds for
+ * silent sign-in, keeps the ordinary rules. With another site's Referer, it is
+ * an embed's. With no Referer at all (an app that sends none, or a frame that
+ * hides its origin) it is an embed's only when it goes to one of the embedded
+ * sites.
+ */
+export class EmbedMoveTracker {
+    appUrl;
+    pending = null;
+    /** The origin the page was moved to by an embed, while it stays there. */
+    movedTo = null;
+    constructor(appUrl) {
+        this.appUrl = appUrl;
+    }
+    /** The top window's navigation to `url` sent its first request, with this Referer, from a page embedding these other sites. */
+    navigationStarted(url, referer, embedded) {
+        const target = foreignFrameOrigin(this.appUrl, [url]);
+        if (!target || embedded.size === 0) {
+            this.pending = null;
+            return;
+        }
+        const refererIsHttp = !!referer && /^https?:/i.test(referer);
+        if (refererIsHttp && foreignFrameOrigin(this.appUrl, [referer]) === null)
+            this.pending = null;
+        else if (refererIsHttp)
+            this.pending = target;
+        else
+            this.pending = embedded.has(target) ? target : null;
+    }
+    /** The top window now shows `url`: a new document, or a same-document route change. */
+    pageLoaded(url) {
+        let origin;
+        try {
+            const u = new URL(url);
+            if (u.protocol !== "http:" && u.protocol !== "https:")
+                return;
+            origin = u.origin;
+        }
+        catch {
+            return;
+        }
+        if (foreignFrameOrigin(this.appUrl, [url]) === null) {
+            this.movedTo = null;
+            this.pending = null;
+            return;
+        }
+        if (this.pending === origin)
+            this.movedTo = origin;
+        else if (this.movedTo !== origin)
+            this.movedTo = null;
+        this.pending = null;
+    }
+}
+/**
+ * The origin to name when the session's page was moved off the app by one of
+ * its embeds (EmbedMoveTracker) and writes to another site from there, or
+ * null. Refused unless it is a sign-in request.
+ */
+export function offAppPageWrite(appUrl, pageUrl, destinationUrl, movedByEmbed) {
+    if (!movedByEmbed)
+        return null;
+    const originOf = (url) => {
+        if (!url)
+            return null;
+        try {
+            const u = new URL(url);
+            return u.protocol === "http:" || u.protocol === "https:" ? u.origin : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const app = originOf(appUrl);
+    const page = originOf(pageUrl);
+    if (!app || !page || page === app || page !== movedByEmbed)
+        return null;
+    if (originOf(destinationUrl) === app)
+        return null;
+    return page;
+}
+/**
+ * The page a sandboxed frame is given in place of a redirect: it navigates to
+ * the redirect's target itself, so the next hop is a navigation the policy
+ * routes and sandboxes again. A redirect answered as a redirect is followed by
+ * the browser without asking, and the page it lands on was not sandboxed.
+ */
+export function sandboxedRedirectPage(target) {
+    const json = JSON.stringify(target).replace(/</g, "\\u003c");
+    // No referrer: the next hop would otherwise name this stand-in page, where a real redirect names the app.
+    return `<!doctype html><meta charset="utf-8"><meta name="referrer" content="no-referrer"><script>location.replace(${json});</script>`;
+}
+/** The last path segment of a page that is a sign-in page, and nothing else: not a verification step, where a payment provider's frame sits. */
+const SIGN_IN_SEGMENT_RE = /^(login|log-in|signin|sign-in|signup|sign-up|sso|oauth)$/i;
+/**
+ * Whether a foreign frame's writes out may go on this page after all: a
+ * captcha on the app's own sign-in page is a cross-origin frame that posts to
+ * its own site, and refusing it would make every login fail. Only on the app's
+ * own origin, only when the page's last path segment is a sign-in word (a
+ * trailing file extension ignored, `_` read as `-`) — not "auth", which is
+ * also the last step of a card payment's verification — and not in observe, where only the login
+ * request itself goes out.
+ */
+export function allowsForeignWriteOnSignIn(mode, topPageUrl, appUrl) {
+    if (mode === "observe" || mode === "destructive")
+        return false;
+    let page;
+    try {
+        page = new URL(topPageUrl);
+        if (page.origin !== new URL(appUrl).origin)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const segments = page.pathname.split("/").filter(Boolean);
+    // "sign_in" is "sign-in": underscores are how some frameworks spell it.
+    const last = (segments[segments.length - 1] ?? "").replace(/\.[a-z0-9]+$/i, "").replace(/_/g, "-");
+    return SIGN_IN_SEGMENT_RE.test(last);
+}
+/**
+ * The sandbox given to every document a frame of another origin loads, outside
+ * destructive mode: scripts, forms and its own origin keep working, and no
+ * popups or top-window navigation are allowed. A browser applies it to every
+ * realm the document makes, nested frames and blank ones included, which a
+ * script patch cannot reach: in Firefox a detached link's click, a
+ * `<base target>` or a borrowed `window.open` each opened a popup whose first
+ * requests never reached the policy.
+ */
+export const FOREIGN_FRAME_SANDBOX = "sandbox allow-scripts allow-forms allow-same-origin";
+/**
+ * A response's Content-Security-Policy with the foreign-frame sandbox added. A
+ * second policy joined with a comma is enforced alongside the first, so the
+ * document's own policy still holds.
+ */
+export function withForeignFrameSandbox(existing) {
+    return existing && existing.trim() ? `${existing}, ${FOREIGN_FRAME_SANDBOX}` : FOREIGN_FRAME_SANDBOX;
+}
 export function allowsWrite(mode, method, destructiveWire, owned) {
     if (mode === "destructive")
         return true;
@@ -209,7 +447,7 @@ export const POLICY_REFUSAL_HEADER = "x-scenescout-policy";
  * drop it all over again. `origin` is the request's own Origin header, echoed
  * only when there is one.
  */
-export function policyRefusal(mode, method, pathname, origin) {
+export function policyRefusal(mode, method, pathname, origin, why) {
     const headers = { "content-type": "application/json", [POLICY_REFUSAL_HEADER]: `refused; mode=${mode}` };
     if (origin) {
         headers["access-control-allow-origin"] = origin;
@@ -221,7 +459,7 @@ export function policyRefusal(mode, method, pathname, origin) {
         headers,
         body: JSON.stringify({
             error: "Forbidden",
-            message: `${method} ${pathname} was refused by the tester's ${mode} write policy. The server never received it.`,
+            message: `${method} ${pathname} was refused by the tester's ${mode} write policy${why ? ` (${why})` : ""}. The server never received it.`,
         }),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "SceneScout — exploratory UI testing for AI coding agents. An MCP server that gives any agent (Claude Code, Cursor, VS Code Copilot, Codex, Gemini CLI and others) a structured view of a running web app, always-on oracles, a network-level write policy, memory across runs and a gap-checked report.",
   "license": "MIT",
   "author": "brunoboto96",

package/skills/scenescout/SKILL.md

@@ -34,7 +34,7 @@ You are the brain of an exploratory UI tester. The SceneScout MCP server gives y
 1. **`scout_crawl` first, always.** One call visits every known route (pass `paths` to sweep a specific subset instead), records coverage, and returns per-route health. This is the whole breadth pass — do not visit routes one-by-one with navigate+snapshot.
 2. **Investigate what the crawl flagged.** For each problem route (violations, dead-ends, auth-redirects): navigate there, `scout_snapshot`, reproduce, then `scout_finding`.
 3. **Run journeys with `scout_run_plan {steps}`.** Mechanical sequences (fill form → submit → check) go in ONE plan call — `steps` is an ordered list of `{action, target, value}` — with `testid=`/`text=`/`label=` targets — not one LLM turn per click. The plan aborts at the first violation and tells you where; that's your cue to investigate interactively.
-4. **Snapshot economics:** `scout_snapshot` after landing somewhere new; re-snapshots of the same route return *diffs* with stable refs — "No element changes" costs you almost nothing. `scout_screenshot` ONLY for suspected pixel-native issues (a canvas, a rendering glitch); geometry problems (overlap, off-screen, a covered control) are already in the snapshot as GEOMETRY issues, and images that failed to load are listed under BROKEN IMAGES — file those, quoting the line.
+4. **Snapshot economics:** `scout_snapshot` after landing somewhere new; re-snapshots of the same route return *diffs* with stable refs — "No element changes" costs you almost nothing. `scout_screenshot` ONLY for suspected pixel-native issues (a canvas, a rendering glitch); geometry problems (overlap, off-screen, a covered control) are already in the snapshot as GEOMETRY issues, and images that failed to load are listed under BROKEN IMAGES — file those, quoting the line. A FRAMES line means part of the page is an embed (`<iframe>`) whose controls are not listed and cannot be acted on yet: say in your summary that its contents were not explored, and never file its absence as a missing feature. Writes a cross-origin frame sends outside the app are refused in every mode but destructive, because they reach the third party serving it.
 5. **Native-user behaviours.** `scout_type {ref, textValue}` (or its alias `value`, matching `scout_select` and a plan step) APPENDS when a field already has content (menu clicks often insert @-mention chips or commands into composers — appending preserves them; the result reports what was already there); pass `replace=true` only to deliberately clear, and `pressEnter=true` to submit from the field the way a user would. Before concluding a badge, icon, or "N errors" indicator *does nothing*, `scout_hover` it — tooltips and hover cards are invisible to snapshots and clicks, and hover output includes what appeared. In HEADED mode (`scout_attach {headed:true}`, which the user asks for when they want to watch) the user's physical mouse competes with the synthetic pointer: if a hover reveals nothing and the finding matters, ask the user to move their mouse off the browser window and retry before filing. **Scroll long pages with `scout_scroll`** — the design audit and snapshot measure at the current scroll position, so judge deep sections by scrolling then re-auditing; it refuses to scroll where a real user couldn't and reports SCROLL LOCKED (the leaked modal scroll-lock that silently amputates everything below the fold — snapshots also flag it passively as an OVERLAY line), and scrolling triggers lazy-loaded content whose failures surface as fresh oracle violations. Elements fully clipped inside an overflow-hidden container are flagged UNREACHABLE in GEOMETRY issues — no amount of scrolling reveals them; that's a high-value layout bug, distinct from merely below-the-fold content. **A page can hold SEVERAL independent scroll regions** and plain `scout_scroll` moves the largest one, so a sidebar nav beside a taller main pane never budges: pass `scout_scroll {target:"testid=…"}` to scroll one region. Never report a nav item, tab or list row as missing/truncated until you have scrolled ITS container — content scrolled out of a secondary pane looks exactly like content that was cut off.
 6. **The rest of the input vocabulary.** `scout_select` sets a `<select>` option by value or visible label — use it rather than clicking a native dropdown open, which does not render as page DOM. `scout_press` sends a real key to the focused element (`Escape` to dismiss a modal, `Tab` to walk focus order, `Enter` to submit from a field); it is also how the keyboard-only pass at `extensive` is performed, and it vets the focused control first so a destructive action cannot be triggered blind in read-only mode. **`scout_upload {ref}` attaches a file the way a user does** — `ref` is a visible `<input type=file>` (snapshots list these with role `file`; `scout_type` on one redirects here) OR the button/label/dropzone that opens the file chooser (the chooser is intercepted and answered — that is how the hidden input behind a styled "Choose file" control is reached); omit `ref` when the page has exactly one file input, hidden or not (snapshots disclose hidden ones on a FILE INPUTS line). Nothing needs to exist on disk: a small VALID fixture is generated in memory, its kind inferred from the input's `accept` attribute or chosen with `fixture` (`pdf`, `png`, `txt`, `csv`, `json`); `filePath` uploads a real file but must live inside the attached project (fenced, like navigation is fenced to the origin); `name` overrides the filename. The result flags a file that violates `accept` (a mismatch the app then ACCEPTS is a validation finding), warns when the app cleared the input after selection, and says whether a state-changing request fired on selection — if none did, either click the form's submit or read the next snapshot for a client-side rejection. Plans take `{action:"upload", target, value:"pdf"}` steps (`target` required). When the input or its trigger was addressed by `ref`, the gap ledger counts an attached-but-unsent file as filled-never-submitted; the ref-less path has no listed element to mark.
 7. **Say what you are doing: `task` is required before a tool acts.** A session shows two lines to whoever is watching. Its **objective** is the whole remit you were given, set once at `scout_attach {objective}` ("Admin lane: §2 registers, §7 plan gating", "Approve and reject orders as a manager"). Its **task** is what you are doing *right now*, and every tool that changes the app or the page — `scout_navigate`, `scout_back`, `scout_click`, `scout_type`, `scout_select`, `scout_press`, `scout_upload`, `scout_run_plan` — takes it: a few words for the batch in front of you ("Filtering the documents register by status", "Filling the deviation form with invalid dates", "Signing in as QA_Team"). Say what you are DOING, not what you are checking — "§2.4 filtering narrows the set and is reflected in the URL" is the acceptance criteria, which is the result you will judge, not the batch you are running; naming the item is fine ("§2.4: filtering the documents register"). The task STAYS SET until you pass a different one, so a batch costs a few words, not one per call — pass a fresh one whenever you move on. Acting with none standing is refused: the person watching would otherwise see a session clicking through their app with nothing to say why. `scout_journey {action:"start", goal:…}` sets the task too while it runs — use a journey when you are MEASURING a whole user task, the parameter for everything else.