@botiverse/porthole 0.14.17 → 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.
@@ -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`).
@@ -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
- const framed = window.parent !== window;
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
- const framed = parentWindow !== window;
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).
@@ -1,5 +1,10 @@
1
1
  import { PAGE_SANDBOX_TOKENS } from "../compile/policy.ts";
2
- import { framedByProblem, hostOriginProblem, onNestedLabel } from "../isolation/served.ts";
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
- export const FRAME_SHELL_RUNTIME = String.raw`(() => {
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). Where
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.includes(origin)) {
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
- return FRAME_SHELL_RUNTIME.replace("__PLAN__", () =>
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
- ...((options.framedBy ?? []).length === 0 ? {} : { strictParent: true }),
345
+ ...(strict ? { strictParent: true } : {}),
327
346
  page: page.href,
328
347
  sandbox: PAGE_SANDBOX_TOKENS.join(" "),
329
348
  ...(options.title === undefined ? {} : { title: options.title }),
@@ -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) there is no host to ask: `none()`
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.
@@ -323,10 +328,11 @@ export const SHELL_RUNTIME = String.raw`(() => {
323
328
  // A page of a set that a navigation opened (not its ticket's answer) says so as it arrives
324
329
  // (P098), below, once the shell can speak: the notice its last page sent as it left can reach
325
330
  // the host after this page's load, or never (Chromium forwards a cross-process message from a
326
- // task of the sending document's, which a navigation that commits first drops).
327
- let arrived = false;
331
+ // task of the sending document's, which a navigation that commits first drops). With or without
332
+ // the Navigation API (P142): where there is none, the leaving page sends nothing, and this is the
333
+ // page's only word.
334
+ const arrived = filesBase !== null && typeof plan.files.address !== "string";
328
335
  if (navigationApi && typeof navigationApi.addEventListener === "function" && destinationOf !== null && sameDocumentOf !== null && navigationTypeOf !== null) {
329
- arrived = filesBase !== null && typeof plan.files.address !== "string";
330
336
  navigationApi.addEventListener("navigate", (event) => {
331
337
  const destination = applyOf(destinationOf, event, []);
332
338
  if (!applyOf(sameDocumentOf, destination, []) && applyOf(navigationTypeOf, event, []) !== "reload") {
@@ -1603,9 +1609,9 @@ export const SHELL_RUNTIME = String.raw`(() => {
1603
1609
  send({ method: "notifications/message", params: { level: "error", logger: "porthole", data: ownAddresses(message).slice(0, 2000) } });
1604
1610
  };
1605
1611
  // Nothing secret is ever said from here, so any parent may hear it; what it hears is the
1606
- // 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).
1607
1613
  const post = (message) => {
1608
- if (window.parent !== window) {
1614
+ if (window.parent !== window && !hostless) {
1609
1615
  window.parent.postMessage(Object.assign({ jsonrpc: "2.0" }, message), "*");
1610
1616
  }
1611
1617
  };
@@ -1637,6 +1643,15 @@ export const SHELL_RUNTIME = String.raw`(() => {
1637
1643
  if (arrived) {
1638
1644
  notice(location.href, { arrived: true });
1639
1645
  }
1646
+ // A navigation within the document (a fragment, history between its entries) says the page
1647
+ // stayed (P142): WebKit fires the frame's load for one (measured, 18.2 and 26.6: a link to
1648
+ // #bottom, the first in a document), which the host would otherwise take for content that left.
1649
+ // Listened for now, before any content runs; each is the content's word, as every notice is.
1650
+ if (filesSet !== null && filesBase !== null) {
1651
+ const stayed = () => notice(location.href, { same: true });
1652
+ window.addEventListener("popstate", stayed, true);
1653
+ window.addEventListener("hashchange", stayed, true);
1654
+ }
1640
1655
  // A sealed files' address opens the page's files on its own for a while (P083): renewed before
1641
1656
  // it ends, the page moved to the new one in place (the same page, the same history entry). Its
1642
1657
  // modules keep the address they loaded from; the server serves their own loads till the session
@@ -2274,7 +2289,8 @@ export const SHELL_RUNTIME = String.raw`(() => {
2274
2289
 
2275
2290
  // The handshake (HANDSHAKE, P085): asked until answered, since the host may start listening
2276
2291
  // after this runs; on a tab of its own, not asked at all (P139): its parent is itself, so no host
2277
- // hears it, and the runtime has nothing to offer from the start. How it ended goes on the
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
2278
2294
  // document's root element (data-porthole-host: "answered", or "none" where no host answered), for
2279
2295
  // a test, a person or a tool that shoots the page to see (P139): not on the shell's own script,
2280
2296
  // which a whole document's render takes out with the body it replaces, while the root stays (the
@@ -2288,7 +2304,7 @@ export const SHELL_RUNTIME = String.raw`(() => {
2288
2304
  };
2289
2305
  const handshake = ${HANDSHAKE};
2290
2306
  handshake(
2291
- window.top === window,
2307
+ window.top === window || hostless,
2292
2308
  () =>
2293
2309
  request("ui/initialize", {
2294
2310
  protocolVersion: plan.protocolVersion,