@botiverse/porthole 0.14.18 → 0.15.0
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/CHANGELOG.md +45 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/isolation/served.d.ts +9 -0
- package/dist/isolation/served.js +23 -0
- package/dist/server/host.d.ts +7 -0
- package/dist/server/host.js +1 -0
- package/dist/server/pages.d.ts +39 -12
- package/dist/server/pages.js +85 -37
- package/dist/server/server.js +168 -40
- package/dist/server/types.d.ts +30 -0
- package/dist/shell/annotate.js +3 -2
- package/dist/shell/find.js +2 -1
- package/dist/shell/frame.d.ts +3 -34
- package/dist/shell/frame.js +26 -14
- package/dist/shell/runtime.d.ts +3 -2
- package/dist/shell/runtime.js +12 -6
- package/docs/ADOPTING.md +18 -4
- package/docs/DECISIONS.md +191 -2
- package/docs/DESIGN.md +4 -0
- package/docs/THREAT_MODEL.md +35 -2
- package/package.json +1 -1
- package/src/isolation/served.ts +25 -0
- package/src/server/host.ts +8 -0
- package/src/server/pages.ts +129 -56
- package/src/server/server.ts +237 -40
- package/src/server/types.ts +30 -0
- package/src/shell/annotate.ts +3 -2
- package/src/shell/find.ts +2 -1
- package/src/shell/frame.ts +33 -14
- package/src/shell/runtime.ts +12 -6
package/src/server/types.ts
CHANGED
|
@@ -77,6 +77,17 @@ export type Grant = (
|
|
|
77
77
|
* gives an id per artifact, so pages can't link a person across artifacts. Only with `level`.
|
|
78
78
|
*/
|
|
79
79
|
readonly user?: { readonly id: string; readonly name?: string };
|
|
80
|
+
/**
|
|
81
|
+
* An embedded document (P143): a public page that any site may frame, with no host. Only where
|
|
82
|
+
* the server opted in (`ServerOptions.embeds`), only with `anonymous: true` and no `level` or
|
|
83
|
+
* `user`, and only for an artifact's page that isn't nested (never a url-mode app, a served shell,
|
|
84
|
+
* the sandbox proxy or a nested display); anything else throws at `issue`. Carried signed in the
|
|
85
|
+
* session (and in a frame's sealed files' address), so it is never added to a session or taken
|
|
86
|
+
* from one. Every answer of such a session says `frame-ancestors *` (no other session's changes),
|
|
87
|
+
* its shell's plan names no host (it asks no host, hears none and tells no parent anything; the
|
|
88
|
+
* bridge never runs), and `issue` mints no door.
|
|
89
|
+
*/
|
|
90
|
+
readonly embed?: true;
|
|
80
91
|
};
|
|
81
92
|
|
|
82
93
|
export interface TicketRecord {
|
|
@@ -113,6 +124,8 @@ export interface TicketRecord {
|
|
|
113
124
|
* content's address; the door takes no other.
|
|
114
125
|
*/
|
|
115
126
|
readonly door?: true;
|
|
127
|
+
/** An embed grant's (P143): the session it buys is an embed session. */
|
|
128
|
+
readonly embed?: true;
|
|
116
129
|
}
|
|
117
130
|
|
|
118
131
|
/** Where tickets live between `issue` and their one use. Default: in memory (one process). */
|
|
@@ -224,6 +237,11 @@ export interface Access {
|
|
|
224
237
|
readonly origin: string;
|
|
225
238
|
/** When the cookie stops being good, epoch milliseconds. */
|
|
226
239
|
readonly expiresAt: number;
|
|
240
|
+
/**
|
|
241
|
+
* An embed session's (P143, `Grant.embed`): its answers may be framed by any page, and its
|
|
242
|
+
* documents name no host. Absent for every other session.
|
|
243
|
+
*/
|
|
244
|
+
readonly embed?: true;
|
|
227
245
|
}
|
|
228
246
|
|
|
229
247
|
/**
|
|
@@ -240,6 +258,11 @@ export interface AuthorizeRequest {
|
|
|
240
258
|
readonly viewer: string;
|
|
241
259
|
readonly anonymous: boolean;
|
|
242
260
|
readonly subject?: string;
|
|
261
|
+
/**
|
|
262
|
+
* Whether the session is an embed session (P143, `Grant.embed`): absent for every other, so a
|
|
263
|
+
* host's check can hold an embed subject to embed sessions alone.
|
|
264
|
+
*/
|
|
265
|
+
readonly embed?: true;
|
|
243
266
|
/** The request itself (its path, method; never its Porthole cookie's value). */
|
|
244
267
|
readonly request: Request;
|
|
245
268
|
}
|
|
@@ -281,6 +304,13 @@ export interface ServerOptions {
|
|
|
281
304
|
* (`http://` on loopback), none a host origin, none the content domain's site. Default none.
|
|
282
305
|
*/
|
|
283
306
|
readonly framedBy?: readonly string[];
|
|
307
|
+
/**
|
|
308
|
+
* Whether `issue` takes an embed grant (P143, `Grant.embed`): a public artifact page that any
|
|
309
|
+
* site may frame, with no host. Default false: an embed grant throws, and a session or sealed
|
|
310
|
+
* address that says it is one opens nothing. Only an embed session's answers say
|
|
311
|
+
* `frame-ancestors *`; every other answer is as without it, byte for byte.
|
|
312
|
+
*/
|
|
313
|
+
readonly embeds?: boolean;
|
|
284
314
|
/**
|
|
285
315
|
* The configs a served shell or page is served under, by the name a `ServedDocument` gives
|
|
286
316
|
* (an artifact defaults to `artifact`, the MCP Apps sandbox proxy to `mcpApp`).
|
package/src/shell/annotate.ts
CHANGED
|
@@ -161,8 +161,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
161
161
|
const getAttribute = Element.prototype.getAttribute;
|
|
162
162
|
const listenOn = EventTarget.prototype.addEventListener;
|
|
163
163
|
const post = window.parent.postMessage.bind(window.parent);
|
|
164
|
-
// Read once: content can replace window.parent (it is [Replaceable]), never what was read.
|
|
165
|
-
|
|
164
|
+
// Read once: content can replace window.parent (it is [Replaceable]), never what was read. A
|
|
165
|
+
// hostless plan (P143) tells no parent anything.
|
|
166
|
+
const framed = window.parent !== window && !hostless;
|
|
166
167
|
const tell = (method, params) => {
|
|
167
168
|
if (framed) {
|
|
168
169
|
post({ jsonrpc: "2.0", method, params }, "*");
|
package/src/shell/find.ts
CHANGED
|
@@ -261,7 +261,8 @@ export const FIND_RUNTIME = String.raw`if (declared("find")) {
|
|
|
261
261
|
const time = () => callOf(clock, Date, []);
|
|
262
262
|
// Read once: content can replace window.parent (it is [Replaceable]), never what was read.
|
|
263
263
|
const parentWindow = window.parent;
|
|
264
|
-
|
|
264
|
+
// A hostless plan (P143) tells no parent anything.
|
|
265
|
+
const framed = parentWindow !== window && !hostless;
|
|
265
266
|
const postIn = parentWindow.postMessage;
|
|
266
267
|
const post = (message) => callOf(postIn, parentWindow, [message, "*"]);
|
|
267
268
|
// Whose shortcut it is: Cmd on Apple's platforms, Ctrl elsewhere (read before content runs).
|
package/src/shell/frame.ts
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
import { PAGE_SANDBOX_TOKENS } from "../compile/policy.ts";
|
|
2
|
-
import {
|
|
2
|
+
import {
|
|
3
|
+
framedByProblem,
|
|
4
|
+
hostOriginProblem,
|
|
5
|
+
includesOrigin,
|
|
6
|
+
onNestedLabel,
|
|
7
|
+
} from "../isolation/served.ts";
|
|
3
8
|
|
|
4
9
|
/**
|
|
5
10
|
* Porthole's shell for a nested page (P111): the whole document at the address the host frames,
|
|
@@ -33,9 +38,12 @@ import { framedByProblem, hostOriginProblem, onNestedLabel } from "../isolation/
|
|
|
33
38
|
* the host's the window hears no focus event at all (Firefox). A later task's `frame.focus()`
|
|
34
39
|
* goes through on all of them, the frame blurred first as the failed one left it active.
|
|
35
40
|
*
|
|
36
|
-
* Plain ES2020, no imports and no build step, like the runtime. `__PLAN__` is its plan.
|
|
41
|
+
* Plain ES2020, no imports and no build step, like the runtime. `__PLAN__` is its plan. A shell
|
|
42
|
+
* whose parent may be an outer page (a host's `framedBy`, P141) runs the strict runtime, which
|
|
43
|
+
* checks that parent before it says `*`; every other shell runs 0.14.16's, byte for byte, so its
|
|
44
|
+
* hash is too (P144).
|
|
37
45
|
*/
|
|
38
|
-
|
|
46
|
+
const frameShellRuntime = (strict: boolean): string => String.raw`(() => {
|
|
39
47
|
"use strict";
|
|
40
48
|
const plan = __PLAN__;
|
|
41
49
|
const PREFIX = "porthole/shell/";
|
|
@@ -81,9 +89,7 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
|
|
|
81
89
|
const web = plan.origins.filter((origin) => origin.indexOf("https://") === 0 || origin.indexOf("http://") === 0);
|
|
82
90
|
// To the host: each web host origin (only the parent's is delivered); a desktop app's own scheme
|
|
83
91
|
// is no target a browser takes, so where one is listed and the parent isn't a known web origin,
|
|
84
|
-
// "*" (frame-ancestors holds the parent to the host origins; nothing said here is secret)
|
|
85
|
-
// it names an outer page above them too (the host's framedBy, P141: plan.strictParent), the parent
|
|
86
|
-
// may be the outer page: "*" then goes only to a parent the engine names as a host origin.
|
|
92
|
+
// "*" (frame-ancestors holds the parent to the host origins; nothing said here is secret).${strict ? STRICT_NOTE : ""}
|
|
87
93
|
const toHost = (message) => {
|
|
88
94
|
if (!framed) {
|
|
89
95
|
return;
|
|
@@ -94,11 +100,7 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
|
|
|
94
100
|
} catch (_) {}
|
|
95
101
|
}
|
|
96
102
|
const parent = location.ancestorOrigins && location.ancestorOrigins.length > 0 ? location.ancestorOrigins[0] : null;
|
|
97
|
-
if (
|
|
98
|
-
web.length < plan.origins.length &&
|
|
99
|
-
(parent === null || web.indexOf(parent) === -1) &&
|
|
100
|
-
(plan.strictParent !== true || (parent !== null && plan.origins.indexOf(parent) !== -1))
|
|
101
|
-
) {
|
|
103
|
+
if (${strict ? STRICT_CONDITION : "web.length < plan.origins.length && (parent === null || web.indexOf(parent) === -1)"}) {
|
|
102
104
|
try {
|
|
103
105
|
window.parent.postMessage(message, "*");
|
|
104
106
|
} catch (_) {}
|
|
@@ -265,6 +267,22 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
|
|
|
265
267
|
}
|
|
266
268
|
})();`;
|
|
267
269
|
|
|
270
|
+
/** What a strict shell says of its `*` (P141), after the default's note. */
|
|
271
|
+
const STRICT_NOTE = ` Where
|
|
272
|
+
// it names an outer page above them too (the host's framedBy, P141: plan.strictParent), the parent
|
|
273
|
+
// may be the outer page: "*" then goes only to a parent the engine names as a host origin.`;
|
|
274
|
+
/** When a strict shell says `*` (P141): as 0.14.16's, and only to a parent named as a host origin. */
|
|
275
|
+
const STRICT_CONDITION = `
|
|
276
|
+
web.length < plan.origins.length &&
|
|
277
|
+
(parent === null || web.indexOf(parent) === -1) &&
|
|
278
|
+
(plan.strictParent !== true || (parent !== null && plan.origins.indexOf(parent) !== -1))
|
|
279
|
+
`;
|
|
280
|
+
|
|
281
|
+
/** The nested page's shell's runtime: 0.14.16's, byte for byte. */
|
|
282
|
+
export const FRAME_SHELL_RUNTIME = frameShellRuntime(false);
|
|
283
|
+
/** A strict shell's runtime (P141): its parent may be an outer page. */
|
|
284
|
+
export const STRICT_FRAME_SHELL_RUNTIME = frameShellRuntime(true);
|
|
285
|
+
|
|
268
286
|
export { SHELL_METHOD_PREFIX, SHELL_STATE_METHOD } from "../isolation/types.ts";
|
|
269
287
|
|
|
270
288
|
export interface FrameShellOptions {
|
|
@@ -301,7 +319,7 @@ export function frameShellScript(options: FrameShellOptions): string {
|
|
|
301
319
|
}
|
|
302
320
|
for (const origin of options.framedBy ?? []) {
|
|
303
321
|
const problem = framedByProblem(origin);
|
|
304
|
-
if (problem !== null || options.origins
|
|
322
|
+
if (problem !== null || includesOrigin(options.origins, origin)) {
|
|
305
323
|
throw new TypeError(`frameShellScript: framedBy: ${problem ?? `${origin} is a host origin`}`);
|
|
306
324
|
}
|
|
307
325
|
}
|
|
@@ -320,10 +338,11 @@ export function frameShellScript(options: FrameShellOptions): string {
|
|
|
320
338
|
"frameShellScript: page is on a nested page's own label (porthole-<24 base32>, nestedLabelOf)",
|
|
321
339
|
);
|
|
322
340
|
}
|
|
323
|
-
|
|
341
|
+
const strict = (options.framedBy ?? []).length > 0;
|
|
342
|
+
return (strict ? STRICT_FRAME_SHELL_RUNTIME : FRAME_SHELL_RUNTIME).replace("__PLAN__", () =>
|
|
324
343
|
scriptJson({
|
|
325
344
|
origins: options.origins,
|
|
326
|
-
...(
|
|
345
|
+
...(strict ? { strictParent: true } : {}),
|
|
327
346
|
page: page.href,
|
|
328
347
|
sandbox: PAGE_SANDBOX_TOKENS.join(" "),
|
|
329
348
|
...(options.title === undefined ? {} : { title: options.title }),
|
package/src/shell/runtime.ts
CHANGED
|
@@ -93,9 +93,10 @@ export const ONCE = String.raw`(passesAsIs, toText) => (value) => {
|
|
|
93
93
|
}`;
|
|
94
94
|
|
|
95
95
|
/**
|
|
96
|
-
* The shell's handshake with its host (P085, P139), spliced into the runtime as
|
|
96
|
+
* The shell's handshake with its host (P085, P139, P143), spliced into the runtime as
|
|
97
97
|
* `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
|
|
98
|
-
* its own top, so its parent is itself and no host can hear it)
|
|
98
|
+
* its own top, so its parent is itself and no host can hear it), and under a plan that names no
|
|
99
|
+
* host (P143: the runtime passes `topLevel` true for it too), there is no host to ask: `none()`
|
|
99
100
|
* at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
|
|
100
101
|
* 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
|
|
101
102
|
* runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
|
|
@@ -171,6 +172,10 @@ export const HANDSHAKE = String.raw`(topLevel, ask, answered, none, later) => {
|
|
|
171
172
|
export const SHELL_RUNTIME = String.raw`(() => {
|
|
172
173
|
"use strict";
|
|
173
174
|
const plan = __PLAN__;
|
|
175
|
+
// A plan that names no host (P143: an embedded document, framed below a page that is no host):
|
|
176
|
+
// the shell asks no host and ends its handshake at once, as on a tab (P139), and says nothing to
|
|
177
|
+
// any parent, not even its own notices to "*" (P053). No origin is a host's, so it hears no one.
|
|
178
|
+
const hostless = Array.isArray(plan.origins) && plan.origins.length === 0;
|
|
174
179
|
// Every built-in a guard calls is called through callOf, which is Reflect.apply itself, kept
|
|
175
180
|
// now, before any content runs: a direct call of it never reads Function.prototype's call,
|
|
176
181
|
// apply or bind, so nothing content later puts there sees what the shell calls or with what.
|
|
@@ -1604,9 +1609,9 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
1604
1609
|
send({ method: "notifications/message", params: { level: "error", logger: "porthole", data: ownAddresses(message).slice(0, 2000) } });
|
|
1605
1610
|
};
|
|
1606
1611
|
// Nothing secret is ever said from here, so any parent may hear it; what it hears is the
|
|
1607
|
-
// content's word, which the host gates before it acts on it.
|
|
1612
|
+
// content's word, which the host gates before it acts on it. A hostless plan says nothing (P143).
|
|
1608
1613
|
const post = (message) => {
|
|
1609
|
-
if (window.parent !== window) {
|
|
1614
|
+
if (window.parent !== window && !hostless) {
|
|
1610
1615
|
window.parent.postMessage(Object.assign({ jsonrpc: "2.0" }, message), "*");
|
|
1611
1616
|
}
|
|
1612
1617
|
};
|
|
@@ -2284,7 +2289,8 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
2284
2289
|
|
|
2285
2290
|
// The handshake (HANDSHAKE, P085): asked until answered, since the host may start listening
|
|
2286
2291
|
// after this runs; on a tab of its own, not asked at all (P139): its parent is itself, so no host
|
|
2287
|
-
// hears it, and the runtime has nothing to offer from the start.
|
|
2292
|
+
// hears it, and the runtime has nothing to offer from the start. Nor under a plan that names no
|
|
2293
|
+
// host (P143): no parent is one. How it ended goes on the
|
|
2288
2294
|
// document's root element (data-porthole-host: "answered", or "none" where no host answered), for
|
|
2289
2295
|
// a test, a person or a tool that shoots the page to see (P139): not on the shell's own script,
|
|
2290
2296
|
// which a whole document's render takes out with the body it replaces, while the root stays (the
|
|
@@ -2298,7 +2304,7 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
2298
2304
|
};
|
|
2299
2305
|
const handshake = ${HANDSHAKE};
|
|
2300
2306
|
handshake(
|
|
2301
|
-
window.top === window,
|
|
2307
|
+
window.top === window || hostless,
|
|
2302
2308
|
() =>
|
|
2303
2309
|
request("ui/initialize", {
|
|
2304
2310
|
protocolVersion: plan.protocolVersion,
|