@botiverse/porthole 0.1.4 → 0.1.6

package/dist/compile/policy.d.ts

@@ -1,5 +1,5 @@
 import { type CapabilityName, type Gate } from "../config/capabilities.ts";
-import type { EgressConfig, PortholeConfig } from "../config/schema.ts";
+import type { PortholeConfig } from "../config/schema.ts";
 /**
  * The frame's policies, derived from the config: its CSP (in the shell's `<meta>` for opaque
  * frames, in headers for served ones), its `sandbox` and `allow` attributes, and the `frame-src`
@@ -7,7 +7,9 @@ import type { EgressConfig, PortholeConfig } from "../config/schema.ts";
  */
 /** A CSP directive: its name, then its sources. */
 export type CspDirective = readonly [name: string, ...sources: string[]];
-export type EgressKind = keyof EgressConfig;
+export type EgressKind = "connect" | "script" | "style" | "img" | "font" | "media";
+/** Whether `kind` loads from any https site (`EgressConfig.anyHttps`, P059): passive kinds only. */
+export declare function anyHttps(config: PortholeConfig, kind: EgressKind): boolean;
 /** The capabilities a config declares, in vocabulary order. */
 export declare function declaredCapabilities(config: PortholeConfig): CapabilityName[];
 /** The gates a declared capability runs under: its own, else the vocabulary's defaults. */

package/dist/compile/policy.js

@@ -1,4 +1,8 @@
 import { CAPABILITIES } from "../config/capabilities.js";
+/** Whether `kind` loads from any https site (`EgressConfig.anyHttps`, P059): passive kinds only. */
+export function anyHttps(config, kind) {
+    return (config.egress.anyHttps ?? []).some((each) => each === kind);
+}
 /** The capabilities a config declares, in vocabulary order. */
 export function declaredCapabilities(config) {
     return Object.keys(CAPABILITIES).filter((name) => config.capabilities[name] !== undefined);
@@ -34,13 +38,15 @@ export function frameCspDirectives(config) {
         return [];
     }
     const origins = (kind) => egressOrigins(config, kind);
+    // Any https site, for passive kinds a host opened so (P059); never for what runs or talks.
+    const https = (kind) => (anyHttps(config, kind) ? ["https:"] : []);
     return [
         ["default-src", "'none'"],
         ["script-src", "'unsafe-inline'", "'unsafe-eval'", "blob:", ...origins("script")],
         ["style-src", "'unsafe-inline'", ...origins("style")],
-        ["font-src", "data:", ...origins("font")],
-        ["img-src", "data:", "blob:", ...origins("img")],
-        ["media-src", "data:", "blob:", ...origins("media")],
+        ["font-src", "data:", ...https("font"), ...origins("font")],
+        ["img-src", "data:", "blob:", ...https("img"), ...origins("img")],
+        ["media-src", "data:", "blob:", ...https("media"), ...origins("media")],
         ["connect-src", ...list(origins("connect"))],
         ["worker-src", "blob:"],
         ["child-src", "blob:"],

package/dist/config/schema.d.ts

@@ -58,7 +58,16 @@ export interface EgressConfig {
     readonly img?: readonly string[];
     readonly font?: readonly string[];
     readonly media?: readonly string[];
+    /**
+     * Passive content that may load from any https site (P059): images, audio and video, fonts, for
+     * pages that hotlink them. Never scripts, styles or data. It opens a channel out: a viewer's
+     * address and a visit signal reach any site, and data can leave in the URL.
+     */
+    readonly anyHttps?: readonly PassiveKind[];
 }
+/** What `EgressConfig.anyHttps` may open: content that runs nothing (P059). */
+export declare const PASSIVE_KINDS: readonly ["img", "media", "font"];
+export type PassiveKind = (typeof PASSIVE_KINDS)[number];
 export interface ThemeConfig {
     /**
      * Every CSS variable the content may read, with its default per scheme. The shell injects

package/dist/config/schema.js

@@ -1,3 +1,5 @@
+/** What `EgressConfig.anyHttps` may open: content that runs nothing (P059). */
+export const PASSIVE_KINDS = ["img", "media", "font"];
 /**
  * Sandbox tokens a url-mode frame may add to its baseline, by the host's choice (P037): a
  * person's own running app (a dev server's preview) may need popups (an OAuth flow), modals and

package/dist/config/validate.js

@@ -1,5 +1,5 @@
 import { CAPABILITY_NAMES, isCapabilityName } from "./capabilities.js";
-import { URL_PERMISSIONS, URL_SANDBOX_EXTRAS } from "./schema.js";
+import { PASSIVE_KINDS, URL_PERMISSIONS, URL_SANDBOX_EXTRAS, } from "./schema.js";
 /**
  * Checks a config before anything is derived from it. Every string that ends up in a CSP, an
  * attribute or the shell is checked here, so a malformed origin can't inject a directive
@@ -17,6 +17,147 @@ export class ConfigError extends Error {
 /** The built-in manual topics; a host's own topics may not reuse these names. */
 export const BUILT_IN_TOPICS = ["widget", "chart", "interactive"];
 const LOOPBACK = /^(localhost|127\.0\.0\.1|\[::1\])$|\.localhost$/u;
+/**
+ * Suffixes under which anyone can register or publish a name (a public suffix): a wildcard over
+ * one (`https://*.co.uk`, `https://*.github.io`) opens every stranger's site. Single labels (`com`,
+ * `dev`) are refused by rule; these are the common multi-label ones, registries' and hosting
+ * platforms'. Not the whole Public Suffix List: a wildcard should name the host's own domain.
+ */
+const PUBLIC_SUFFIXES = new Set([
+    // Registries' second levels.
+    ...["co", "org", "ac", "gov", "me", "net", "ltd", "plc", "sch", "nhs", "police"].map((each) => `${each}.uk`),
+    ...["com", "net", "org", "edu", "gov", "asn", "id"].map((each) => `${each}.au`),
+    ...["co", "org", "net", "ac", "govt", "geek", "school"].map((each) => `${each}.nz`),
+    ...["co", "ne", "or", "ac", "go", "ad", "ed", "gr", "lg"].map((each) => `${each}.jp`),
+    ...["co", "or", "ne", "ac", "go", "re"].map((each) => `${each}.kr`),
+    ...["com", "net", "org", "gov", "edu"].flatMap((each) => [
+        "br",
+        "cn",
+        "hk",
+        "tw",
+        "sg",
+        "my",
+        "mx",
+        "ar",
+        "tr",
+        "ua",
+        "pl",
+        "ph",
+        "pk",
+        "ng",
+        "eg",
+        "sa",
+        "vn",
+        "co",
+    ].map((country) => `${each}.${country}`)),
+    ...["co", "net", "org", "gen", "firm", "ind", "ac", "edu", "gov", "res"].map((each) => `${each}.in`),
+    ...["co", "org", "ac", "gov", "net", "web"].map((each) => `${each}.za`),
+    ...["co", "org", "ac", "gov", "net", "muni"].map((each) => `${each}.il`),
+    "co.id",
+    "or.id",
+    "ac.id",
+    "co.th",
+    "or.th",
+    "ac.th",
+    "co.ke",
+    "co.tz",
+    "co.ug",
+    "com.de",
+    "co.at",
+    "or.at",
+    "ac.at",
+    "co.it",
+    "com.es",
+    "nom.es",
+    "com.fr",
+    "asso.fr",
+    "eu.org",
+    "us.com",
+    "uk.com",
+    "eu.com",
+    "uk.net",
+    "gb.net",
+    "jpn.com",
+    "kr.com",
+    // Hosting platforms: anyone gets a name under these.
+    "github.io",
+    "githubusercontent.com",
+    "gitlab.io",
+    "bitbucket.io",
+    "pages.dev",
+    "workers.dev",
+    "r2.dev",
+    "vercel.app",
+    "now.sh",
+    "netlify.app",
+    "netlify.com",
+    "herokuapp.com",
+    "herokussl.com",
+    "appspot.com",
+    "web.app",
+    "firebaseapp.com",
+    "cloudfunctions.net",
+    "run.app",
+    "googleusercontent.com",
+    "blogspot.com",
+    "azurewebsites.net",
+    "azurestaticapps.net",
+    "azureedge.net",
+    "blob.core.windows.net",
+    "cloudapp.net",
+    "trafficmanager.net",
+    "cloudfront.net",
+    "amazonaws.com",
+    "s3.amazonaws.com",
+    "elasticbeanstalk.com",
+    "awsapprunner.com",
+    "amplifyapp.com",
+    "fly.dev",
+    "onrender.com",
+    "railway.app",
+    "up.railway.app",
+    "glitch.me",
+    "repl.co",
+    "replit.app",
+    "replit.dev",
+    "surge.sh",
+    "deno.dev",
+    "ngrok.io",
+    "ngrok-free.app",
+    "ngrok.app",
+    "loca.lt",
+    "trycloudflare.com",
+    "codesandbox.io",
+    "csb.app",
+    "stackblitz.io",
+    "webcontainer.io",
+    "neocities.org",
+    "wordpress.com",
+    "tumblr.com",
+    "wixsite.com",
+    "squarespace.com",
+    "myshopify.com",
+    "carrd.co",
+    "notion.site",
+    "framer.app",
+    "webflow.io",
+    "readthedocs.io",
+    "gitbook.io",
+    "sourceforge.net",
+    "digitaloceanspaces.com",
+    "ondigitalocean.app",
+    "b-cdn.net",
+    "jsdelivr.net",
+]);
+/** Why a wildcard's base can't be wildcarded, or null: a public suffix, or a single label. */
+function wildcardProblem(base) {
+    if (base === "localhost") {
+        return null;
+    }
+    return !base.includes(".") || PUBLIC_SUFFIXES.has(base)
+        ? `is a wildcard over a public suffix (*.${base}): anyone can serve a site under it; name a domain of your own (https://*.cdn.example.com)`
+        : null;
+}
 const HOST = /^(\*\.)?([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/u;
 /**
  * Whether `value` is a CSP host source Porthole accepts: a scheme, a host (optionally `*.` for
@@ -42,6 +183,12 @@ export function originSourceProblem(value) {
     if (host !== "[::1]" && !HOST.test(host)) {
         return `${JSON.stringify(value)} ${shape}`;
     }
+    if (host.startsWith("*.")) {
+        const problem = wildcardProblem(host.slice(2));
+        if (problem !== null) {
+            return `${JSON.stringify(value)} ${problem}`;
+        }
+    }
     if ((scheme === "http" || scheme === "ws") && !LOOPBACK.test(host.replace(/^\*\./u, "x."))) {
         return `${JSON.stringify(value)} uses ${scheme} off loopback: ${scheme} is allowed only for localhost, *.localhost, 127.0.0.1 and [::1] (loopback development); use ${scheme === "http" ? "https" : "wss"}`;
     }
@@ -147,10 +294,23 @@ export function validateConfig(input) {
     }
     const egress = object(config.egress, "config.egress");
     const kinds = ["connect", "script", "style", "img", "font", "media"];
-    only(egress, kinds, "config.egress");
+    only(egress, [...kinds, "anyHttps"], "config.egress");
     for (const kind of kinds) {
         sources(egress[kind], `config.egress.${kind}`);
     }
+    if (egress.anyHttps !== undefined) {
+        if (!Array.isArray(egress.anyHttps)) {
+            fail("config.egress.anyHttps", `must be a list of ${PASSIVE_KINDS.join(", ")}`);
+        }
+        egress.anyHttps.forEach((kind, index) => {
+            if (!PASSIVE_KINDS.includes(kind)) {
+                fail(`config.egress.anyHttps[${index}]`, `${JSON.stringify(kind)}: only images, media and fonts may load from any https site (P059), never scripts, styles or data`);
+            }
+        });
+        if (config.mode === "url") {
+            fail("config.egress.anyHttps", "url mode has no egress control");
+        }
+    }
     const theme = object(config.theme, "config.theme");
     only(theme, ["variables", "event", "documents"], "config.theme");
     if (theme.documents !== undefined &&

package/dist/conformance/behavior.js

@@ -156,7 +156,7 @@ export const BEHAVIOR_PROBES = [
     {
         id: "11.theme-flip",
         item: 11,
-        title: "a theme flip re-themes the running content in place, and tells it once",
+        title: "a theme flip re-themes the running content in place, and tells it once; no event without one",
         async run(context) {
             const config = inline({ theme: { event: "app:theme" } });
             const light = resolveTheme(config.theme, "light");
@@ -169,6 +169,13 @@ export const BEHAVIOR_PROBES = [
             const frame = await display.frame();
             await expect(frame.locator("p")).toHaveText("themed");
             expect(await variable(frame, "--color-text-primary")).toBe(light["--color-text-primary"]);
+            const flips = () => read(frame, () => window.flips);
+            // Mounting, and a host telling it the scheme it already has, are no flip: no event (#3).
+            await settle(400);
+            expect(await flips(), "no theme event at mount").toEqual([]);
+            await display.setTheme("light");
+            await settle(400);
+            expect(await flips(), "no theme event for the scheme it has").toEqual([]);
             await display.setTheme("dark");
             await expect
                 .poll(() => variable(frame, "--color-text-primary"))
@@ -418,6 +425,12 @@ export const BEHAVIOR_PROBES = [
                 content: PROMPT_CONTENT,
             });
             await click(display, "#ask");
+            // A host that always has a confirm function (a default dialog) asks anyway: what this case
+            // proves can't happen there (P058). Its answer is no, so nothing is sent either way.
+            const asked = await display.answerNextConfirmation(false, { timeoutMs: 1_500 }).then(() => true, () => false);
+            if (asked) {
+                context.inapplicable("this host always has a confirm function (a default dialog), so a display without one can't be shown; it asked the person instead");
+            }
             expect(await bodyData(display, "result")).toBe("false");
             expect(await refusals(display)).toContain("sendPrompt:no-confirm");
             expect(await display.calls()).toEqual([]);

package/dist/conformance/kit.d.ts

@@ -20,6 +20,11 @@ export interface ProbeContext {
     requestsTo(origin: string): string[];
     /** Records a measured engine fact in the report. */
     measured(text: string): void;
+    /**
+     * Ends the probe as inapplicable on this host (reported as skipped, with the reason): what it
+     * proves can't be observed here, through no fault of the host's isolation (P058).
+     */
+    inapplicable(reason: string): never;
 }
 export interface Probe {
     /** Stable id, `<item>.<channel>`: what `LeakSuiteOptions.skip` names. */

package/dist/conformance/kit.js

@@ -11,6 +11,17 @@ export function attack(code, markup = "") {
 (async () => {
   const r = {};
   const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  // Whether a policy blocks \`origin\` though the frame's own allows it: then it is the page's,
+  // which an opaque frame inherits (P058). \`attempt\` loads something from it once more.
+  const inheritedBlocks = async (origin, attempt) => {
+    let blocked = false;
+    const seen = (event) => { if (String(event.blockedURI).indexOf(origin) === 0) blocked = true; };
+    document.addEventListener("securitypolicyviolation", seen);
+    try { await attempt(); } catch (e) {}
+    await wait(300);
+    document.removeEventListener("securitypolicyviolation", seen);
+    return blocked;
+  };
   try {
 ${code}
   } catch (error) {

package/dist/conformance/probes.js

@@ -255,6 +255,11 @@ const sdkProbe = (preset) => ({
     },
 });
 export { attack } from "./kit.js";
+/**
+ * Why a positive control can't pass on this host: an opaque (`srcdoc`) frame inherits the
+ * embedding page's whole policy, and the page's own closes what the config opens (P058).
+ */
+const INHERITED = (directive, origin) => `the page's own CSP, which an opaque frame inherits, blocks ${origin} (${directive}): content in opaque frames here is as closed as the page, whatever its config opens. Domain mode's frames don't inherit it.`;
 export const PROBES = [
     // ── 0: the shell's own wiring, in a real frame ─────────────────────────────────────────────
     {
@@ -358,10 +363,14 @@ export const PROBES = [
       worker.onmessage = (event) => (event.data === "sent" ? resolve() : reject());
       worker.onerror = reject;
     }));
-    r.allowed = await fetch(${js(allowed.origin)} + "/allowed").then((response) => response.text(), () => "blocked");`),
+    r.allowed = await fetch(${js(allowed.origin)} + "/allowed").then((response) => response.text(), () => "blocked");
+    r.inherited = await inheritedBlocks(${js(allowed.origin)}, () => fetch(${js(allowed.origin)} + "/policy").catch(() => {}));`),
             });
             const verdict = await context.result(display, 20_000);
             await settle();
+            if (verdict.allowed !== "oracle" && verdict.inherited === true) {
+                context.inapplicable(INHERITED("connect-src", allowed.origin));
+            }
             expect(verdict.allowed, "the allowed origin (the positive control)").toBe("oracle");
             expect(allowed.requests().map((request) => request.path)).toContain("/allowed");
             expect(canary.requests(), "requests reached the canary").toEqual([]);
@@ -405,10 +414,14 @@ export const PROBES = [
     try { new Worker(${js(`${c}/worker.js`)}); } catch (e) {}
     const ok = document.getElementById("ok");
     r.allowed = await new Promise((resolve) => { if (ok.complete && ok.naturalWidth > 0) resolve("loaded"); ok.onload = () => resolve("loaded"); ok.onerror = () => resolve("blocked"); setTimeout(() => resolve("timeout"), 3000); });
-    r.script = typeof globalThis.__portholeOracleScript;`, markup),
+    r.script = typeof globalThis.__portholeOracleScript;
+    r.inherited = await inheritedBlocks(${js(allowed.origin)}, () => { new Image().src = ${js(`${allowed.origin}/policy.png`)}; });`, markup),
             });
             const verdict = await context.result(display, 20_000);
             await settle();
+            if (verdict.allowed !== "loaded" && verdict.inherited === true) {
+                context.inapplicable(INHERITED("img-src", allowed.origin));
+            }
             expect(verdict.allowed, "the allowed image (the positive control)").toBe("loaded");
             expect(canary.requests(), "resources loaded from the canary").toEqual([]);
             expect(context.requestsTo(canary.origin)).toEqual([]);
@@ -857,6 +870,10 @@ export function leakTests(host, options = {}) {
                     },
                     requestsTo: (origin) => requests.filter((url) => url.startsWith(`${origin}/`) || url === origin),
                     measured: (text) => info.annotations.push({ type: "measured", description: text }),
+                    inapplicable: (why) => {
+                        info.skip(true, `inapplicable on this host: ${why}`);
+                        throw new Error(`inapplicable on this host: ${why}`);
+                    },
                 });
             }
             finally {

package/dist/conformance/served.js

@@ -250,27 +250,76 @@ export function servedTests(host, options = {}) {
                 expect(shown.origin).not.toBe(location.origin);
             }
         });
-        define("served.domain.egress", "the CSP in the document's headers closes egress", async ({ page }) => {
+        define("served.domain.egress", "the CSP in the document's headers closes egress; only what the config opens to any https site (images, media) reaches it", async ({ page }) => {
             const display = await host.show(page, host.shell("egress"), { content: SHELL_CONTENT });
             const frame = await display.frame();
-            const fetched = await frame.evaluate(async (url) => {
+            const kinds = ["fetch", "img", "media", "script", "style", "frame"];
+            const urls = Object.fromEntries(await Promise.all(kinds.map(async (kind) => [kind, await host.canary(`egress-${kind}`)])));
+            // Each kind tried once; the policy that applied is read from the violations it raises.
+            const seen = await frame.evaluate(async (each) => {
+                const policies = [];
+                document.addEventListener("securitypolicyviolation", (event) => policies.push(event.originalPolicy));
+                let fetched = "sent";
                 try {
-                    await fetch(url, { mode: "no-cors" });
-                    return "sent";
+                    await fetch(each.fetch, { mode: "no-cors" });
                 }
                 catch {
-                    return "blocked";
+                    fetched = "blocked";
                 }
-            }, await host.canary("egress-fetch"));
-            await frame.evaluate((url) => {
                 const image = new Image();
-                image.src = url;
+                image.src = each.img;
                 document.body.append(image);
-            }, await host.canary("egress-img"));
+                const audio = document.createElement("audio");
+                audio.preload = "auto";
+                audio.src = each.media;
+                document.body.append(audio);
+                const script = document.createElement("script");
+                script.src = each.script;
+                document.body.append(script);
+                const link = document.createElement("link");
+                link.rel = "stylesheet";
+                link.href = each.style;
+                document.head.append(link);
+                const nested = document.createElement("iframe");
+                nested.src = each.frame;
+                document.body.append(nested);
+                await new Promise((resolve) => setTimeout(resolve, 800));
+                return { fetched, policy: policies.find((policy) => /connect-src/u.test(policy)) ?? "" };
+            }, urls);
             await page.waitForTimeout(SETTLE_MS);
-            expect(fetched).toBe("blocked");
-            expect(await host.canaryHits("egress-fetch")).toBe(0);
-            expect(await host.canaryHits("egress-img")).toBe(0);
+            expect(seen.fetched).toBe("blocked");
+            expect(seen.policy, "a CSP applied to the document").not.toBe("");
+            const sources = new Map(seen.policy
+                .split(";")
+                .map((directive) => directive.trim().split(/\s+/u))
+                .map(([name = "", ...rest]) => [name, rest]));
+            // What runs or talks never opens to any site (P059), whatever the config.
+            for (const name of ["script-src", "style-src", "connect-src", "frame-src", "default-src"]) {
+                expect(sources.get(name) ?? [], `${name} opens no scheme`).not.toContain("https:");
+            }
+            for (const kind of ["fetch", "script", "style", "frame"]) {
+                expect(await host.canaryHits(`egress-${kind}`), kind).toBe(0);
+            }
+            // Images and media: closed, unless the config opened them to any https site (P059);
+            // then, the canary being an https site, an image reaches it, as the config means.
+            const https = (kind) => (sources.get(`${kind}-src`) ?? []).includes("https:") &&
+                new URL(urls[kind]).protocol === "https:";
+            const opened = ["img", "media"].filter(https);
+            if (opened.length > 0) {
+                info?.annotations.push({
+                    type: "expected",
+                    description: `${opened.join(" and ")} load from any https site under this config (anyHttps, P059): ${opened.includes("img") ? "the image is asserted to reach the outside site" : "measured, not asserted"}; script, style, connect and frames still can't`,
+                });
+            }
+            if (https("img")) {
+                expect(await host.canaryHits("egress-img"), "the image, as the config opens it").toBeGreaterThan(0);
+            }
+            else {
+                expect(await host.canaryHits("egress-img"), "img").toBe(0);
+            }
+            if (!https("media")) {
+                expect(await host.canaryHits("egress-media"), "media").toBe(0);
+            }
         });
         const resourceReady = (html) => ({
             jsonrpc: "2.0",

package/dist/guide/guide.d.ts

@@ -10,6 +10,8 @@ import { BUILT_IN_TOPICS } from "../config/validate.ts";
 export type BuiltInTopic = (typeof BUILT_IN_TOPICS)[number];
 /** A topic name: a built-in one, or one of the config's own (`guide.topics`). */
 export type GuideTopic = BuiltInTopic | (string & {});
+/** What the manual calls `https:` (any https site), where a config opens passive kinds to it. */
+export declare const ANY_HTTPS_SITE = "any https site";
 /** The manual for `topics`, in the order asked (all built-in topics by default). */
 export declare function generateGuide(config: PortholeConfig, topics?: readonly GuideTopic[]): string;
 /** The description of the host's show tool, for the agent's tool list. */

package/dist/guide/guide.js

@@ -1,6 +1,6 @@
 import { MAX_COPY_CHARS, capabilitySpec, } from "../config/capabilities.js";
 import { BUILT_IN_TOPICS } from "../config/validate.js";
-import { declaredCapabilities, effectiveGates, egressOrigins, sandboxTokens, } from "../compile/policy.js";
+import { anyHttps, declaredCapabilities, effectiveGates, egressOrigins, sandboxTokens, } from "../compile/policy.js";
 import { shellPlan } from "../shell/plan.js";
 import { themeDefault } from "../theme/variables.js";
 import { GUIDE_EXAMPLES } from "./examples.js";
@@ -36,11 +36,18 @@ const KIND_WORDS = {
     media: "audio and video",
     connect: "data (fetch, WebSocket)",
 };
+/** What the manual calls `https:` (any https site), where a config opens passive kinds to it. */
+export const ANY_HTTPS_SITE = "any https site";
+/** The sources content may load `kind` from, as the manual names them: origins, any https site. */
+const sourcesFor = (config, kind) => [
+    ...(anyHttps(config, kind) ? [ANY_HTTPS_SITE] : []),
+    ...egressOrigins(config, kind),
+];
 /** What content may load, in prose, from the same origins the CSP lists. */
 function network(config) {
     const kinds = ["script", "style", "font", "img", "media", "connect"];
     const open = kinds
-        .map((kind) => [kind, egressOrigins(config, kind)])
+        .map((kind) => [kind, sourcesFor(config, kind)])
         .filter(([, origins]) => origins.length > 0);
     if (open.length === 0) {
         return "Network: none. Nothing loads from outside (no scripts, styles, fonts, images or data from any server) and any fetch fails, so write everything inline: SVG and CSS draw charts well.";
@@ -248,9 +255,17 @@ export function generateToolDescription(config) {
     const origins = [
         ...new Set(["script", "style", "font", "img", "media", "connect"].flatMap((kind) => egressOrigins(config, kind))),
     ];
-    const net = origins.length === 0
+    const passive = ["img", "media", "font"]
+        .filter((kind) => anyHttps(config, kind))
+        .map((kind) => KIND_WORDS[kind]);
+    const fromAnywhere = passive.length === 0
+        ? ""
+        : `${passive.length === 1 ? passive[0] : `${passive.slice(0, -1).join(", ")} and ${passive.at(-1)}`} from ${ANY_HTTPS_SITE}`;
+    const net = origins.length === 0 && fromAnywhere === ""
         ? "with no network (nothing loads from outside)"
-        : `loading only from ${origins.join(", ")}`;
+        : origins.length === 0
+            ? `loading only ${fromAnywhere}`
+            : `loading only from ${origins.join(", ")}${fromAnywhere === "" ? "" : `, and ${fromAnywhere}`}`;
     const globals = declaredCapabilities(config).flatMap((name) => {
         const spec = capabilitySpec(name);
         if (spec.global === undefined || !c.global(spec.global)) {

package/dist/index.d.ts

@@ -4,13 +4,14 @@
  */
 export { CAPABILITIES, CAPABILITY_NAMES, MAX_COPY_CHARS, capabilitySpec, isCapabilityName, type CapabilityArgs, type CapabilityName, type CapabilityResults, type CapabilitySpec, type Gate, type HandledCapability, } from "./config/capabilities.ts";
 export type { CapabilityConfig, CapabilityMap, ColorScheme, DisplayMode, EgressConfig, EmbedderConfig, GuideConfig, IsolationKind, LayoutConfig, Limits, PortholeConfig, StorageConfig, ThemeConfig, ThemeValue, } from "./config/schema.ts";
+export { PASSIVE_KINDS, type PassiveKind } from "./config/schema.ts";
 export { BUILT_IN_TOPICS, ConfigError, isOriginSource, originSourceProblem, validateConfig, } from "./config/validate.ts";
 export { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, type UrlPermission, type UrlSandboxExtra, } from "./config/schema.ts";
 export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
 export { FRAME_STATUS_METHOD } from "./isolation/types.ts";
 export { LIBRARY_CDNS, presets, type PresetName, type PresetOptions, type UrlPresetOptions, } from "./presets/presets.ts";
 export { compile, type CompiledConfig } from "./compile/compile.ts";
-export { allEgressOrigins, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, type CspDirective, type EgressKind, } from "./compile/policy.ts";
+export { allEgressOrigins, anyHttps, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, type CspDirective, type EgressKind, } from "./compile/policy.ts";
 export { shellPlan, type ShellPlan } from "./shell/plan.ts";
 export type { ShellDocumentOptions } from "./shell/document.ts";
 export { generateGuide, generateToolDescription, type BuiltInTopic, type GuideTopic, } from "./guide/guide.ts";

package/dist/index.js

@@ -4,6 +4,7 @@
  */
 // The config and its vocabulary.
 export { CAPABILITIES, CAPABILITY_NAMES, MAX_COPY_CHARS, capabilitySpec, isCapabilityName, } from "./config/capabilities.js";
+export { PASSIVE_KINDS } from "./config/schema.js";
 export { BUILT_IN_TOPICS, ConfigError, isOriginSource, originSourceProblem, validateConfig, } from "./config/validate.js";
 export { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, } from "./config/schema.js";
 export { hostOriginProblem, isHostOrigin } from "./isolation/served.js";
@@ -12,7 +13,7 @@ export { FRAME_STATUS_METHOD } from "./isolation/types.js";
 export { LIBRARY_CDNS, presets, } from "./presets/presets.js";
 // The compiler.
 export { compile } from "./compile/compile.js";
-export { allEgressOrigins, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, } from "./compile/policy.js";
+export { allEgressOrigins, anyHttps, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, } from "./compile/policy.js";
 export { shellPlan } from "./shell/plan.js";
 export { generateGuide, generateToolDescription, } from "./guide/guide.js";
 export { GUIDE_EXAMPLES } from "./guide/examples.js";

package/dist/presets/presets.js

@@ -60,6 +60,10 @@ const mergeEgress = (base, extra) => {
             merged[kind] = origins;
         }
     }
+    const passive = [...new Set([...(base.anyHttps ?? []), ...(extra?.anyHttps ?? [])])];
+    if (passive.length > 0) {
+        merged.anyHttps = passive;
+    }
     return merged;
 };
 /** The default variables, with the host's changes and additions, less those it dropped (null). */

package/dist/react/frame.js

@@ -332,15 +332,22 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             attempt(() => display.annotations.focus(id), latest());
         }
     }, [annotates, focusToken]);
+    // A flip or a restyle after the display was made: its first scheme and values went with it.
+    const [mountScheme] = useState(scheme);
+    const flipped = useRef(false);
     useEffect(() => {
-        handle.current?.setTheme(scheme);
-    }, [scheme]);
+        if (flipped.current || scheme !== mountScheme) {
+            flipped.current = true;
+            handle.current?.setTheme(scheme);
+        }
+    }, [scheme, mountScheme]);
     const { themeKey } = frame;
+    const [mountThemeKey] = useState(themeKey);
     useEffect(() => {
-        if (themeKey !== undefined) {
+        if (themeKey !== undefined && themeKey !== mountThemeKey) {
             handle.current?.refreshTheme();
         }
-    }, [themeKey]);
+    }, [themeKey, mountThemeKey]);
     return (_jsxs("div", { "data-porthole-ready": String(ready), style: {
             position: "relative",
             // A url-mode app fills the frame's box (give PortholeFrame a height); the rest size to content.

package/dist/server/server.js

@@ -55,6 +55,10 @@ function mergeEgress(base, extra) {
             merged[kind] = origins;
         }
     }
+    // What the host's config opens to any https site stays; a view can't ask for it (P059).
+    if (base.anyHttps !== undefined) {
+        merged.anyHttps = base.anyHttps;
+    }
     return merged;
 }
 /** `instance` with only the fields Porthole reads, each checked: what a ticket and cookie carry. */