@botiverse/porthole 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/README.md +83 -0
  2. package/dist/cli.d.ts +6 -0
  3. package/dist/cli.js +51 -0
  4. package/dist/conformance/entry.d.ts +19 -7
  5. package/dist/conformance/entry.js +39 -12
  6. package/dist/conformance/harness.js +8 -8
  7. package/dist/conformance/host-kit.d.ts +48 -13
  8. package/dist/conformance/host-kit.js +140 -28
  9. package/dist/conformance/index.d.ts +1 -1
  10. package/dist/conformance/index.js +1 -1
  11. package/dist/conformance/limits.js +15 -2
  12. package/dist/conformance/page.d.ts +6 -0
  13. package/dist/conformance/page.js +8 -0
  14. package/dist/conformance/served.d.ts +4 -4
  15. package/dist/conformance/served.js +26 -16
  16. package/dist/host/types.d.ts +6 -3
  17. package/dist/isolation/served.js +13 -2
  18. package/dist/node/index.d.ts +11 -3
  19. package/dist/node/index.js +70 -10
  20. package/dist/react/frame.d.ts +5 -2
  21. package/dist/server/host.d.ts +42 -8
  22. package/dist/server/host.js +35 -5
  23. package/dist/server/index.d.ts +4 -1
  24. package/dist/server/index.js +2 -0
  25. package/dist/server/pages.js +15 -1
  26. package/dist/server/proxy.js +2 -0
  27. package/dist/server/server.js +9 -2
  28. package/dist/server/types.d.ts +15 -6
  29. package/docs/ARCHITECTURE.md +277 -0
  30. package/docs/DECISIONS.md +1811 -0
  31. package/docs/DESIGN.md +1074 -0
  32. package/docs/OBJECTIVES.md +116 -0
  33. package/docs/PRINCIPLES.md +155 -0
  34. package/examples/app.mjs +234 -0
  35. package/examples/conformance/playwright.config.mjs +28 -0
  36. package/examples/conformance/porthole.spec.mjs +36 -0
  37. package/examples/node/server.mjs +75 -0
  38. package/examples/workers/migrations/0001_porthole_tickets.sql +2 -0
  39. package/examples/workers/worker.mjs +33 -0
  40. package/examples/workers/wrangler.jsonc +19 -0
  41. package/package.json +9 -3
  42. package/src/cli.ts +54 -0
  43. package/src/conformance/entry.ts +70 -19
  44. package/src/conformance/host-kit.ts +194 -45
  45. package/src/conformance/index.ts +4 -0
  46. package/src/conformance/limits.ts +21 -4
  47. package/src/conformance/page.ts +8 -0
  48. package/src/conformance/served.ts +34 -21
  49. package/src/host/types.ts +6 -3
  50. package/src/isolation/served.ts +12 -2
  51. package/src/node/index.ts +73 -10
  52. package/src/react/frame.tsx +5 -2
  53. package/src/server/host.ts +84 -14
  54. package/src/server/index.ts +6 -0
  55. package/src/server/pages.ts +15 -1
  56. package/src/server/proxy.ts +2 -0
  57. package/src/server/server.ts +11 -2
  58. package/src/server/types.ts +18 -7
package/README.md ADDED
@@ -0,0 +1,83 @@
1
+ # Porthole
2
+
3
+ `@botiverse/porthole`: show HTML an agent wrote (a widget, a whole page, an MCP Apps view)
4
+ inside your app, safely. One config gives the frame its isolation, its CSP, a themed shell, the
5
+ host functions it may call (each behind a gate), and the manual your agent reads.
6
+
7
+ ```bash
8
+ npm install @botiverse/porthole
9
+ ```
10
+
11
+ Node 24 or later, or Cloudflare Workers. The browser part is plain ES modules with no
12
+ dependencies (bundle it, or serve `dist/`).
13
+
14
+ ## Two ways to show content
15
+
16
+ - **Opaque, in the page.** No server needed: content runs in a sandboxed frame with an opaque
17
+ origin. For widgets in a conversation.
18
+ - **Served, on an origin of its own.** Each page, or each conversation's widgets, gets an origin
19
+ like `a-<id>.example-usercontent.com`, so it can keep storage, open at a clean address in a
20
+ new tab, and be framed by your app only. The host kit (`createContentHost`) is the server side;
21
+ your app writes only its policy: which pages exist and who may see them.
22
+
23
+ ## Try it in two minutes
24
+
25
+ The package ships a whole app, the same code on Node and on Workers:
26
+
27
+ ```bash
28
+ PORTHOLE_SECRET=$(npx porthole secret) node node_modules/@botiverse/porthole/examples/node/server.mjs
29
+ # open http://localhost:8790: a stored page, served on http://a-hello.content.localhost:8790
30
+ ```
31
+
32
+ - `examples/app.mjs`: the app (policy, routes, page), runtime-agnostic.
33
+ - `examples/node/server.mjs`, `examples/workers/` (with its D1 migration and `wrangler.jsonc`).
34
+ - `examples/conformance/`: Porthole's conformance suite run against it, on three engines.
35
+
36
+ ## The smallest opaque display
37
+
38
+ ```js
39
+ import { createHost, presets } from "@botiverse/porthole";
40
+
41
+ const host = createHost(presets.inlineWidget());
42
+ const display = host.mount(document.getElementById("widget"), {
43
+ displayId: "w1",
44
+ title: "A chart",
45
+ scheme: "light",
46
+ });
47
+ display.setContent("<p>Hello from an agent</p>");
48
+ ```
49
+
50
+ In React: `<PortholeProvider>` around `<PortholeFrame config displayId title scheme content />` from
51
+ `@botiverse/porthole/react`.
52
+
53
+ ## What the agent reads
54
+
55
+ ```js
56
+ import { compile } from "@botiverse/porthole";
57
+
58
+ const compiled = compile(config);
59
+ compiled.toolDescription(); // the show tool's description: what it may write, and where it runs
60
+ compiled.guide(); // the manual: the sandbox's limits, sizes, colors, examples
61
+ ```
62
+
63
+ ## Read next
64
+
65
+ - [docs/ADOPTING.md](docs/ADOPTING.md): getting started, step by step: the server, the page, its
66
+ CSP, Workers, local development, the agent's tools, conformance, troubleshooting.
67
+ - [docs/DESIGN.md](docs/DESIGN.md): how it works. [docs/DECISIONS.md](docs/DECISIONS.md): why,
68
+ by P-number (the code cites them).
69
+
70
+ ## Subpaths
71
+
72
+ | Import | What |
73
+ | --- | --- |
74
+ | `@botiverse/porthole` | `createHost`, `presets`, `compile`, `httpLocator`, `servedOrOpaque` (browser and server) |
75
+ | `@botiverse/porthole/react` | `PortholeProvider`, `PortholeFrame` |
76
+ | `@botiverse/porthole/server` | `createContentHost`, `prefixedName`, `d1TicketStore` (any runtime) |
77
+ | `@botiverse/porthole/node` | `nodeHost`, `nodeProbe` (Node's http server) |
78
+ | `@botiverse/porthole/mcp` | the MCP Apps adapter |
79
+ | `@botiverse/porthole/conformance` | `defineHostConformance`: the suite, against your app (Playwright) |
80
+
81
+ `npx porthole secret` makes a secret; `npx porthole d1-schema` prints the D1 migration.
82
+
83
+ Apache-2.0.
package/dist/cli.d.ts ADDED
@@ -0,0 +1,6 @@
1
+ #!/usr/bin/env node
2
+ /** Runs one command; returns what to print and the exit code. */
3
+ export declare function run(args: readonly string[]): {
4
+ readonly out: string;
5
+ readonly code: number;
6
+ };
package/dist/cli.js ADDED
@@ -0,0 +1,51 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * `npx porthole <command>`: the setup steps an adopter would otherwise script (P071).
4
+ *
5
+ * porthole secret a new PORTHOLE_SECRET (32 random bytes, base64url)
6
+ * porthole d1-schema [table] the D1 ticket table's SQL, for a migration file
7
+ * (npx porthole d1-schema > migrations/0001_porthole_tickets.sql)
8
+ */
9
+ import { d1TicketSchema } from "./server/tickets.js";
10
+ const USAGE = `Usage: porthole <command>
11
+
12
+ secret Print a new PORTHOLE_SECRET: 32 random bytes, base64url.
13
+ wrangler secret put PORTHOLE_SECRET, or your platform's secret store.
14
+ d1-schema [table] Print the D1 ticket table's SQL (default table porthole_tickets):
15
+ npx porthole d1-schema > migrations/0001_porthole_tickets.sql
16
+ `;
17
+ function base64url(bytes) {
18
+ let text = "";
19
+ for (const byte of bytes) {
20
+ text += String.fromCharCode(byte);
21
+ }
22
+ return btoa(text).replace(/\+/gu, "-").replace(/\//gu, "_").replace(/=+$/u, "");
23
+ }
24
+ /** Runs one command; returns what to print and the exit code. */
25
+ export function run(args) {
26
+ const [command, ...rest] = args;
27
+ try {
28
+ switch (command) {
29
+ case "secret":
30
+ return { out: `${base64url(crypto.getRandomValues(new Uint8Array(32)))}\n`, code: 0 };
31
+ case "d1-schema":
32
+ return { out: `${d1TicketSchema(rest[0])}\n`, code: 0 };
33
+ case undefined:
34
+ case "help":
35
+ case "--help":
36
+ case "-h":
37
+ return { out: USAGE, code: command === undefined ? 1 : 0 };
38
+ default:
39
+ return { out: `Unknown command ${JSON.stringify(command)}.\n\n${USAGE}`, code: 1 };
40
+ }
41
+ }
42
+ catch (error) {
43
+ return { out: `${error instanceof Error ? error.message : String(error)}\n`, code: 1 };
44
+ }
45
+ }
46
+ // Run as a program (`porthole …`), not when imported (its test).
47
+ if (import.meta.main) {
48
+ const { out, code } = run(process.argv.slice(2));
49
+ (code === 0 ? process.stdout : process.stderr).write(out);
50
+ process.exitCode = code;
51
+ }
@@ -15,13 +15,25 @@ export interface EntryConformanceHost {
15
15
  * The clean address of a stored page the signed-in viewer may open (`ContentHost.urlOf`), for
16
16
  * `scope`: it draws `<main id="artifact">version 1</main>`.
17
17
  */
18
- url(scope: string): string;
19
- /** A clean address the signed-in viewer may not open. */
20
- denied(scope: string): string;
21
- /** Whether `page` shows the app's own sign-in. */
22
- atSignIn(page: Page): Promise<boolean>;
23
- /** On the app's sign-in page: signs in, as a person does (and the app goes back). */
24
- completeSignIn(page: Page): Promise<void>;
18
+ url(scope: string): string | Promise<string>;
19
+ /** A clean address the signed-in viewer may not open. Absent: `served.entry.denied` is skipped. */
20
+ denied?(scope: string): string | Promise<string>;
21
+ /**
22
+ * Addresses on the content domain that name nothing (a label the app never assigns, the bare
23
+ * domain, a path no instance has): each must be Porthole's 404 there, never the app's sign-in
24
+ * (P070). Absent: the case is skipped.
25
+ */
26
+ unknown?(): readonly string[] | Promise<readonly string[]>;
27
+ /**
28
+ * Whether `page` shows the app's own sign-in. Absent: the browser left the content origin for
29
+ * another (the app's) and shows no content.
30
+ */
31
+ atSignIn?(page: Page): Promise<boolean>;
32
+ /**
33
+ * On the app's sign-in page: signs in, as a person does (and the app goes back). Absent: the
34
+ * signed-out case stops at the sign-in.
35
+ */
36
+ completeSignIn?(page: Page): Promise<void>;
25
37
  /**
26
38
  * Frames a clean address on the app's page as the app would (a location of that address),
27
39
  * returning the frame and the display's outcome once it has one.
@@ -31,7 +31,7 @@ export function entryTests(host, options = {}) {
31
31
  };
32
32
  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 }) => {
33
33
  await host.signIn(page);
34
- const url = host.url("entry-direct");
34
+ const url = await host.url("entry-direct");
35
35
  await page.goto(url);
36
36
  await expect(page.locator("#artifact")).toHaveText("version 1");
37
37
  expect(page.url(), "the address bar shows the clean address, no code").toBe(url);
@@ -45,26 +45,52 @@ export function entryTests(host, options = {}) {
45
45
  await expect(page.locator("#artifact")).toHaveText("version 1");
46
46
  expect(entries, "a reload needs no entry").toEqual([]);
47
47
  });
48
- 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 }) => {
49
- const url = host.url("entry-signed-out");
48
+ 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 }, info) => {
49
+ const url = await host.url("entry-signed-out");
50
50
  await page.goto(url);
51
- expect(await host.atSignIn(page), "the app's sign-in").toBe(true);
51
+ const atSignIn = host.atSignIn === undefined
52
+ ? new URL(page.url()).origin !== new URL(url).origin
53
+ : await host.atSignIn(page);
54
+ expect(atSignIn, `the app's sign-in (ended at ${page.url()})`).toBe(true);
52
55
  expect(await shows(page)).toBe(false);
56
+ if (host.completeSignIn === undefined) {
57
+ info.annotations.push({
58
+ type: "note",
59
+ description: "the sign-in wasn't completed: entry.completeSignIn not given",
60
+ });
61
+ return;
62
+ }
53
63
  await host.completeSignIn(page);
54
64
  await expect(page.locator("#artifact")).toHaveText("version 1");
55
65
  expect(page.url()).toBe(url);
56
66
  });
57
- define("served.entry.denied", "a viewer without access gets the app's refusal, never the content", async ({ page }) => {
67
+ define("served.entry.denied", "a viewer without access gets the app's refusal, never the content", async ({ page }, info) => {
68
+ info.skip(host.denied === undefined, "the host gave no address its viewer may not open (denied)");
58
69
  await host.signIn(page);
59
- const url = host.denied("entry-denied");
70
+ const url = (await host.denied?.("entry-denied")) ?? "";
60
71
  const answer = await page.goto(url);
61
72
  expect(answer?.status()).toBe(403);
62
73
  expect(await shows(page)).toBe(false);
63
74
  expect(new URL(page.url()).origin, "the refusal is the app's").not.toBe(new URL(url).origin);
64
75
  });
76
+ define("served.entry.unknown", "an address that names nothing is a 404 on the content domain: never a trip to the app's sign-in", async ({ page }, info) => {
77
+ info.skip(host.unknown === undefined, "the host gave no addresses that name nothing (unknown)");
78
+ const request = page.context().request;
79
+ for (const url of (await host.unknown?.()) ?? []) {
80
+ const answer = await request.get(url, {
81
+ maxRedirects: 0,
82
+ headers: { "sec-fetch-dest": "document" },
83
+ });
84
+ expect(answer.status(), url).toBe(404);
85
+ expect(answer.headers().location, url).toBeUndefined();
86
+ const opened = await page.goto(url);
87
+ expect(opened?.status(), url).toBe(404);
88
+ expect(new URL(page.url()).origin, url).toBe(new URL(url).origin);
89
+ }
90
+ });
65
91
  define("served.entry.code-once", "an entry code works once: replayed, it opens nothing", async ({ page }) => {
66
92
  await host.signIn(page);
67
- const code = await codeFor(page, host.url("entry-once"));
93
+ const code = await codeFor(page, await host.url("entry-once"));
68
94
  const request = page.context().request;
69
95
  const top = { "sec-fetch-dest": "document" };
70
96
  const first = await request.get(code, { maxRedirects: 0, headers: top });
@@ -75,8 +101,8 @@ export function entryTests(host, options = {}) {
75
101
  });
76
102
  define("served.entry.code-elsewhere", "an entry code taken to another instance's origin opens nothing there", async ({ page }) => {
77
103
  await host.signIn(page);
78
- const code = new URL(await codeFor(page, host.url("entry-mine")));
79
- const other = new URL(host.url("entry-theirs"));
104
+ const code = new URL(await codeFor(page, await host.url("entry-mine")));
105
+ const other = new URL(await host.url("entry-theirs"));
80
106
  const request = page.context().request;
81
107
  const answer = await request.get(`${other.origin}${code.pathname}${code.search}`, {
82
108
  maxRedirects: 0,
@@ -87,10 +113,11 @@ export function entryTests(host, options = {}) {
87
113
  });
88
114
  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) => {
89
115
  await host.signIn(page);
90
- const shown = await host.frame(page, host.url("entry-framed"));
116
+ const before = page.url();
117
+ const shown = await host.frame(page, await host.url("entry-framed"));
91
118
  const outcome = await shown.outcome();
92
119
  const frame = await shown.frame();
93
- expect(await host.atSignIn(page)).toBe(false);
120
+ expect(page.url(), "the app's page stays where it was").toBe(before);
94
121
  expect(new URL(frame.url()).pathname).not.toMatch(/sign-?in/iu);
95
122
  if (outcome.state === "loaded") {
96
123
  await expect(frame.locator("#artifact")).toHaveText("version 1");
@@ -110,7 +137,7 @@ export function entryTests(host, options = {}) {
110
137
  await host.signIn(page);
111
138
  // The app's page stays; the browser forgets every sign-in.
112
139
  await page.context().clearCookies();
113
- const shown = await host.frame(page, host.url("entry-framed-out"));
140
+ const shown = await host.frame(page, await host.url("entry-framed-out"));
114
141
  expect(await shown.outcome()).toMatchObject({ state: "blocked", reason: "sign-in" });
115
142
  const frame = await shown.frame();
116
143
  await expect(frame.locator("h1")).toHaveText("Open this in a new tab to sign in");