@botiverse/porthole 0.1.7 → 0.2.0

package/src/conformance/entry.ts

@@ -0,0 +1,206 @@
+import { expect, type Frame, type Page, type TestInfo } 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>>;
+}
+
+type Fixtures = { page: Page; browserName: string };
+
+/** Whether a page shows the stored page's own content. */
+const shows = async (where: Page | Frame): Promise<boolean> =>
+  (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: Page, url: string): Promise<string> {
+  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: EntryConformanceHost,
+  options: EntrySuiteOptions = {},
+): ConformanceTest[] {
+  const tests: ConformanceTest[] = [];
+  const define = (
+    id: string,
+    title: string,
+    body: (fixtures: Fixtures, info: TestInfo) => Promise<void>,
+  ) => {
+    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: string[] = [];
+      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 as { readonly reason: string }).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/src/conformance/harness/page.ts

@@ -0,0 +1,267 @@
+import type { CapabilityHandlers, ConfirmRequest } from "../../bridge/types.ts";
+import type { PortholeConfig } from "../../config/schema.ts";
+import { createHost } from "../../host/create-host.ts";
+import { httpLocator } from "../../host/locator.ts";
+import type { DisplayEvents, DisplayHandle } from "../../host/types.ts";
+import type { FrameLocation, InstanceLocator, InstanceRef } from "../../isolation/types.ts";
+import type { LaunchSpec, RecordedCall, RecordedEvent } from "../index.ts";
+
+/**
+ * The conformance harness (P066), injected into an app's real page under its nonce: framework-
+ * free, on the core's own mount (`createHost`), it shows each display the suite asks for (an
+ * opaque one with the suite's content; a served one located by the app's issue endpoint),
+ * records what reaches its handlers and holds each confirmation until the test answers it. Built
+ * into one script (`dist/conformance/harness.js`); `defineHostConformance` injects it.
+ */
+
+interface Shown {
+  readonly handle: DisplayHandle;
+  readonly calls: RecordedCall[];
+  readonly events: RecordedEvent[];
+  readonly confirmations: { request: ConfirmRequest; resolve: (accepted: boolean) => void }[];
+  readonly received: unknown[];
+  origin: string | null;
+  /** Why the instance couldn't be located (the issue endpoint's refusal). */
+  failure: string | null;
+  frame: HTMLIFrameElement | null;
+}
+
+const EVENTS: readonly (keyof DisplayEvents)[] = [
+  "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<number, Shown>();
+let next = 0;
+const pause = (ms: number) => 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(): HTMLElement {
+  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: number, widthPx: number, heightPx?: number): HTMLElement {
+  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: RecordedCall[]): CapabilityHandlers {
+  const record =
+    <T>(capability: RecordedCall["capability"], value: T) =>
+    (args: unknown): T => {
+      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: number, shown: Shown): void {
+  for (const type of EVENTS) {
+    shown.handle.on(type, (detail) => shown.events.push({ type, detail } as RecordedEvent));
+  }
+  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: LaunchSpec): Promise<number> {
+    const id = next;
+    next += 1;
+    const container = box(id, spec.widthPx ?? 600, spec.heightPx);
+    const calls: RecordedCall[] = [];
+    const confirmations: Shown["confirmations"] = [];
+    const host = createHost(spec.config, {
+      handlers: recorder(calls),
+      ...(spec.confirms === false
+        ? {}
+        : {
+            confirm: (request: ConfirmRequest) =>
+              new Promise<boolean>((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: Shown = {
+      handle,
+      calls,
+      events: [],
+      confirmations,
+      received: [],
+      origin: null,
+      failure: null,
+      frame: null,
+    };
+    const initialized = new Promise<void>((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: PortholeConfig,
+    instance: InstanceRef,
+    where:
+      | { readonly issue: string; readonly headers?: Readonly<Record<string, string>> }
+      | { readonly location: FrameLocation },
+    content?: string,
+  ): number {
+    const id = next;
+    next += 1;
+    const container = box(id, 600, 400);
+    const calls: RecordedCall[] = [];
+    const shown: Shown = {
+      handle: null as unknown as DisplayHandle,
+      calls,
+      events: [],
+      confirmations: [],
+      received: [],
+      origin: null,
+      failure: null,
+      frame: null,
+    };
+    const asked: InstanceLocator =
+      "issue" in where
+        ? httpLocator(where.issue, where.headers === undefined ? {} : { headers: where.headers })
+        : { locate: () => Promise.resolve(where.location) };
+    const locator: InstanceLocator = {
+      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 as { handle: DisplayHandle }).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: number) => displays.get(id)?.origin ?? null,
+  failure: (id: number) => displays.get(id)?.failure ?? null,
+  received: (id: number) => displays.get(id)?.received ?? [],
+  post(id: number, message: unknown) {
+    const shown = displays.get(id);
+    if (shown?.frame?.contentWindow && shown.origin !== null) {
+      shown.frame.contentWindow.postMessage(message, shown.origin);
+    }
+  },
+  setContent(id: number, html: string, partial: boolean) {
+    displays.get(id)?.handle.setContent(html, { partial });
+  },
+  calls: (id: number) => displays.get(id)?.calls ?? [],
+  events: (id: number) => displays.get(id)?.events ?? [],
+  errors: (id: number) =>
+    (displays.get(id)?.events ?? []).flatMap((event) =>
+      event.type === "error" ? [event.detail.message] : [],
+    ),
+  pendingConfirmations: (id: number) => displays.get(id)?.confirmations.length ?? 0,
+  answer(id: number, accept: boolean): ConfirmRequest | null {
+    const waiting = displays.get(id)?.confirmations.shift();
+    if (waiting === undefined) {
+      return null;
+    }
+    waiting.resolve(accept);
+    return waiting.request;
+  },
+  setTheme: (id: number, scheme: "light" | "dark") => displays.get(id)?.handle.setTheme(scheme),
+  destroy(id: number) {
+    displays.get(id)?.handle.destroy();
+    document.getElementById(`porthole-display-${id}`)?.remove();
+    displays.delete(id);
+  },
+};
+
+export type ConformanceHarness = typeof harness;
+
+(window as unknown as { portholeConformance: ConformanceHarness }).portholeConformance = harness;
+document.documentElement.dataset.portholeConformance = "ready";