scenescout 3.7.0 → 3.9.0

package/dist/engine/collector.js

@@ -402,6 +402,152 @@ export const BROKEN_IMAGES_SCRIPT = `(() => {
   }
   return { images, total };
 })()`;
+/**
+ * An element's coverage key inside a frame: the frame's origin (another site)
+ * or path (the app's own) before the element's own key, so a "Submit" in an
+ * embed is not the page's "Submit". Elements of the page itself keep their key
+ * unchanged, so pages without frames keep the coverage they had.
+ */
+export function frameElementKey(baseKey, frame) {
+    if (!frame)
+        return baseKey;
+    let where = frame.origin || frame.url;
+    if (!frame.foreign) {
+        try {
+            const u = new URL(frame.url);
+            // A frame with no web address (srcdoc, about:blank) is told apart by its title.
+            where = u.protocol === "http:" || u.protocol === "https:" ? u.pathname : `${frame.url}#${frame.title}`;
+        }
+        catch {
+            where = `${frame.url}#${frame.title}`;
+        }
+    }
+    return `frame:${where}|${baseKey}`;
+}
+/** The longest name kept for a control in another site's frame: a chat that renders messages as buttons would otherwise print them whole. */
+export const MAX_FOREIGN_NAME = 40;
+/** A control's name from another site's frame, cut to MAX_FOREIGN_NAME. */
+export function capForeignName(name) {
+    return name.length > MAX_FOREIGN_NAME ? `${name.slice(0, MAX_FOREIGN_NAME)}…` : name;
+}
+/** A link's address from another site's frame without its query and fragment, where tokens and addresses travel. */
+export function stripForeignHref(href) {
+    try {
+        const u = new URL(href);
+        return u.origin + u.pathname;
+    }
+    catch {
+        return href.split(/[?#]/)[0];
+    }
+}
+/**
+ * A rect read inside a frame, in the page's document coordinates: the frame
+ * element's box on screen, less the frame's own scroll, plus the page's.
+ */
+export function frameToPageRect(rect, box, frameScroll, pageScroll) {
+    return { ...rect, x: rect.x + box.x + pageScroll.x - frameScroll.x, y: rect.y + box.y + pageScroll.y - frameScroll.y };
+}
+/** How a snapshot line names the frame an element is in. */
+export function frameLabel(frame) {
+    let where = frame.url;
+    if (!frame.foreign) {
+        try {
+            const u = new URL(frame.url);
+            where = u.pathname + u.search;
+        }
+        catch {
+            /* shown as it is */
+        }
+    }
+    else if (frame.origin)
+        where = frame.origin;
+    return `${frame.foreign ? "cross-origin" : "same-origin"} frame ${where.slice(0, 80)}${frame.title ? ` "${frame.title.slice(0, 40)}"` : ""}`;
+}
+/**
+ * Whether an element's name, read from another site's frame, is masked. A
+ * name taken from a container's text — a select's options, a textarea's
+ * contents, a tagged <div> — can carry other people's data (a support chat,
+ * a customer record) into the snapshot, the transcript and the report. The
+ * label of a link, a button or a field is the interface itself and is kept:
+ * the agent needs it to act.
+ */
+export function masksForeignName(tag, role) {
+    if (tag === "a" || tag === "button" || tag === "input")
+        return false;
+    return !/^(button|link|tab|menuitem|checkbox|switch|radio)$/.test(role);
+}
+/** The name shown for a masked element. */
+export const MASKED_NAME = "(content masked: another site's frame)";
+/** 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: what is embedded, where it
+ * comes from, and whether its controls were read (`read`, by frame URL) —
+ * a page that shows its form in an embed used to look like a page with no
+ * form at all. Without `read`, nothing was 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)}"` : "";
+        let frameOrigin = "";
+        try {
+            frameOrigin = new URL(f.url).origin;
+        }
+        catch {
+            /* no origin */
+        }
+        const writes = f.foreign
+            ? opts.writesRefused === false
+                ? " — its writes go out (destructive mode)"
+                : opts.trustedWrites?.has(frameOrigin)
+                    ? " — trusted embed: its writes go out (safe-write)"
+                    : " — writes it sends outside the app are refused"
+            : "";
+        const read = opts.read ? (opts.read.has(f.url) ? " — controls listed above" : " — not read") : "";
+        return `  ${f.foreign ? "cross-origin" : "same-origin"} ${where.slice(0, 120)}${label} ${f.width}×${f.height}${read}${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)`);
+    const header = opts.read && opts.read.size > 0
+        ? "FRAMES — the controls of each frame read are listed above, marked ⟨in … frame⟩, and can be acted on by ref" +
+            (visible.some((f) => f.foreign)
+                ? "; in another site's frame, content is masked and hostile input, repeated-click probes and uploads are refused"
+                : "") +
+            ":"
+        : "FRAMES not explored — their controls are not listed above and cannot be acted on:";
+    return [header, ...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/memory.js

@@ -282,6 +282,14 @@ function decisionKey(d) {
  * project would otherwise accumulate every decision ever made and re-serialise
  * them on each save, which is what made an old history slow to open.
  */
+/**
+ * Whether a coverage key belongs to a control inside another site's frame:
+ * those keys carry the frame's origin (collector.ts frameElementKey), where
+ * the app's own frames carry a path. Not the app's to cover.
+ */
+export function isEmbedKey(key) {
+    return /^frame:https?:\/\//.test(key);
+}
 export const MAX_LANE_DECISIONS = 1000;
 /**
  * Most options a dropdown may have and still be tracked for unchosen options.
@@ -1388,6 +1396,7 @@ export class MemoryStore {
         let elementsTotal = 0;
         let elementsExercised = 0;
         const unexercised = [];
+        const embeds = { total: 0, exercised: 0 };
         for (const [route, elements] of byRoute) {
             const own = [];
             // The route's OWN element count — deduped across states and with shared
@@ -1398,6 +1407,12 @@ export class MemoryStore {
             // untouched route silently drops out of the gap ledger.
             let ownTotal = 0;
             for (const [key, done] of elements) {
+                if (isEmbedKey(key)) {
+                    embeds.total += 1;
+                    if (done)
+                        embeds.exercised += 1;
+                    continue;
+                }
                 if (isChrome(key)) {
                     chrome.set(key, (chrome.get(key) ?? false) || done);
                     continue;
@@ -1424,7 +1439,7 @@ export class MemoryStore {
         if (chromeLeft.length > 0) {
             unexercised.push({ state: SHARED_CHROME_ROUTE, keys: chromeLeft, total: chrome.size });
         }
-        return { states: Object.keys(this.data.states).length, elementsTotal, elementsExercised, unexercised };
+        return { states: Object.keys(this.data.states).length, elementsTotal, elementsExercised, unexercised, embeds };
     }
     /**
      * Remember which styled-element signatures the design audit saw on a route.

package/dist/engine/oracles.js

@@ -84,6 +84,7 @@ export class OracleMonitor {
                 severity: "medium",
                 detail: `${req.method()} ${req.url().slice(0, 200)} → ${failure}`,
                 url: page.url(),
+                embed: this.embedOfRequest(req) ?? undefined,
             });
         });
         page.on("response", (res) => {
@@ -106,6 +107,7 @@ export class OracleMonitor {
                 severity: status >= 500 ? "high" : "medium",
                 detail: `${res.request().method()} ${res.url().slice(0, 200)} → HTTP ${status}`,
                 url: page.url(),
+                embed: this.embedOfRequest(res.request()) ?? undefined,
             });
         });
     }
@@ -128,6 +130,17 @@ export class OracleMonitor {
      * errors look the same.
      */
     policyAttributed = 0;
+    embedOfRequest = () => null;
+    /**
+     * The engine knows which frame a request came from; a failing request is
+     * attributed to an embed through this. Console and page errors are not
+     * attributed: a console message says where its script was served from, not
+     * which frame ran it, so an SDK the app's page loads from the embed's own
+     * site would be taken for the embed.
+     */
+    setEmbedAttribution(ofRequest) {
+        this.embedOfRequest = ofRequest;
+    }
     /** The engine knows exactly which requests its policy stopped; failed requests and stand-in refusals are matched against that, not against wording. */
     setPolicyRefusalCheck(check) {
         this.refusedByPolicy = check;
@@ -158,7 +171,11 @@ export class OracleMonitor {
             this.policyAttributed += 1;
             return;
         }
-        const violation = { ...redactViolation(v), at: new Date().toISOString() };
+        // Another site's frame: its behaviour, reported, but never as the app's high-severity defect.
+        const attributed = v.embed ? { ...v, severity: "medium" } : v;
+        if (!attributed.embed)
+            delete attributed.embed;
+        const violation = { ...redactViolation(attributed), at: new Date().toISOString() };
         this.buffer.push(violation);
         this.all.push(violation);
     }
@@ -179,7 +196,8 @@ export class OracleMonitor {
         for (const v of out) {
             // Same normalization as the report rollup, so "the same violation"
             // means the same thing in tool output and in the final report.
-            const sig = `${v.kind}: ${v.detail
+            // An embed's violation is not the app's: its signature says whose it is.
+            const sig = `${v.embed ? `[${v.embed}] ` : ""}${v.kind}: ${v.detail
                 .replace(/\b\d+\b/g, ":n")
                 .replace(/[0-9a-f]{8,}/gi, ":h")
                 .slice(0, 140)}`;
@@ -205,7 +223,9 @@ export function formatViolations(violations) {
     if (fresh.length === 0) {
         return `\nORACLE: ${repeats} repeat violation(s) of previously reported signatures — nothing new.`;
     }
-    const lines = fresh.slice(0, 10).map((v) => `  ⚠ [${v.severity}] ${v.kind}: ${v.detail}`);
+    const lines = fresh
+        .slice(0, 10)
+        .map((v) => `  ⚠ [${v.severity}] ${v.kind}${v.embed ? ` (in an embed of ${v.embed}: its behaviour, not the app's)` : ""}: ${v.detail}`);
     const more = fresh.length > 10 ? `\n  … and ${fresh.length - 10} more` : "";
     return `\nORACLE VIOLATIONS since last action (${fresh.length} new):\n${lines.join("\n")}${more}${repeatLine}`;
 }

package/dist/engine/policy.js

@@ -174,6 +174,362 @@ 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 embed a failing request is attributed to: the other site whose frame
+ * sent it (`frameSite`, judged on the frame chain), unless the request went to
+ * the app itself — a 500 from the app is the app's to answer, whoever called.
+ */
+export function embedOfRequest(appUrl, requestUrl, frameSite) {
+    if (!frameSite)
+        return null;
+    return foreignFrameOrigin(appUrl, [requestUrl]) === null ? null : frameSite;
+}
+/** The most origins a session may trust with its embeds' writes. */
+export const MAX_TRUSTED_EMBEDS = 10;
+/**
+ * The origins a session was told to trust, normalised, and what was given
+ * that is not one. An entry must be a plain http(s) origin — scheme, host and
+ * port, nothing after — so a path or a wildcard cannot widen it by accident.
+ */
+export function trustedEmbedOrigins(list) {
+    const origins = [];
+    const rejected = [];
+    const overflow = [];
+    for (const raw of list ?? []) {
+        let u;
+        try {
+            u = new URL(raw.trim());
+        }
+        catch {
+            rejected.push(raw);
+            continue;
+        }
+        const bare = u.pathname === "/" && !u.search && !u.hash && !u.username && !u.password;
+        if ((u.protocol !== "http:" && u.protocol !== "https:") || !bare || raw.includes("*")) {
+            rejected.push(raw);
+            continue;
+        }
+        // "pay.example.com." is "pay.example.com": one origin, one slot.
+        const origin = u.origin.replace(/\.(?=(:\d+)?$)/, "");
+        if (origins.includes(origin))
+            continue;
+        if (origins.length < MAX_TRUSTED_EMBEDS)
+            origins.push(origin);
+        else
+            overflow.push(raw);
+    }
+    return { origins, rejected, overflow };
+}
+/**
+ * Whether the writes a frame of `origin` sends outside the app may go out
+ * after all: only for an origin the user named as trusted (a provider in test
+ * mode, say), and only in safe-write — read-only and observe keep their
+ * promise, and destructive allows everything already.
+ */
+export function trustsEmbedWrite(mode, trusted, origin) {
+    return mode === "safe-write" && trusted.has(origin);
+}
+/**
+ * Whether a foreign write may go out because of trust: every other site
+ * involved — each http(s) frame from the sender up to the page, and the
+ * Origin header when it names one — must be trusted, so an untrusted embed
+ * cannot borrow a trusted one it wraps. A page the session never adopted (a
+ * popup) is not a frame, and trust does not reach it.
+ */
+export function trustsForeignWrite(mode, trusted, appUrl, req) {
+    if (mode !== "safe-write" || trusted.size === 0 || req.unadoptedPageUrl)
+        return false;
+    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 involved = new Set();
+    for (const url of req.frameChain) {
+        // A blank or srcdoc frame is its parent's, and the parent is judged next.
+        // Any other frame with no web address (blob:, data:) could be an untrusted
+        // site that moved itself there to wrap a trusted one: no trust through it.
+        if (/^about:(blank|srcdoc)/i.test(url))
+            continue;
+        const o = originOf(url);
+        if (!o)
+            return false;
+        if (o !== app)
+            involved.add(o);
+    }
+    const header = originOf(req.originHeader);
+    if (header && header !== app)
+        involved.add(header);
+    return involved.size > 0 && [...involved].every((o) => trustsEmbedWrite(mode, trusted, o));
+}
+/** The longest text typed into another site's frame; past it, a value is a fuzzing probe, not a user's input. */
+export const MAX_EMBED_TEXT = 200;
+/**
+ * Why a value must not be typed into another site's frame, or null when it
+ * may be. The tester is authorised to test the app, not the embeds of
+ * others: markup, fuzzing lengths and control characters typed there would
+ * be probing a third party's system without its leave.
+ */
+export function hostileForEmbed(text) {
+    if (/<\s*[a-z!/?]/i.test(text) || /javascript:/i.test(text))
+        return "it is markup";
+    if (text.length > MAX_EMBED_TEXT)
+        return `it is longer than ${MAX_EMBED_TEXT} characters`;
+    if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(text))
+        return "it holds control characters";
+    return null;
+}
+/** The refusal for a probe aimed at another site's frame. */
+export function embedProbeRefusal(what, origin) {
+    return (`REFUSED: ${what} inside a frame of ${origin}, another site embedded in the page. The tester is authorised to test the app, ` +
+        `not the embeds of others, so hostile input, repeated-click probes and file uploads are never sent into one, in any mode. ` +
+        `Ordinary clicks and typing there are allowed; the embed's writes out of the app are refused by the write policy.`);
+}
+/**
+ * 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 +565,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 +577,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.`,
         }),
     };
 }