@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.
- package/README.md +83 -0
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +51 -0
- package/dist/conformance/entry.d.ts +19 -7
- package/dist/conformance/entry.js +39 -12
- package/dist/conformance/harness.js +8 -8
- package/dist/conformance/host-kit.d.ts +48 -13
- package/dist/conformance/host-kit.js +140 -28
- package/dist/conformance/index.d.ts +1 -1
- package/dist/conformance/index.js +1 -1
- package/dist/conformance/limits.js +15 -2
- package/dist/conformance/page.d.ts +6 -0
- package/dist/conformance/page.js +8 -0
- package/dist/conformance/served.d.ts +4 -4
- package/dist/conformance/served.js +26 -16
- package/dist/host/types.d.ts +6 -3
- package/dist/isolation/served.js +13 -2
- package/dist/node/index.d.ts +11 -3
- package/dist/node/index.js +70 -10
- package/dist/react/frame.d.ts +5 -2
- package/dist/server/host.d.ts +42 -8
- package/dist/server/host.js +35 -5
- package/dist/server/index.d.ts +4 -1
- package/dist/server/index.js +2 -0
- package/dist/server/pages.js +15 -1
- package/dist/server/proxy.js +2 -0
- package/dist/server/server.js +9 -2
- package/dist/server/types.d.ts +15 -6
- package/docs/ARCHITECTURE.md +277 -0
- package/docs/DECISIONS.md +1811 -0
- package/docs/DESIGN.md +1074 -0
- package/docs/OBJECTIVES.md +116 -0
- package/docs/PRINCIPLES.md +155 -0
- package/examples/app.mjs +234 -0
- package/examples/conformance/playwright.config.mjs +28 -0
- package/examples/conformance/porthole.spec.mjs +36 -0
- package/examples/node/server.mjs +75 -0
- package/examples/workers/migrations/0001_porthole_tickets.sql +2 -0
- package/examples/workers/worker.mjs +33 -0
- package/examples/workers/wrangler.jsonc +19 -0
- package/package.json +9 -3
- package/src/cli.ts +54 -0
- package/src/conformance/entry.ts +70 -19
- package/src/conformance/host-kit.ts +194 -45
- package/src/conformance/index.ts +4 -0
- package/src/conformance/limits.ts +21 -4
- package/src/conformance/page.ts +8 -0
- package/src/conformance/served.ts +34 -21
- package/src/host/types.ts +6 -3
- package/src/isolation/served.ts +12 -2
- package/src/node/index.ts +73 -10
- package/src/react/frame.tsx +5 -2
- package/src/server/host.ts +84 -14
- package/src/server/index.ts +6 -0
- package/src/server/pages.ts +15 -1
- package/src/server/proxy.ts +2 -0
- package/src/server/server.ts +11 -2
- 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
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
|
-
/**
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
-
|
|
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
|
|
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(
|
|
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");
|