@botiverse/porthole 0.1.7 → 0.2.0

package/dist/conformance/clipboard.js

@@ -8,14 +8,17 @@ import { settle } from "./oracles.js";
  * from the host's page, then pasted back into a text area there.
  */
 const SEED = "porthole-seed";
-/** A text area of the oracle's own on the host's page. */
+/**
+ * A text area of the oracle's own on the host's page: in the conformance harness's layer where
+ * there is one (over an app's own page, P066), else at the top of the page.
+ */
 async function area(page, id) {
     await page.evaluate((each) => {
         if (document.getElementById(each) === null) {
             const element = document.createElement("textarea");
             element.id = each;
             element.style.cssText = "display:block;width:200px;height:40px";
-            document.body.prepend(element);
+            (document.getElementById("porthole-conformance") ?? document.body).prepend(element);
         }
     }, id);
 }

package/dist/conformance/entry.d.ts

@@ -0,0 +1,37 @@
+import { type Frame, type Page } from "@playwright/test";
+import type { FrameOutcome } from "../host/types.ts";
+import type { ConformanceTest } from "./probes.ts";
+/**
+ * Redirect entry's cases (P068): a clean address opens directly, signed in or not, and never
+ * shows content without access; its one-time code works once, on its own origin; in a frame, the
+ * app's sign-in never shows. A host implements `EntryConformanceHost` (or gives
+ * `defineHostConformance` its `entry`).
+ */
+export interface EntryConformanceHost {
+    readonly name: string;
+    /** Signs `page`'s browser in at the app, as a person does, leaving it on the app's page. */
+    signIn(page: Page): Promise<void>;
+    /**
+     * The clean address of a stored page the signed-in viewer may open (`ContentHost.urlOf`), for
+     * `scope`: it draws `<main id="artifact">version 1</main>`.
+     */
+    url(scope: string): string;
+    /** A clean address the signed-in viewer may not open. */
+    denied(scope: string): string;
+    /** Whether `page` shows the app's own sign-in. */
+    atSignIn(page: Page): Promise<boolean>;
+    /** On the app's sign-in page: signs in, as a person does (and the app goes back). */
+    completeSignIn(page: Page): Promise<void>;
+    /**
+     * Frames a clean address on the app's page as the app would (a location of that address),
+     * returning the frame and the display's outcome once it has one.
+     */
+    frame(page: Page, url: string): Promise<{
+        frame(): Promise<Frame>;
+        outcome(): Promise<FrameOutcome>;
+    }>;
+}
+export interface EntrySuiteOptions {
+    readonly skip?: Readonly<Record<string, string>>;
+}
+export declare function entryTests(host: EntryConformanceHost, options?: EntrySuiteOptions): ConformanceTest[];

package/dist/conformance/entry.js

@@ -0,0 +1,120 @@
+import { expect } from "@playwright/test";
+/** Whether a page shows the stored page's own content. */
+const shows = async (where) => (await where.locator("#artifact").count()) > 0;
+/** Walks a redirect entry by hand, as the browser would on a tab: the code URL it ends with. */
+async function codeFor(page, url) {
+    const request = page.context().request;
+    const top = { "sec-fetch-dest": "document" };
+    const begin = await request.get(url, { maxRedirects: 0, headers: top });
+    expect(begin.status(), "a clean address without a cookie goes to the app").toBe(302);
+    const authorized = await request.get(begin.headers().location ?? "", {
+        maxRedirects: 0,
+        headers: top,
+    });
+    expect(authorized.status(), "the app's authorize route gives a code").toBe(302);
+    const code = authorized.headers().location ?? "";
+    expect(code).toContain("/__porthole/entry?code=");
+    return code;
+}
+export function entryTests(host, options = {}) {
+    const tests = [];
+    const define = (id, title, body) => {
+        tests.push({
+            id,
+            title: `${id}: ${title}`,
+            async run({ page, browserName }, info) {
+                const reason = options.skip?.[id];
+                info.skip(reason !== undefined, reason);
+                await body({ page, browserName }, info);
+            },
+        });
+    };
+    define("served.entry.direct", "a clean address opens directly for a signed-in viewer, and stays clean; a reload rides on its cookie", async ({ page }) => {
+        await host.signIn(page);
+        const url = host.url("entry-direct");
+        await page.goto(url);
+        await expect(page.locator("#artifact")).toHaveText("version 1");
+        expect(page.url(), "the address bar shows the clean address, no code").toBe(url);
+        const entries = [];
+        page.on("request", (request) => {
+            if (request.url().includes("/__porthole/entry")) {
+                entries.push(request.url());
+            }
+        });
+        await page.reload();
+        await expect(page.locator("#artifact")).toHaveText("version 1");
+        expect(entries, "a reload needs no entry").toEqual([]);
+    });
+    define("served.entry.signed-out", "signed out, a clean address goes to the app's own sign-in, then back to the content", async ({ page }) => {
+        const url = host.url("entry-signed-out");
+        await page.goto(url);
+        expect(await host.atSignIn(page), "the app's sign-in").toBe(true);
+        expect(await shows(page)).toBe(false);
+        await host.completeSignIn(page);
+        await expect(page.locator("#artifact")).toHaveText("version 1");
+        expect(page.url()).toBe(url);
+    });
+    define("served.entry.denied", "a viewer without access gets the app's refusal, never the content", async ({ page }) => {
+        await host.signIn(page);
+        const url = host.denied("entry-denied");
+        const answer = await page.goto(url);
+        expect(answer?.status()).toBe(403);
+        expect(await shows(page)).toBe(false);
+        expect(new URL(page.url()).origin, "the refusal is the app's").not.toBe(new URL(url).origin);
+    });
+    define("served.entry.code-once", "an entry code works once: replayed, it opens nothing", async ({ page }) => {
+        await host.signIn(page);
+        const code = await codeFor(page, host.url("entry-once"));
+        const request = page.context().request;
+        const top = { "sec-fetch-dest": "document" };
+        const first = await request.get(code, { maxRedirects: 0, headers: top });
+        expect(first.status()).toBe(303);
+        const again = await request.get(code, { maxRedirects: 0, headers: top });
+        expect(again.status()).toBe(403);
+        expect(await again.text()).not.toContain('id="artifact"');
+    });
+    define("served.entry.code-elsewhere", "an entry code taken to another instance's origin opens nothing there", async ({ page }) => {
+        await host.signIn(page);
+        const code = new URL(await codeFor(page, host.url("entry-mine")));
+        const other = new URL(host.url("entry-theirs"));
+        const request = page.context().request;
+        const answer = await request.get(`${other.origin}${code.pathname}${code.search}`, {
+            maxRedirects: 0,
+            headers: { "sec-fetch-dest": "document" },
+        });
+        expect(answer.status()).toBe(403);
+        expect(answer.headers()["set-cookie"] ?? "").not.toMatch(/porthole-[a-z2-7]{16}=/u);
+    });
+    define("served.entry.framed", "a clean address in a frame shows the content where the browser keeps the cookies, else asks for a tab: never the app's sign-in", async ({ page, browserName }, info) => {
+        await host.signIn(page);
+        const shown = await host.frame(page, host.url("entry-framed"));
+        const outcome = await shown.outcome();
+        const frame = await shown.frame();
+        expect(await host.atSignIn(page)).toBe(false);
+        expect(new URL(frame.url()).pathname).not.toMatch(/sign-?in/iu);
+        if (outcome.state === "loaded") {
+            await expect(frame.locator("#artifact")).toHaveText("version 1");
+        }
+        else {
+            expect(outcome).toMatchObject({ state: "blocked" });
+            expect(["cookies", "sign-in"]).toContain(outcome.reason);
+            expect(await shows(frame)).toBe(false);
+        }
+        const said = outcome.state === "blocked" ? `blocked: ${outcome.reason}` : outcome.state;
+        info.annotations.push({
+            type: "measured",
+            description: `${browserName}: framed entry ${said}`,
+        });
+    });
+    define("served.entry.framed-signed-out", "signed out, a clean address in a frame asks for a tab to sign in: the sign-in never shows in a frame", async ({ page }) => {
+        await host.signIn(page);
+        // The app's page stays; the browser forgets every sign-in.
+        await page.context().clearCookies();
+        const shown = await host.frame(page, host.url("entry-framed-out"));
+        expect(await shown.outcome()).toMatchObject({ state: "blocked", reason: "sign-in" });
+        const frame = await shown.frame();
+        await expect(frame.locator("h1")).toHaveText("Open this in a new tab to sign in");
+        expect(await shows(frame)).toBe(false);
+    });
+    return tests;
+}

package/dist/conformance/harness/page.d.ts

@@ -0,0 +1,32 @@
+import type { ConfirmRequest } from "../../bridge/types.ts";
+import type { PortholeConfig } from "../../config/schema.ts";
+import type { FrameLocation, InstanceRef } from "../../isolation/types.ts";
+import type { LaunchSpec, RecordedCall, RecordedEvent } from "../index.ts";
+declare const harness: {
+    /** An opaque display with the suite's content (the leak suite's `launch`). */
+    launch(spec: LaunchSpec): Promise<number>;
+    /**
+     * A served display, located by the app's issue endpoint (`issue`, from this page with its own
+     * cookies) or at a location the test got (`location`), with the suite's content for a shell.
+     */
+    show(config: PortholeConfig, instance: InstanceRef, where: {
+        readonly issue: string;
+        readonly headers?: Readonly<Record<string, string>>;
+    } | {
+        readonly location: FrameLocation;
+    }, content?: string): number;
+    origin: (id: number) => string | null;
+    failure: (id: number) => string | null;
+    received: (id: number) => unknown[];
+    post(id: number, message: unknown): void;
+    setContent(id: number, html: string, partial: boolean): void;
+    calls: (id: number) => RecordedCall[];
+    events: (id: number) => RecordedEvent[];
+    errors: (id: number) => string[];
+    pendingConfirmations: (id: number) => number;
+    answer(id: number, accept: boolean): ConfirmRequest | null;
+    setTheme: (id: number, scheme: "light" | "dark") => void | undefined;
+    destroy(id: number): void;
+};
+export type ConformanceHarness = typeof harness;
+export {};

package/dist/conformance/harness/page.js

@@ -0,0 +1,215 @@
+import { createHost } from "../../host/create-host.js";
+import { httpLocator } from "../../host/locator.js";
+const EVENTS = [
+    "initialized",
+    "resize",
+    "error",
+    "contentError",
+    "hostError",
+    "navigated",
+    "refused",
+    "muted",
+    "outcome",
+    "annotation",
+];
+const nonce = document.currentScript instanceof HTMLScriptElement && document.currentScript.nonce !== ""
+    ? document.currentScript.nonce
+    : undefined;
+const displays = new Map();
+let next = 0;
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** The harness's own layer, over the app's page, so the app's UI never takes a click. */
+function layer() {
+    let element = document.getElementById("porthole-conformance");
+    if (element === null) {
+        element = document.createElement("main");
+        element.id = "porthole-conformance";
+        element.style.cssText =
+            "position:fixed;inset:0;overflow:auto;z-index:2147483000;background:#fff;color:#000;padding:8px";
+        document.body.append(element);
+    }
+    return element;
+}
+function box(id, widthPx, heightPx) {
+    const element = document.createElement("section");
+    element.id = `porthole-display-${id}`;
+    element.style.width = `${widthPx}px`;
+    if (heightPx !== undefined) {
+        element.style.height = `${heightPx}px`;
+    }
+    layer().append(element);
+    return element;
+}
+function recorder(calls) {
+    const record = (capability, value) => (args) => {
+        calls.push({ capability, args });
+        return value;
+    };
+    return {
+        sendPrompt: record("sendPrompt", true),
+        openLink: record("openLink", true),
+        downloadFile: record("downloadFile", true),
+        callTool: record("callTool", { content: [] }),
+        readData: record("readData", { contents: [] }),
+        setModelContext: record("setModelContext", undefined),
+        copyText: record("copyText", true),
+    };
+}
+function watch(id, shown) {
+    for (const type of EVENTS) {
+        shown.handle.on(type, (detail) => shown.events.push({ type, detail }));
+    }
+    displays.set(id, shown);
+}
+/** The frame's messages, from its window and its located origin only, as a host takes them. */
+addEventListener("message", (event) => {
+    for (const shown of displays.values()) {
+        if (shown.frame?.contentWindow === event.source && event.origin === shown.origin) {
+            shown.received.push(event.data);
+        }
+    }
+});
+const harness = {
+    /** An opaque display with the suite's content (the leak suite's `launch`). */
+    async launch(spec) {
+        const id = next;
+        next += 1;
+        const container = box(id, spec.widthPx ?? 600, spec.heightPx);
+        const calls = [];
+        const confirmations = [];
+        const host = createHost(spec.config, {
+            handlers: recorder(calls),
+            ...(spec.confirms === false
+                ? {}
+                : {
+                    confirm: (request) => new Promise((resolve) => confirmations.push({ request, resolve })),
+                }),
+            theme: (scheme) => spec.hostTheme?.[scheme] ?? {},
+            hostInfo: { name: "porthole-conformance", version: "1" },
+            ...(nonce === undefined ? {} : { nonce }),
+        });
+        const handle = host.mount(container, {
+            displayId: `display-${id}`,
+            title: spec.title ?? "Probe",
+            scheme: spec.scheme ?? "light",
+            ...(spec.document === undefined ? {} : { document: spec.document }),
+        });
+        const shown = {
+            handle,
+            calls,
+            events: [],
+            confirmations,
+            received: [],
+            origin: null,
+            failure: null,
+            frame: null,
+        };
+        const initialized = new Promise((resolve) => handle.on("initialized", () => resolve()));
+        watch(id, shown);
+        if (spec.document === undefined) {
+            await Promise.race([initialized, pause(5_000)]);
+            for (const partial of spec.partials ?? []) {
+                handle.setContent(partial, { partial: true });
+                await pause(150);
+            }
+            if (spec.content !== undefined) {
+                handle.setContent(spec.content);
+            }
+        }
+        return id;
+    },
+    /**
+     * A served display, located by the app's issue endpoint (`issue`, from this page with its own
+     * cookies) or at a location the test got (`location`), with the suite's content for a shell.
+     */
+    show(config, instance, where, content) {
+        const id = next;
+        next += 1;
+        const container = box(id, 600, 400);
+        const calls = [];
+        const shown = {
+            handle: null,
+            calls,
+            events: [],
+            confirmations: [],
+            received: [],
+            origin: null,
+            failure: null,
+            frame: null,
+        };
+        const asked = "issue" in where
+            ? httpLocator(where.issue, where.headers === undefined ? {} : { headers: where.headers })
+            : { locate: () => Promise.resolve(where.location) };
+        const locator = {
+            async locate(each, signal) {
+                try {
+                    const location = await asked.locate(each, signal);
+                    shown.origin = location.origin;
+                    return location;
+                }
+                catch (error) {
+                    shown.failure =
+                        error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+                    throw error;
+                }
+            },
+        };
+        const handle = createHost(config, {
+            handlers: recorder(calls),
+            locator,
+            hostInfo: { name: "porthole-conformance", version: "1" },
+            ...(nonce === undefined ? {} : { nonce }),
+        }).mount(container, {
+            displayId: `display-${id}`,
+            title: "Probe",
+            scheme: "light",
+            instance,
+        });
+        shown.handle = handle;
+        watch(id, shown);
+        // The frame element, once it exists, so its messages can be told from others'.
+        const found = () => {
+            shown.frame = container.querySelector("iframe");
+            if (shown.frame === null) {
+                requestAnimationFrame(found);
+            }
+        };
+        found();
+        if (content !== undefined) {
+            handle.setContent(content);
+        }
+        return id;
+    },
+    origin: (id) => displays.get(id)?.origin ?? null,
+    failure: (id) => displays.get(id)?.failure ?? null,
+    received: (id) => displays.get(id)?.received ?? [],
+    post(id, message) {
+        const shown = displays.get(id);
+        if (shown?.frame?.contentWindow && shown.origin !== null) {
+            shown.frame.contentWindow.postMessage(message, shown.origin);
+        }
+    },
+    setContent(id, html, partial) {
+        displays.get(id)?.handle.setContent(html, { partial });
+    },
+    calls: (id) => displays.get(id)?.calls ?? [],
+    events: (id) => displays.get(id)?.events ?? [],
+    errors: (id) => (displays.get(id)?.events ?? []).flatMap((event) => event.type === "error" ? [event.detail.message] : []),
+    pendingConfirmations: (id) => displays.get(id)?.confirmations.length ?? 0,
+    answer(id, accept) {
+        const waiting = displays.get(id)?.confirmations.shift();
+        if (waiting === undefined) {
+            return null;
+        }
+        waiting.resolve(accept);
+        return waiting.request;
+    },
+    setTheme: (id, scheme) => displays.get(id)?.handle.setTheme(scheme),
+    destroy(id) {
+        displays.get(id)?.handle.destroy();
+        document.getElementById(`porthole-display-${id}`)?.remove();
+        displays.delete(id);
+    },
+};
+window.portholeConformance = harness;
+document.documentElement.dataset.portholeConformance = "ready";