@botiverse/porthole 0.0.0-stage → 0.1.0

package/dist/conformance/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * `@botiverse/porthole/conformance`: the leak/conformance suite (P008), runnable by any host
+ * against its own integration. A host implements `ConformanceHost` (how to show one display in a
+ * page and drive it), then registers the suite in its Playwright project:
+ *
+ *   import { test } from "@playwright/test";
+ *   import { defineLeakSuite } from "@botiverse/porthole/conformance";
+ *   defineLeakSuite(test, myHost);
+ *
+ * Each probe attempts one egress or escape channel (DESIGN.md § Egress hardening) and asserts,
+ * with an out-of-band oracle where one exists (an HTTP canary that also counts connections, a UDP
+ * listener for ICE), that nothing left. Each oracle has a positive control: where the engine
+ * can't make the channel work even unsandboxed, the probe says so instead of passing silently.
+ * Porthole runs it against its own reference host on every engine it supports.
+ */
+import type { Frame, Page } from "@playwright/test";
+import type { ConfirmRequest } from "../bridge/types.ts";
+import type { CapabilityName } from "../config/capabilities.ts";
+import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
+import type { DisplayEvents } from "../host/types.ts";
+export interface LaunchSpec {
+    readonly config: PortholeConfig;
+    /**
+     * The whole content (a fragment, or a document for artifact mode). Omitted: nothing is sent,
+     * and the test drives the content with `LaunchedDisplay.setContent`.
+     */
+    readonly content?: string;
+    /** Content to stream first, each step sent as partial, before the whole. */
+    readonly partials?: readonly string[];
+    /** A whole document the frame starts with instead (an MCP Apps view). */
+    readonly document?: string;
+    readonly title?: string;
+    readonly scheme?: ColorScheme;
+    /** The frame's width, px. */
+    readonly widthPx?: number;
+    /** The host's live values for theme variables, per scheme (as `HostOptions.theme` answers). */
+    readonly hostTheme?: {
+        readonly light?: Readonly<Record<string, string>>;
+        readonly dark?: Readonly<Record<string, string>>;
+    };
+    /** Whether the host has a `confirm` function (default true): without one, gated calls are refused. */
+    readonly confirms?: boolean;
+}
+export interface RecordedCall {
+    readonly capability: CapabilityName;
+    readonly args: unknown;
+}
+export type RecordedEvent = {
+    [E in keyof DisplayEvents]: {
+        readonly type: E;
+        readonly detail: DisplayEvents[E];
+    };
+}[keyof DisplayEvents];
+export interface LaunchedDisplay {
+    /** The display's frame as it is now (a restart makes a new one), to probe from inside. */
+    frame(): Promise<Frame>;
+    /** The frame element's size on the host's page, px. */
+    box(): Promise<{
+        readonly width: number;
+        readonly height: number;
+    }>;
+    /** Sends content: partial (drawn inert) any number of times, then whole (runs once). */
+    setContent(html: string, options?: {
+        readonly partial?: boolean;
+    }): Promise<void>;
+    setTheme(scheme: ColorScheme): Promise<void>;
+    /** Waits for the next confirmation the host is asked for, answers it, and returns it. */
+    answerNextConfirmation(accept: boolean, options?: {
+        readonly timeoutMs?: number;
+    }): Promise<ConfirmRequest>;
+    /** The calls that reached the host's handlers, in order. */
+    calls(): Promise<readonly RecordedCall[]>;
+    /** The errors the display reported. */
+    errors(): Promise<readonly string[]>;
+    /** Every event the display emitted, in order. */
+    events(): Promise<readonly RecordedEvent[]>;
+    destroy(): Promise<void>;
+}
+/** What a host implements to run the suite against its integration. */
+export interface ConformanceHost {
+    readonly name: string;
+    /**
+     * Shows one display in `page` and returns handles to drive it. The first call on a page loads
+     * the host's page (sending its embedding CSP for `spec.config`); a later call on the same page
+     * adds another display beside the first.
+     */
+    launch(page: Page, spec: LaunchSpec): Promise<LaunchedDisplay>;
+}
+export interface LeakSuiteOptions {
+    /** Probe ids to skip, each with the reason (shown in the report). */
+    readonly skip?: Readonly<Record<string, string>>;
+}
+export { defineLeakSuite, PROBES, type Probe } from "./probes.ts";
+export { httpOracle, settle, udpOracle, type HttpOracle, type UdpOracle } from "./oracles.ts";
+export { defineServedSuite, type ServedConformanceHost, type ServedDisplay, type ServedSuiteOptions, } from "./served.ts";

package/dist/conformance/index.js

@@ -0,0 +1,4 @@
+export { defineLeakSuite, 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, } from "./served.js";

package/dist/conformance/kit.d.ts

@@ -0,0 +1,42 @@
+import type { Page } from "@playwright/test";
+import { type PresetOptions } from "../presets/presets.ts";
+import type { LaunchedDisplay, LaunchSpec } from "./index.ts";
+import type { HttpOracle, ServedFile, UdpOracle } from "./oracles.ts";
+/** What every probe is given, and the helpers they share. */
+export interface ProbeContext {
+    readonly page: Page;
+    readonly engine: string;
+    launch(spec: LaunchSpec): Promise<LaunchedDisplay>;
+    /** A fresh HTTP oracle (serving `files` at their paths), closed after the probe. */
+    http(files?: Readonly<Record<string, ServedFile>>): Promise<HttpOracle>;
+    /** A fresh UDP oracle, closed after the probe. */
+    udp(): Promise<UdpOracle>;
+    /** Waits for the content's verdict (`window.portholeProbe`, set by `attack`) and returns it. */
+    result(display: LaunchedDisplay, timeoutMs?: number): Promise<Record<string, unknown>>;
+    /**
+     * The URLs on `origin` that answered the page (any of its frames): requests that left the
+     * browser and came back. A load the browser blocked itself never has a response.
+     */
+    requestsTo(origin: string): string[];
+    /** Records a measured engine fact in the report. */
+    measured(text: string): void;
+}
+export interface Probe {
+    /** Stable id, `<item>.<channel>`: what `LeakSuiteOptions.skip` names. */
+    readonly id: string;
+    /**
+     * The DESIGN.md egress-table item it proves; 0 for the shell's own wiring and interop, 11 for
+     * behavior (streaming, sizing, theming), 12 for host-function gates.
+     */
+    readonly item: number;
+    readonly title: string;
+    run(context: ProbeContext): Promise<void>;
+}
+/** A JS literal safe inside an inline `<script>` (no `</script>` can end it early). */
+export declare const js: (value: unknown) => string;
+/**
+ * Content that runs `code` (an async body with `r`, its verdict, in scope) once the shell has
+ * drawn it, then publishes `r` as `window.portholeProbe`. A `#marker` shows the content is still there.
+ */
+export declare function attack(code: string, markup?: string): string;
+export declare const inline: (options?: PresetOptions) => import("../index.ts").PortholeConfig;

package/dist/conformance/kit.js

@@ -0,0 +1,24 @@
+import { presets } from "../presets/presets.js";
+/** A JS literal safe inside an inline `<script>` (no `</script>` can end it early). */
+export const js = (value) => JSON.stringify(value).replace(/</gu, "\\u003c");
+/**
+ * Content that runs `code` (an async body with `r`, its verdict, in scope) once the shell has
+ * drawn it, then publishes `r` as `window.portholeProbe`. A `#marker` shows the content is still there.
+ */
+export function attack(code, markup = "") {
+    return `<div id="marker">content</div>${markup}
+<script>
+(async () => {
+  const r = {};
+  const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  try {
+${code}
+  } catch (error) {
+    r.error = String((error && error.message) || error);
+  }
+  r.done = true;
+  window.portholeProbe = r;
+})();
+</script>`;
+}
+export const inline = (options = {}) => presets.inlineWidget(options);

package/dist/conformance/oracles.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Out-of-band oracles: listeners outside the browser that see what actually left it. A probe
+ * points content at one and asserts it heard nothing; a positive control points something allowed
+ * at one and asserts it heard it, so a silent oracle is never mistaken for a wall.
+ */
+export interface HeardRequest {
+    readonly method: string;
+    readonly path: string;
+    readonly origin: string | undefined;
+}
+export interface HttpOracle {
+    /** `http://127.0.0.1:<port>`: an exact origin a config can allow or leave out. */
+    readonly origin: string;
+    /** Every request it answered. */
+    requests(): readonly HeardRequest[];
+    /** Every TCP connection opened to it, whether or not a request followed (preconnects). */
+    connections(): number;
+    close(): Promise<void>;
+}
+/** A file an oracle serves at a path, instead of its stand-in answer (a library, say). */
+export interface ServedFile {
+    readonly type: string;
+    readonly data: string | Buffer;
+}
+export declare function httpOracle(files?: Readonly<Record<string, ServedFile>>): Promise<HttpOracle>;
+export interface UdpOracle {
+    /** `stun:127.0.0.1:<port>`, for an ICE server list. */
+    readonly stun: string;
+    /** The datagrams that reached it. */
+    packets(): number;
+    close(): Promise<void>;
+}
+export declare function udpOracle(): Promise<UdpOracle>;
+/** Waits `ms`, so a request that was going to leave has time to arrive. */
+export declare const settle: (ms?: number) => Promise<void>;

package/dist/conformance/oracles.js

@@ -0,0 +1,77 @@
+import { createSocket } from "node:dgram";
+import { createServer } from "node:http";
+const PIXEL = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", "base64");
+/** What the oracle answers, by the path's extension: real enough for each kind of load to finish. */
+function body(path) {
+    if (/\.m?js(\?|$)/u.test(path)) {
+        return {
+            type: "text/javascript",
+            data: "globalThis.__portholeOracleScript = (globalThis.__portholeOracleScript || 0) + 1;",
+        };
+    }
+    if (/\.css(\?|$)/u.test(path)) {
+        return { type: "text/css", data: "html { --porthole-oracle: 1; }" };
+    }
+    if (/\.(png|gif|jpg)(\?|$)/u.test(path)) {
+        return { type: "image/png", data: PIXEL };
+    }
+    if (/\.html(\?|$)/u.test(path)) {
+        return {
+            type: "text/html",
+            data: "<!doctype html><title>oracle</title><p id=oracle>oracle</p>",
+        };
+    }
+    return { type: "text/plain", data: "oracle" };
+}
+export async function httpOracle(files = {}) {
+    const heard = [];
+    let connections = 0;
+    const server = createServer((request, response) => {
+        heard.push({
+            method: request.method ?? "GET",
+            path: request.url ?? "/",
+            origin: request.headers.origin,
+        });
+        const { type, data } = files[request.url ?? "/"] ?? body(request.url ?? "/");
+        response.writeHead(200, {
+            "content-type": type,
+            "access-control-allow-origin": "*",
+            "cache-control": "no-store",
+        });
+        response.end(data);
+    });
+    server.on("connection", () => {
+        connections += 1;
+    });
+    server.on("upgrade", (request, socket) => {
+        heard.push({ method: "UPGRADE", path: request.url ?? "/", origin: request.headers.origin });
+        socket.destroy();
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address();
+    return {
+        origin: `http://127.0.0.1:${port}`,
+        requests: () => [...heard],
+        connections: () => connections,
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections();
+            server.close(() => resolve());
+        }),
+    };
+}
+export async function udpOracle() {
+    let packets = 0;
+    const socket = createSocket("udp4");
+    socket.on("message", () => {
+        packets += 1;
+    });
+    await new Promise((resolve) => socket.bind(0, "127.0.0.1", resolve));
+    const { port } = socket.address();
+    return {
+        stun: `stun:127.0.0.1:${port}`,
+        packets: () => packets,
+        close: () => new Promise((resolve) => socket.close(() => resolve())),
+    };
+}
+/** Waits `ms`, so a request that was going to leave has time to arrive. */
+export const settle = (ms = 800) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/conformance/probes.d.ts

@@ -0,0 +1,9 @@
+import { type PlaywrightTestArgs, type PlaywrightTestOptions, type PlaywrightWorkerArgs, type PlaywrightWorkerOptions, type TestType } from "@playwright/test";
+import type { ConformanceHost, LeakSuiteOptions } from "./index.ts";
+import { type Probe } from "./kit.ts";
+export type { Probe, ProbeContext } from "./kit.ts";
+export { attack } from "./kit.ts";
+export declare const PROBES: readonly Probe[];
+type AnyTest = TestType<PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
+/** Registers every probe as a test, grouped by egress item. */
+export declare function defineLeakSuite(test: AnyTest, host: ConformanceHost, options?: LeakSuiteOptions): void;