@botiverse/porthole 0.1.7 → 0.2.0

package/dist/conformance/host-kit.d.ts

@@ -0,0 +1,85 @@
+import { type Page, type TestType } from "@playwright/test";
+import type { PortholeConfig } from "../config/schema.ts";
+import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
+import { type EntryConformanceHost } from "./entry.ts";
+import type { ConformanceHost } from "./index.ts";
+import { type ServedConformanceHost } from "./served.ts";
+/**
+ * The conformance runner (P066): an app points it at its real page (its CSP, its nonce, its
+ * session) and its issue endpoint; Porthole loads its own harness there (framework-free, on the
+ * core's `createHost`), routes the canaries and a foreign origin, and registers the leak and
+ * served suites in the app's Playwright project:
+ *
+ *   defineHostConformance(test, {
+ *     name: "my-app",
+ *     open: async (page) => { await signIn(page); await page.goto("/viewer"); },
+ *     issue: { url: "/api/frames" },             // the app's ContentHost.issue route
+ *     config: (instance) => servedConfigs[presetOf(instance)],
+ *     instances: { shell: (scope) => ({ scope, document: { kind: "shell", preset: "widget" } }) },
+ *   });
+ */
+export interface HostConformanceOptions {
+    readonly name: string;
+    /** Opens the app's real page in `page` as a person sees it (signed in); the harness runs there. */
+    readonly open: (page: Page) => Promise<void>;
+    /**
+     * The page's script nonce, where its CSP is nonce-based. Default: the first `script[nonce]`'s.
+     * The harness loads as a script from the page's own origin, so `'self'` policies need none.
+     */
+    readonly nonce?: (page: Page) => Promise<string | undefined>;
+    /**
+     * The app's issue endpoint (`ContentHost.issue`), relative to the page: the harness asks it from
+     * the page with the page's own cookies, as the app's client does (`httpLocator`).
+     */
+    readonly issue?: {
+        readonly url: string;
+        readonly headers?: Readonly<Record<string, string>>;
+    };
+    /** Or the location for an instance, got the test's own way. */
+    readonly locate?: (instance: InstanceRef, page: Page) => Promise<FrameLocation>;
+    /** The config a served instance is framed under (the app's served config for its preset). */
+    readonly config: (instance: InstanceRef) => PortholeConfig;
+    /**
+     * The instances the served cases ask for, each for the scope a case names. `shell` runs the
+     * domain-mode cases; `artifact` (versions of one stored page), `app` (url mode) and `proxy` (the
+     * MCP Apps sandbox proxy) run theirs where given, and are skipped (with the reason) where not.
+     */
+    readonly instances: Pick<ServedConformanceHost, "shell"> & Partial<Pick<ServedConformanceHost, "artifact" | "app" | "proxy">>;
+    /**
+     * Redirect entry (P068), where the app serves clean addresses: the cases open them directly,
+     * signed in and out, and in a frame.
+     */
+    readonly entry?: {
+        /** The clean address of `instances.artifact(scope, "1")` (`ContentHost.urlOf`). */
+        readonly url: (scope: string) => string;
+        /** A clean address the signed-in viewer may not open. */
+        readonly denied: (scope: string) => string;
+        /** Whether `page` shows the app's own sign-in. */
+        readonly atSignIn: (page: Page) => Promise<boolean>;
+        /** On the app's sign-in page: signs in, as a person does. */
+        readonly completeSignIn: (page: Page) => Promise<void>;
+    };
+    /** Case ids to skip, each with its reason (shown in the report). */
+    readonly skip?: Readonly<Record<string, string>>;
+}
+/**
+ * The harness as one script: from the package (`dist/conformance/harness.js`), or, run from the
+ * sources, bundled now (esbuild, a development dependency of Porthole's).
+ */
+export declare function harnessScript(): Promise<string>;
+export interface HostConformance {
+    readonly leak: ConformanceHost;
+    readonly served: ServedConformanceHost;
+    /** Redirect entry's host, where the options give `entry`. */
+    readonly entry: EntryConformanceHost | null;
+    /** Prepares a test's page (the canaries, the foreign origin, the harness's route): call first. */
+    begin(page: Page): Promise<void>;
+}
+/** The leak and served hosts on an app's real page, for an app that registers the cases itself. */
+export declare function hostConformance(options: HostConformanceOptions): HostConformance;
+/**
+ * Registers the leak and served suites against an app's real page, in a spec file of the app's
+ * (so `-g "\[1\.connect\]"` selects one). The served cases for instances the app didn't give are
+ * skipped, each with its reason.
+ */
+export declare function defineHostConformance(test: TestType<object, object>, options: HostConformanceOptions): void;

package/dist/conformance/host-kit.js

@@ -0,0 +1,341 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { expect } from "@playwright/test";
+import { entryTests } from "./entry.js";
+import { leakTests } from "./probes.js";
+import { servedTests } from "./served.js";
+const CANARY = "https://porthole-canary.example";
+/** A page on no one's origin that frames what a case asks (routed by the test, like the canary). */
+const FOREIGN = "http://porthole-foreign.example";
+/** Where the harness loads from, on the app's own origin (routed by the test, never the app's). */
+const HARNESS_PATH = "/__porthole/conformance/harness.js";
+let built = null;
+/**
+ * The harness as one script: from the package (`dist/conformance/harness.js`), or, run from the
+ * sources, bundled now (esbuild, a development dependency of Porthole's).
+ */
+export function harnessScript() {
+    built ??= (async () => {
+        try {
+            return await readFile(new URL("./harness.js", import.meta.url), "utf8");
+        }
+        catch {
+            const { build } = await import("esbuild");
+            const result = await build({
+                entryPoints: [fileURLToPath(new URL("./harness/page.ts", import.meta.url))],
+                bundle: true,
+                format: "iife",
+                platform: "browser",
+                target: "es2022",
+                write: false,
+                logLevel: "silent",
+            });
+            const text = result.outputFiles[0]?.text;
+            if (text === undefined) {
+                throw new Error("the conformance harness didn't build");
+            }
+            return text;
+        }
+    })();
+    return built;
+}
+/** Calls one of the harness's methods in the page. */
+function invoke(page, method, ...args) {
+    return page.evaluate(([name, given]) => {
+        const harness = window.portholeConformance;
+        const run = harness?.[name];
+        if (run === undefined) {
+            throw new Error(`the conformance harness has no ${name}`);
+        }
+        return run(...given);
+    }, [method, args]);
+}
+/** The display's frame element's document, once it exists. */
+async function frameIn(page, id) {
+    let found = null;
+    await expect
+        .poll(async () => {
+        const element = await page
+            .locator(`#porthole-display-${id} iframe`)
+            .elementHandle({ timeout: 2_000 })
+            .catch(() => null);
+        found = (await element?.contentFrame()) ?? null;
+        return found !== null;
+    })
+        .toBe(true);
+    return found;
+}
+/** The leak and served hosts on an app's real page, for an app that registers the cases itself. */
+export function hostConformance(options) {
+    let current = null;
+    const opened = new WeakSet();
+    const hits = new Map();
+    const open = async (page) => {
+        await options.open(page);
+        opened.add(page);
+    };
+    /** Opens the app's page, if it isn't, and loads the harness into it under the page's policy. */
+    const ready = async (page) => {
+        const loaded = await page
+            .evaluate(() => document.documentElement.dataset.portholeConformance === "ready")
+            .catch(() => false);
+        if (loaded) {
+            return;
+        }
+        await open(page);
+        const nonce = (await options.nonce?.(page)) ??
+            (await page.evaluate(() => document.querySelector("script[nonce]")?.nonce || undefined));
+        await page.evaluate(([path, given]) => {
+            const script = document.createElement("script");
+            if (given !== undefined) {
+                script.nonce = given;
+            }
+            script.src = path;
+            document.head.append(script);
+        }, [HARNESS_PATH, nonce]);
+        await expect
+            .poll(() => page.evaluate(() => document.documentElement.dataset.portholeConformance), {
+            message: "the harness runs on the app's page (does its CSP let a script from its own origin, or with its nonce, run?)",
+        })
+            .toBe("ready");
+    };
+    const leak = {
+        name: options.name,
+        async launch(page, spec) {
+            await ready(page);
+            const id = await invoke(page, "launch", spec);
+            return {
+                frame: () => frameIn(page, id),
+                async box() {
+                    const element = await page.locator(`#porthole-display-${id} iframe`).elementHandle();
+                    const area = await element?.boundingBox();
+                    return { width: area?.width ?? 0, height: area?.height ?? 0 };
+                },
+                setContent: (html, given) => invoke(page, "setContent", id, html, given?.partial === true),
+                setTheme: (scheme) => invoke(page, "setTheme", id, scheme),
+                async answerNextConfirmation(accept, given) {
+                    await expect
+                        .poll(() => invoke(page, "pendingConfirmations", id), {
+                        timeout: given?.timeoutMs ?? 5_000,
+                    })
+                        .toBeGreaterThan(0);
+                    const request = await invoke(page, "answer", id, accept);
+                    if (request === null) {
+                        throw new Error("no confirmation was waiting");
+                    }
+                    return request;
+                },
+                calls: () => invoke(page, "calls", id),
+                errors: () => invoke(page, "errors", id),
+                events: () => invoke(page, "events", id),
+                destroy: () => invoke(page, "destroy", id),
+            };
+        },
+    };
+    const locate = async (instance) => {
+        const page = current;
+        if (page === null) {
+            throw new Error("the runner has no page: call begin(page) first");
+        }
+        if (options.locate !== undefined) {
+            return options.locate(instance, page);
+        }
+        if (options.issue === undefined) {
+            throw new Error("the runner needs the app's issue endpoint (issue) or locate");
+        }
+        if (!opened.has(page)) {
+            await open(page);
+        }
+        // Asked as the page asks it: the context's cookies, the page's origin.
+        const response = await page
+            .context()
+            .request.post(new URL(options.issue.url, page.url()).href, {
+            data: { instance },
+            headers: { origin: new URL(page.url()).origin, ...options.issue.headers },
+            maxRedirects: 0,
+        });
+        if (response.status() !== 201) {
+            throw new Error(`the app's issue endpoint answered ${response.status()}: ${(await response.text()).slice(0, 200)}`);
+        }
+        return (await response.json());
+    };
+    const { artifact, app, proxy } = options.instances;
+    const served = {
+        name: options.name,
+        async show(page, instance, given = {}) {
+            await ready(page);
+            const where = options.locate === undefined && options.issue !== undefined
+                ? {
+                    issue: options.issue.url,
+                    ...(options.issue.headers === undefined ? {} : { headers: options.issue.headers }),
+                }
+                : { location: await locate(instance) };
+            const id = await invoke(page, "show", options.config(instance), instance, where, given.content);
+            let origin = null;
+            await expect
+                .poll(async () => {
+                origin = await invoke(page, "origin", id);
+                return origin ?? (await invoke(page, "failure", id)) ?? "";
+            }, { message: "the app's issue endpoint locates the instance" })
+                .toMatch(/^https?:\/\//u);
+            const located = origin;
+            return {
+                origin: located,
+                async frame() {
+                    const frame = await frameIn(page, id);
+                    await frame.waitForURL((url) => url.origin === located);
+                    // A url-mode app's entry page goes on to the app where the browser kept the cookie; where
+                    // it didn't (WebKit, P025), it stays, saying so: the frame is that page then.
+                    await frame
+                        .waitForURL((url) => url.pathname !== "/__porthole/enter", { timeout: 5_000 })
+                        .catch(() => undefined);
+                    await frame.waitForLoadState("load");
+                    return frame;
+                },
+                destroy: () => invoke(page, "destroy", id),
+                post: (message) => invoke(page, "post", id, message),
+                received: () => invoke(page, "received", id),
+            };
+        },
+        locate,
+        async frameFromForeignOrigin(page, url) {
+            await page.goto(`${FOREIGN}/?frame=${encodeURIComponent(url)}`);
+        },
+        canary: (name) => Promise.resolve(`${CANARY}/${name}`),
+        canaryHits: (name) => Promise.resolve(hits.get(name) ?? 0),
+        shell: options.instances.shell,
+        // Asked for only by cases that run where the app gave them (`defineHostConformance` skips).
+        artifact: artifact ??
+            ((scope, version) => ({ scope, document: { kind: "artifact", id: "page", version } })),
+        app: app ?? ((scope) => ({ scope, document: { kind: "external", url: "http://app.test/" } })),
+        proxy: proxy ?? ((scope) => ({ scope, document: { kind: "mcp-proxy" } })),
+    };
+    const given = options.entry;
+    const entry = given === undefined
+        ? null
+        : {
+            name: options.name,
+            // Signed in on the app's page, the harness there (a frame needs it).
+            signIn: async (page) => {
+                await open(page);
+                await ready(page);
+            },
+            url: given.url,
+            denied: given.denied,
+            atSignIn: given.atSignIn,
+            completeSignIn: given.completeSignIn,
+            async frame(page, url) {
+                await ready(page);
+                const instance = served.artifact("entry", "1");
+                const id = await invoke(page, "show", options.config(instance), instance, {
+                    location: { url, origin: new URL(url).origin },
+                });
+                return {
+                    frame: () => frameIn(page, id),
+                    async outcome() {
+                        let found = null;
+                        await expect
+                            .poll(async () => {
+                            const events = await invoke(page, "events", id);
+                            const each = events.find((event) => event.type === "outcome");
+                            found = each === undefined ? null : each.detail;
+                            return found !== null;
+                        }, { message: "the display has an outcome", timeout: 15_000 })
+                            .toBe(true);
+                        return found;
+                    },
+                };
+            },
+        };
+    return {
+        leak,
+        served,
+        entry,
+        async begin(page) {
+            current = page;
+            const script = await harnessScript();
+            await page.route(`**${HARNESS_PATH}`, (route) => route.fulfill({
+                status: 200,
+                contentType: "text/javascript; charset=utf-8",
+                headers: { "cache-control": "no-store" },
+                body: script,
+            }));
+            await page.context().route(`${CANARY}/**`, (route) => {
+                const name = new URL(route.request().url()).pathname.slice(1);
+                hits.set(name, (hits.get(name) ?? 0) + 1);
+                return route.fulfill({ status: 200, contentType: "text/plain", body: "canary" });
+            });
+            await page.context().route(`${FOREIGN}/**`, (route) => {
+                const target = new URL(route.request().url()).searchParams.get("frame") ?? "";
+                const attribute = target.replace(/&/gu, "&").replace(/"/gu, """);
+                return route.fulfill({
+                    status: 200,
+                    contentType: "text/html",
+                    body: `<!doctype html><title>Foreign</title><iframe sandbox="allow-scripts allow-same-origin" src="${attribute}"></iframe>`,
+                });
+            });
+        },
+    };
+}
+const URL_CASES = [
+    "served.url.origin",
+    "served.url.no-reach",
+    "served.url.no-top-navigation",
+    "served.url.no-popups",
+    "served.url.ticket",
+    "served.url.tab",
+    "served.url.framed",
+];
+const PROXY_CASES = ["served.proxy.view", "served.proxy.parent-only", "served.proxy.egress"];
+/**
+ * Registers the leak and served suites against an app's real page, in a spec file of the app's
+ * (so `-g "\[1\.connect\]"` selects one). The served cases for instances the app didn't give are
+ * skipped, each with its reason.
+ */
+export function defineHostConformance(test, options) {
+    const typed = test;
+    const hosts = hostConformance(options);
+    const skip = { ...options.skip };
+    const absent = (ids, reason) => {
+        for (const id of ids) {
+            skip[id] ??= reason;
+        }
+    };
+    if (options.instances.artifact === undefined) {
+        absent(["served.artifact.versions"], "the app serves no versions of a stored page");
+    }
+    if (options.instances.app === undefined) {
+        absent(URL_CASES, "the app serves no url-mode apps");
+    }
+    if (options.instances.proxy === undefined) {
+        absent(PROXY_CASES, "the app serves no MCP Apps views");
+    }
+    typed.describe(`Porthole leak suite (${options.name})`, () => {
+        for (const each of leakTests(hosts.leak, { skip })) {
+            // Playwright reads the fixtures a test uses from its parameter's destructuring.
+            typed(each.title, async ({ page, browserName }, info) => {
+                await hosts.begin(page);
+                await each.run({ page, browserName }, info);
+            });
+        }
+    });
+    typed.describe(`Porthole served modes (${options.name})`, () => {
+        for (const each of servedTests(hosts.served, { skip })) {
+            typed(each.title, async ({ page, browserName }, info) => {
+                await hosts.begin(page);
+                await each.run({ page, browserName }, info);
+            });
+        }
+    });
+    const entry = hosts.entry;
+    if (entry !== null) {
+        typed.describe(`Porthole redirect entry (${options.name})`, () => {
+            for (const each of entryTests(entry, { skip })) {
+                typed(each.title, async ({ page, browserName }, info) => {
+                    await hosts.begin(page);
+                    await each.run({ page, browserName }, info);
+                });
+            }
+        });
+    }
+}

package/dist/conformance/index.d.ts

@@ -101,3 +101,5 @@ export interface LeakSuiteOptions {
 export { defineLeakSuite, leakTests, PROBES, type ConformanceFixtures, type ConformanceTest, type Probe, } from "./probes.ts";
 export { httpOracle, settle, udpOracle, type HttpOracle, type UdpOracle } from "./oracles.ts";
 export { defineServedSuite, servedTests, type ServedConformanceHost, type ServedDisplay, type ServedSuiteOptions, } from "./served.ts";
+export { entryTests, type EntryConformanceHost, type EntrySuiteOptions } from "./entry.ts";
+export { defineHostConformance, harnessScript, hostConformance, type HostConformance, type HostConformanceOptions, } from "./host-kit.ts";

package/dist/conformance/index.js

@@ -2,3 +2,7 @@ export { defineLeakSuite, leakTests, PROBES, } from "./probes.js";
 export { httpOracle, settle, udpOracle } from "./oracles.js";
 // The served modes' cases (domain and url mode), with their own host interface.
 export { defineServedSuite, servedTests, } from "./served.js";
+// Redirect entry's cases (P068).
+export { entryTests } from "./entry.js";
+// The runner an app points at its real page and issue endpoint (P066).
+export { defineHostConformance, harnessScript, hostConformance, } from "./host-kit.js";

package/dist/conformance/limits.js

@@ -119,7 +119,7 @@ export const LIMIT_PROBES = [
     {
         id: "14.silent",
         item: 14,
-        title: "what the sandbox blocks fails silently: nothing loads, a fetch rejects, nothing is shown",
+        title: "what the sandbox blocks shows nothing on the page: nothing loads, a fetch rejects; the host hears of it where reportError is declared, and nothing where it isn't",
         async run(context) {
             const canary = await context.http();
             const seen = watch(context.page);
@@ -143,6 +143,21 @@ export const LIMIT_PROBES = [
             });
             expect(canary.requests()).toEqual([]);
             expect(seen.dialogs).toEqual([]);
+            // Where reportError is declared, each block is reported to the host (the manual says where
+            // it goes, by \`errors\`, #4); where it isn't, nothing is.
+            await expect
+                .poll(async () => (await display.errors()).some((each) => each.startsWith("Blocked by the sandbox:")))
+                .toBe(true);
+            const quiet = await context.launch({
+                config: inline({ errors: "none" }),
+                content: attack(`
+    r.fetch = await fetch(${js(`${c}/quiet`)}).then(() => "sent", (e) => "rejected " + e.name);`, `<img src="${c}/quiet.png">`),
+            });
+            expect(await context.result(quiet, 15_000)).toMatchObject({ fetch: "rejected TypeError" });
+            await settle();
+            expect(await quiet.errors()).toEqual([]);
+            expect(canary.requests()).toEqual([]);
+            expect(seen.dialogs).toEqual([]);
         },
     },
     {

package/dist/conformance/served.js

@@ -375,9 +375,19 @@ export function servedTests(host, options = {}) {
         });
         define("served.url.ticket", "an app shows nothing to a browser without its ticket's cookie", async ({ page }) => {
             const location = await host.locate(host.app("url-ticket"));
-            const bare = await page.goto(`${location.origin}/`);
-            expect(bare?.status()).toBe(401);
-            expect(await page.evaluate(() => document.documentElement.dataset.app ?? null)).toBeNull();
+            // A fresh browser: no cookie of the content's, none of the app's. Porthole refuses it, or
+            // (redirect entry, P068) hands it to the app's authorize route, which asks it to sign in.
+            const fresh = await page.context().browser().newContext();
+            try {
+                const other = await fresh.newPage();
+                const bare = await other.goto(`${location.origin}/`);
+                const away = new URL(other.url()).origin !== location.origin;
+                expect(bare?.status() === 401 || away, `ended at ${other.url()}`).toBe(true);
+                expect(await other.evaluate(() => document.documentElement.dataset.app ?? null)).toBeNull();
+            }
+            finally {
+                await fresh.close();
+            }
         });
         define("served.url.tab", "an app opened on a tab of its own runs, its requests riding on its cookie", async ({ page }) => {
             const location = await host.locate(host.app("url-tab"));

package/dist/guide/limits.js

@@ -81,7 +81,15 @@ export function manualLimits(config, network) {
         : documents === "never"
             ? "It always shows in light: the app doesn't theme it, so style it yourself; prefers-color-scheme may report the reader's system setting, so don't rely on it."
             : 'It shows in light, as you style it; to follow the person\'s light or dark theme, declare it in its head (<meta name="color-scheme" content="light dark">) and draw with the variables below.');
-    add("silent", "What the sandbox blocks fails silently: a blocked script, style or image just doesn't load, a blocked fetch rejects, and nothing shows an error.");
+    // What a block does on the page, and where it is reported: as the Errors line says (#4).
+    const blocked = "a blocked script, style or image just doesn't load and a blocked fetch rejects";
+    add("silent", !declared.has("reportError")
+        ? "What the sandbox blocks fails silently: a blocked script, style or image just doesn't load, a blocked fetch rejects, and nothing shows an error."
+        : config.errors === "agent"
+            ? `What the sandbox blocks shows nothing on the page: ${blocked}. Each block comes back to you as an error, so check them.`
+            : config.errors === "host"
+                ? `What the sandbox blocks shows nothing on the page: ${blocked}. The app is told of each block, but you aren't: test what you write.`
+                : `What the sandbox blocks shows nothing on the page: ${blocked}. Each block is reported to the app.`);
     add("network", network);
     // Assets: what isn't opened goes inline (Network: none already says "everything inline").
     const anywhere = (kind) => (config.egress.anyHttps ?? []).some((each) => each === kind);

package/dist/host/locator.d.ts

@@ -0,0 +1,39 @@
+import type { PortholeConfig } from "../config/schema.ts";
+import type { InstanceLocator } from "../isolation/types.ts";
+/**
+ * The client half of the host kit (P066): a locator that asks the app's issue endpoint
+ * (`ContentHost.issue`) for a frame's location, and the choice between served and opaque configs.
+ * The client proposes an instance; the server's mapping decides what it means, and the server
+ * alone chooses the origin.
+ */
+/** Why the issue endpoint gave no location: its status and code (`not-served`, `forbidden`, …). */
+export declare class LocateError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+export interface HttpLocatorOptions {
+    /** Headers for each request (an `authorization`), or a function giving them now. */
+    readonly headers?: HeadersInit | (() => HeadersInit);
+    /** Default `same-origin` (the app's own cookies). */
+    readonly credentials?: RequestCredentials;
+    /** Content frames aren't served now: refresh what the page knows (`ContentHost.meta`). */
+    readonly onNotServed?: () => void;
+    readonly fetch?: typeof fetch;
+}
+/** A locator that POSTs `{ instance }` to the app's issue endpoint at `url`. */
+export declare function httpLocator(url: string, options?: HttpLocatorOptions): InstanceLocator;
+/** What the page knows of content (`ContentHost.meta`, as the app's own meta carries it). */
+export interface ServedMeta {
+    readonly served: boolean;
+    readonly contentSource: string | null;
+}
+/**
+ * The configs a page's displays run under: served (from the content source) while content is
+ * served, opaque otherwise; null while the page doesn't know yet, so a frame never starts opaque
+ * and then restarts served.
+ */
+export declare function servedOrOpaque<T extends Readonly<Record<string, PortholeConfig>>>(meta: ServedMeta | null | undefined, served: (contentSource: string) => T, opaque: T): {
+    readonly served: boolean;
+    readonly configs: T;
+} | null;

package/dist/host/locator.js

@@ -0,0 +1,72 @@
+/**
+ * The client half of the host kit (P066): a locator that asks the app's issue endpoint
+ * (`ContentHost.issue`) for a frame's location, and the choice between served and opaque configs.
+ * The client proposes an instance; the server's mapping decides what it means, and the server
+ * alone chooses the origin.
+ */
+/** Why the issue endpoint gave no location: its status and code (`not-served`, `forbidden`, …). */
+export class LocateError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.name = "LocateError";
+        this.status = status;
+        this.code = code;
+    }
+}
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** A locator that POSTs `{ instance }` to the app's issue endpoint at `url`. */
+export function httpLocator(url, options = {}) {
+    return {
+        async locate(instance, signal) {
+            const extra = typeof options.headers === "function" ? options.headers() : options.headers;
+            const headers = new Headers(extra);
+            headers.set("content-type", "application/json");
+            headers.set("accept", "application/json");
+            const response = await (options.fetch ?? fetch)(url, {
+                method: "POST",
+                headers,
+                credentials: options.credentials ?? "same-origin",
+                redirect: "error",
+                body: JSON.stringify({ instance }),
+                ...(signal === undefined ? {} : { signal }),
+            });
+            const data = await response.json().catch(() => null);
+            if (!response.ok) {
+                const error = isRecord(data) && isRecord(data.error) ? data.error : {};
+                const code = typeof error.code === "string" ? error.code : "failed";
+                if (code === "not-served") {
+                    options.onNotServed?.();
+                }
+                throw new LocateError(typeof error.message === "string"
+                    ? error.message
+                    : `The app's issue endpoint answered ${response.status}`, response.status, code);
+            }
+            if (!isRecord(data) ||
+                typeof data.url !== "string" ||
+                typeof data.origin !== "string" ||
+                (data.reports !== undefined && typeof data.reports !== "boolean")) {
+                throw new LocateError("The app's issue endpoint gave no frame location", response.status, "bad-location");
+            }
+            return {
+                url: data.url,
+                origin: data.origin,
+                ...(typeof data.reports === "boolean" ? { reports: data.reports } : {}),
+            };
+        },
+    };
+}
+/**
+ * The configs a page's displays run under: served (from the content source) while content is
+ * served, opaque otherwise; null while the page doesn't know yet, so a frame never starts opaque
+ * and then restarts served.
+ */
+export function servedOrOpaque(meta, served, opaque) {
+    if (meta === null || meta === undefined) {
+        return null;
+    }
+    return meta.served && meta.contentSource !== null
+        ? { served: true, configs: served(meta.contentSource) }
+        : { served: false, configs: opaque };
+}

package/dist/host/outcome.js

@@ -18,6 +18,7 @@ const SETTLE_MS = 400;
 const BLOCKS = [
     "framing",
     "cookies",
+    "sign-in",
     "session",
     "upstream",
     "denied",

package/dist/host/types.d.ts

@@ -79,6 +79,8 @@ export type FrameBlock =
 "framing"
 /** The browser keeps no cookie for it inside a frame (WebKit, P025): open it on a tab. */
  | "cookies"
+/** The person isn't signed in at the app, and its sign-in never shows in a frame: a tab (P068). */
+ | "sign-in"
 /** Its ticket was used or its session ended. */
  | "session"
 /** Its app didn't answer. */

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS
 export type { CallContext, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmAnswer, ConfirmRequest, Proceed, HostFunctionBridge, Refusal, } from "./bridge/types.ts";
 export { createHost } from "./host/create-host.ts";
 export { writeClipboard } from "./host/clipboard.ts";
+export { httpLocator, LocateError, servedOrOpaque, type HttpLocatorOptions, type ServedMeta, } from "./host/locator.ts";
 export type { AnnotationControls, DisplayControls, DisplayEvents, FrameBlock, FrameOutcome, DisplayHandle, HostOptions, MountOptions, PortholeHost, } from "./host/types.ts";
 export { ANNOTATE_METHODS, ANNOTATION_LIMITS, type AnchorResult, type AnchorState, type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport, type AnnotationSelector, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
 export { parseAnchor, parseRect, parseReport } from "./annotate/validate.ts";