@botiverse/porthole 0.15.2 → 0.16.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.
Files changed (109) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/dist/bridge/bridge.d.ts +1 -8
  3. package/dist/bridge/bridge.js +0 -7
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/check/page.js +1 -1
  6. package/dist/compile/policy.d.ts +0 -7
  7. package/dist/compile/policy.js +1 -10
  8. package/dist/config/capabilities.d.ts +8 -14
  9. package/dist/config/capabilities.js +4 -5
  10. package/dist/config/schema.d.ts +2 -13
  11. package/dist/config/validate.js +0 -24
  12. package/dist/conformance/behavior.js +26 -37
  13. package/dist/conformance/clipboard.js +47 -1
  14. package/dist/conformance/harness-source.js +1 -1
  15. package/dist/displays/displays.js +1 -3
  16. package/dist/guide/limits.js +1 -1
  17. package/dist/guide/runtime.js +1 -1
  18. package/dist/host/create-host.d.ts +1 -1
  19. package/dist/host/create-host.js +6 -51
  20. package/dist/host/door.d.ts +1 -1
  21. package/dist/host/locate.d.ts +1 -1
  22. package/dist/host/locate.js +2 -2
  23. package/dist/host/outcome.d.ts +5 -12
  24. package/dist/host/outcome.js +8 -16
  25. package/dist/host/types.d.ts +6 -22
  26. package/dist/index.d.ts +2 -4
  27. package/dist/index.js +2 -4
  28. package/dist/isolation/served.d.ts +9 -14
  29. package/dist/isolation/served.js +17 -31
  30. package/dist/isolation/types.d.ts +2 -19
  31. package/dist/isolation/types.js +0 -17
  32. package/dist/platform/focus-field.d.ts +11 -0
  33. package/dist/platform/focus-field.js +18 -0
  34. package/dist/platform/types.d.ts +6 -22
  35. package/dist/platform/web.js +8 -98
  36. package/dist/presets/presets.d.ts +0 -2
  37. package/dist/presets/presets.js +0 -1
  38. package/dist/react/frame.d.ts +0 -8
  39. package/dist/react/frame.js +0 -4
  40. package/dist/runtime/contract.d.ts +2 -2
  41. package/dist/runtime/contract.js +2 -2
  42. package/dist/runtime/types.generated.js +6 -6
  43. package/dist/server/files.js +7 -23
  44. package/dist/server/host.d.ts +1 -1
  45. package/dist/server/index.d.ts +1 -1
  46. package/dist/server/index.js +4 -6
  47. package/dist/server/naming.js +1 -1
  48. package/dist/server/pages.d.ts +9 -2
  49. package/dist/server/pages.js +28 -8
  50. package/dist/server/server.js +28 -166
  51. package/dist/server/types.d.ts +7 -7
  52. package/dist/shell/plan.js +2 -2
  53. package/dist/shell/runtime.js +1 -9
  54. package/docs/ADOPTING.md +42 -135
  55. package/docs/ARCHITECTURE.md +0 -33
  56. package/docs/DECISIONS.md +296 -9
  57. package/docs/DESIGN.md +27 -50
  58. package/docs/THREAT_MODEL.md +140 -242
  59. package/package.json +1 -1
  60. package/src/bridge/bridge.ts +1 -17
  61. package/src/check/page.ts +1 -1
  62. package/src/compile/policy.ts +1 -11
  63. package/src/config/capabilities.ts +8 -14
  64. package/src/config/schema.ts +2 -13
  65. package/src/config/validate.ts +0 -28
  66. package/src/conformance/behavior.ts +50 -52
  67. package/src/conformance/clipboard.ts +56 -1
  68. package/src/displays/displays.ts +1 -3
  69. package/src/guide/limits.ts +1 -1
  70. package/src/guide/runtime.ts +1 -1
  71. package/src/host/create-host.ts +6 -52
  72. package/src/host/door.ts +1 -1
  73. package/src/host/locate.ts +2 -2
  74. package/src/host/outcome.ts +8 -21
  75. package/src/host/types.ts +6 -20
  76. package/src/index.ts +2 -4
  77. package/src/isolation/served.ts +18 -37
  78. package/src/isolation/types.ts +2 -24
  79. package/src/platform/focus-field.ts +18 -0
  80. package/src/platform/types.ts +6 -21
  81. package/src/platform/web.ts +8 -116
  82. package/src/presets/presets.ts +0 -3
  83. package/src/react/frame.tsx +0 -10
  84. package/src/runtime/contract.ts +4 -4
  85. package/src/runtime/types.generated.ts +6 -6
  86. package/src/server/files.ts +4 -19
  87. package/src/server/host.ts +1 -1
  88. package/src/server/index.ts +4 -16
  89. package/src/server/naming.ts +1 -1
  90. package/src/server/pages.ts +38 -12
  91. package/src/server/server.ts +29 -189
  92. package/src/server/types.ts +7 -7
  93. package/src/shell/plan.ts +2 -2
  94. package/src/shell/runtime.ts +1 -9
  95. package/types/runtime/v1/artifact.d.ts +2 -3
  96. package/types/runtime/v1/assets.d.ts +1 -1
  97. package/types/runtime/v1/chat.d.ts +2 -2
  98. package/types/runtime/v1/comments.d.ts +1 -1
  99. package/types/runtime/v1/downloads.d.ts +2 -2
  100. package/types/runtime/v1/links.d.ts +2 -2
  101. package/dist/platform/focus-guard.d.ts +0 -252
  102. package/dist/platform/focus-guard.js +0 -764
  103. package/dist/server/nested.d.ts +0 -66
  104. package/dist/server/nested.js +0 -120
  105. package/dist/shell/frame.d.ts +0 -28
  106. package/dist/shell/frame.js +0 -338
  107. package/src/platform/focus-guard.ts +0 -999
  108. package/src/server/nested.ts +0 -156
  109. package/src/shell/frame.ts +0 -371
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Moves focus into one of the host page's own text fields (a composer that opens beside a
3
+ * display): `field.focus()` for a host to call instead. Firefox doesn't move focus out of a frame
4
+ * that holds it with a gesture of the person's, and takes it back on its own blur (measured: the
5
+ * keys then go on to the frame); so where a frame of the page holds the focus, it is blurred
6
+ * first. Elsewhere it is `field.focus()`.
7
+ *
8
+ * Nothing watches what happens next: until 0.16.0 a focus guard did, and counted a frame that
9
+ * took the focus back toward stopping its display (P109, removed by P149).
10
+ */
11
+ export declare function focusField(field: HTMLElement): void;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Moves focus into one of the host page's own text fields (a composer that opens beside a
3
+ * display): `field.focus()` for a host to call instead. Firefox doesn't move focus out of a frame
4
+ * that holds it with a gesture of the person's, and takes it back on its own blur (measured: the
5
+ * keys then go on to the frame); so where a frame of the page holds the focus, it is blurred
6
+ * first. Elsewhere it is `field.focus()`.
7
+ *
8
+ * Nothing watches what happens next: until 0.16.0 a focus guard did, and counted a frame that
9
+ * took the focus back toward stopping its display (P109, removed by P149).
10
+ */
11
+ export function focusField(field) {
12
+ const holder = field.ownerDocument.activeElement;
13
+ const view = field.ownerDocument.defaultView;
14
+ if (view !== null && holder instanceof view.HTMLIFrameElement) {
15
+ holder.blur();
16
+ }
17
+ field.focus({ preventScroll: true });
18
+ }
@@ -22,12 +22,6 @@ export interface SurfaceSpec {
22
22
  readonly fill?: boolean;
23
23
  /** The height to start at (a remembered height, so a frame mounting again doesn't jump). */
24
24
  readonly initialHeightPx: number;
25
- /**
26
- * The frame holds a nested page's shell (P111): the host's config says so, never the frame. What
27
- * the shell says of itself (`porthole/shell/state`) decides moves of focus into it and the
28
- * gesture its page's calls need; nothing else in that namespace reaches the transport.
29
- */
30
- readonly nested?: boolean;
31
25
  }
32
26
  /** One isolated frame. */
33
27
  export interface Surface {
@@ -39,7 +33,7 @@ export interface Surface {
39
33
  /**
40
34
  * Whether the embedding page has transient user activation now (a gesture in the frame
41
35
  * activates its ancestors), or undefined where the platform can't tell. The gesture gate reads
42
- * it, and so does a marker's click (P105): false, or a throw, drops it.
36
+ * it (`copyText`'s by default, and any a host's config adds).
43
37
  */
44
38
  userActivation(): boolean | undefined;
45
39
  /**
@@ -53,23 +47,13 @@ export interface Surface {
53
47
  readonly height: number;
54
48
  } | undefined;
55
49
  /**
56
- * Whether the embedding page's focus is in this frame now, once the platform's focus guard
57
- * judged any move into it (P109); undefined, or absent, where the platform can't tell. A gesture
58
- * gate that asks for the person in the calling frame (`comments`) reads it: false refuses. A
59
- * nested page's frame (P111) is the person's too while its shell saw their gesture just now.
50
+ * Whether the embedding page's keyboard focus is in this frame now, as its document says;
51
+ * undefined, or absent, where the platform can't tell. The find shortcut reads it (P131: a
52
+ * frame that says the shortcut was pressed while the focus is elsewhere is not believed). No
53
+ * word on who put the focus there: a frame may take it by itself (P149).
60
54
  */
61
55
  focused?(): boolean | undefined;
62
- /**
63
- * Each time the content moved the keyboard into its frame from one of the embedding page's text
64
- * fields without the person (no press on the frame, no Tab) and the platform gave focus back
65
- * (P109): whether the person was typing then (a key within the last second), and whether focus
66
- * failed to go back (the frame kept it or took it again). Absent where the platform has no guard.
67
- */
68
- onFocusTaken?(listener: (take: {
69
- readonly typing: boolean;
70
- readonly failed: boolean;
71
- }) => void): () => void;
72
- /** The host moves focus into the frame itself: the guard takes it as the person's (P109). */
56
+ /** The host moves focus into the frame itself. */
73
57
  focus?(): void;
74
58
  /**
75
59
  * The frame loaded a document other than the one it was given: the content navigated it. The
@@ -1,65 +1,5 @@
1
1
  import { DOOR_SANDBOX_TOKENS } from "../compile/policy.js";
2
- import { SHELL_BEAT_METHOD, SHELL_FOCUS_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
3
2
  import { postMessageTransport } from "../transport/post-message.js";
4
- import { focusGuard } from "./focus-guard.js";
5
- /** A shell's own message (P111), by its namespace. */
6
- const isShellWord = (data) => data !== null &&
7
- typeof data === "object" &&
8
- typeof data.method === "string" &&
9
- data.method.startsWith(SHELL_METHOD_PREFIX);
10
- /**
11
- * A nested page's transport (P111): the shell's state, checked, to the focus guard; the rest of
12
- * the shell's namespace dropped; everything else as it came.
13
- */
14
- function shellWords(opened, frame, guard) {
15
- const listeners = new Set();
16
- opened.listen((message) => {
17
- if (!isShellWord(message)) {
18
- for (const listener of listeners) {
19
- listener(message);
20
- }
21
- return;
22
- }
23
- const params = message.params;
24
- if (params === null || typeof params !== "object") {
25
- return;
26
- }
27
- const { supported, ago, focused, gap, asked } = params;
28
- const span = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
29
- if (message.method === SHELL_BEAT_METHOD) {
30
- if (span(gap)) {
31
- guard.beat(frame);
32
- }
33
- return;
34
- }
35
- if (message.method !== SHELL_STATE_METHOD ||
36
- typeof supported !== "boolean" ||
37
- typeof focused !== "boolean" ||
38
- !(ago === null || span(ago)) ||
39
- !span(gap) ||
40
- !(asked === undefined || (Number.isSafeInteger(asked) && asked >= 0))) {
41
- return;
42
- }
43
- guard.shell(frame, {
44
- supported,
45
- ago: ago,
46
- focused,
47
- gap: gap,
48
- ...(asked === undefined ? {} : { asked: asked }),
49
- });
50
- });
51
- return {
52
- send: (message) => opened.send(message),
53
- listen(listener) {
54
- listeners.add(listener);
55
- return () => listeners.delete(listener);
56
- },
57
- close() {
58
- listeners.clear();
59
- opened.close();
60
- },
61
- };
62
- }
63
3
  /**
64
4
  * The web platform: an `<iframe>` whose policy attributes are set before its document is given,
65
5
  * talking over `postMessage`. Its first load is the document it was given; any later load is the
@@ -111,32 +51,10 @@ export const webPlatform = {
111
51
  });
112
52
  container.append(frame);
113
53
  const view = container.ownerDocument.defaultView ?? window;
114
- // The focus guard (P109): a move of the keyboard into this frame from one of the page's text
115
- // fields that the person didn't make is undone.
116
- const guard = focusGuard(view);
117
- const taken = new Set();
118
- const nested = spec.nested === true && spec.source.kind === "url";
119
54
  // A frame is heard from its own window and its located origin alone: never the host's own
120
55
  // origin (P125 removed P068's in-frame pages and the channel that heard them), so no page of
121
56
  // the host's own can speak for a frame either.
122
- const opened = postMessageTransport(() => frame.contentWindow, origin, view);
123
- const unguard = guard.add(frame, (take) => {
124
- for (const listener of taken) {
125
- listener(take);
126
- }
127
- }, {
128
- nested,
129
- // A nested page's shell is asked to look as the guard hears a move into its frame (P120).
130
- ...(nested
131
- ? {
132
- ask: (n) => opened.send({ jsonrpc: "2.0", method: SHELL_LOOK_METHOD, params: { n } }),
133
- }
134
- : {}),
135
- });
136
- // A nested page's shell (P111): its own words go to the guard, by the frame's window and the
137
- // content origin (the transport's checks); the page's pass on. The shell drops any page
138
- // message in its namespace, so there none is the page's.
139
- const transport = nested ? shellWords(opened, frame, guard) : opened;
57
+ const transport = postMessageTransport(() => frame.contentWindow, origin, view);
140
58
  return {
141
59
  transport,
142
60
  element: frame,
@@ -160,20 +78,15 @@ export const webPlatform = {
160
78
  const activation = view.navigator.userActivation;
161
79
  return activation === undefined ? undefined : activation.isActive;
162
80
  },
81
+ // Where the keyboard is, as the frame's own tree says it (its document's, or the shadow
82
+ // root's it is in): no more than that. A frame may take the focus by itself (0.16.0
83
+ // removed the guard that took it back, P149), so this is no word on who put it there.
163
84
  focused() {
164
- return guard.focused(frame) || (nested && guard.gesture(frame));
165
- },
166
- onFocusTaken(listener) {
167
- taken.add(listener);
168
- return () => taken.delete(listener);
85
+ const root = frame.getRootNode();
86
+ return root.activeElement === frame;
169
87
  },
170
88
  focus() {
171
- guard.focus(frame);
172
- // A nested page (P136): the move stops at its shell on every engine, one way or another,
173
- // and only the shell can pass it on. Only a move that landed: the shell asks no more of it.
174
- if (nested && view.document.activeElement === frame) {
175
- opened.send({ jsonrpc: "2.0", method: SHELL_FOCUS_METHOD });
176
- }
89
+ frame.focus();
177
90
  },
178
91
  onLoad(listener) {
179
92
  loaded.add(listener);
@@ -186,8 +99,6 @@ export const webPlatform = {
186
99
  destroy() {
187
100
  navigated.clear();
188
101
  loaded.clear();
189
- taken.clear();
190
- unguard();
191
102
  transport.close();
192
103
  frame.remove();
193
104
  },
@@ -197,8 +108,7 @@ export const webPlatform = {
197
108
  * A served display's door (P125): hidden (no size, `visibility: hidden`, which still runs its
198
109
  * script and fires its load on all three engines), out of focus and of the accessibility tree,
199
110
  * sandboxed with scripts alone, no `allow`, no name. Nothing but its frame status is heard from
200
- * it, from its window and the opaque origin alone; the focus guard, the bridge and annotations
201
- * never see it.
111
+ * it, from its window and the opaque origin alone; the bridge and annotations never see it.
202
112
  */
203
113
  createDoor(container, spec) {
204
114
  // oxlint-disable-next-line react/iframe-missing-sandbox -- set from the door's list, next
@@ -40,8 +40,6 @@ export interface PresetOptions {
40
40
  * be offered the runtime's own (`user`, `comments`, `artifact`, `assets`, `db`).
41
41
  */
42
42
  readonly runtime?: RuntimeVersion;
43
- /** Domain isolation, artifact pages: the page in an opaque child of Porthole's shell (P111). */
44
- readonly nested?: true;
45
43
  /**
46
44
  * `own` (P128): an `<iframe>` of one of the page's own files (a relative `src`) or a `srcdoc`
47
45
  * one loads and runs, in a realm of its own that the shell's hardening doesn't reach
@@ -141,7 +141,6 @@ function build(mode, defaults, options) {
141
141
  ...(options.storage === undefined ? {} : { storage: options.storage }),
142
142
  ...(options.errors === undefined ? {} : { errors: options.errors }),
143
143
  ...(options.runtime === undefined ? {} : { runtime: options.runtime }),
144
- ...(options.nested === undefined ? {} : { nested: options.nested }),
145
144
  ...(options.nestedFrames === undefined ? {} : { nestedFrames: options.nestedFrames }),
146
145
  });
147
146
  }
@@ -285,14 +285,6 @@ export interface PortholeFrameProps {
285
285
  readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
286
286
  /** Too many declines: the display stops asking until it runs again. */
287
287
  readonly onMuted?: () => void;
288
- /**
289
- * The content moved the keyboard into its frame from one of the page's text fields without the
290
- * person, and focus went back (P109); `typing`: the person was typing on the page. A display
291
- * that keeps doing it is stopped (`onContentError` says so).
292
- */
293
- readonly onFocusTaken?: (taken: {
294
- readonly typing: boolean;
295
- }) => void;
296
288
  /**
297
289
  * How the frame's first document went: loaded, blocked (and why), or a timeout. A host shows its
298
290
  * own fallback (a url-mode app "Open in a new tab") on anything but loaded.
@@ -509,9 +509,6 @@ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, ru
509
509
  case "muted":
510
510
  frame.onMuted?.();
511
511
  return;
512
- case "focusTaken":
513
- frame.onFocusTaken?.(detail);
514
- return;
515
512
  case "outcome":
516
513
  frame.onOutcome?.(detail);
517
514
  return;
@@ -636,7 +633,6 @@ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, ru
636
633
  "navigationBlocked",
637
634
  "refused",
638
635
  "muted",
639
- "focusTaken",
640
636
  "outcome",
641
637
  "annotation",
642
638
  "findRequested",
@@ -38,8 +38,8 @@ export interface RuntimeMethod {
38
38
  readonly watch?: true;
39
39
  /**
40
40
  * Gates of its own, over its host function's (after the review, P088): what changes the
41
- * artifact for everyone needs the person's click and their yes. A host's config may replace
42
- * them (`CapabilityConfig.methodGates`).
41
+ * artifact for everyone needs the person's yes. A host's config may replace them
42
+ * (`CapabilityConfig.methodGates`).
43
43
  */
44
44
  readonly gates?: readonly Gate[];
45
45
  }
@@ -33,8 +33,8 @@ const method = (serves, level, extra = {}) => ({
33
33
  ...(extra.watch === undefined ? {} : { watch: true }),
34
34
  ...(extra.gates === undefined ? {} : { gates: extra.gates }),
35
35
  });
36
- /** What changes the artifact for everyone: the person's click, then their yes. */
37
- const CHANGES = ["user-activation", "confirm"];
36
+ /** What changes the artifact for everyone: the person's yes, to its whole effect (no proof of a click since 0.16.0, P149). */
37
+ const CHANGES = ["confirm"];
38
38
  /** Contract 1's capabilities, by the name a page passes to `use`. */
39
39
  export const RUNTIME_CAPABILITIES = {
40
40
  /** Who is viewing: `{ id, name, level }`, as the host says. Declared: the page learns who. */
@@ -3,16 +3,16 @@
3
3
  // contract every capability shares).
4
4
  export const RUNTIME_TYPES = {
5
5
  "1": {
6
- "artifact": "// Porthole capability runtime, contract 1: artifact (this artifact itself). Declare it: { artifact: {} }.\n// Use it when the page is the record: a checklist, a plan, a document someone edits in place.\n\ninterface PortholeArtifactFile {\n readonly path: string;\n readonly size: number;\n readonly sha256: string;\n}\n\ninterface PortholeArtifactVersion {\n /** The version's id: what a publish names as its base. */\n readonly version: string;\n readonly number?: number;\n /** The page it opens at (\"index.html\"). */\n readonly entry: string;\n readonly files: readonly PortholeArtifactFile[];\n}\n\ninterface PortholeArtifactPublish {\n /** The version you read and changed (from get()). If it moved, publish rejects with conflict. */\n readonly base: string;\n /**\n * A patch on base's files, by path: text, bytes (a Blob, an ArrayBuffer, a typed array), or\n * null to remove one; files not named are kept. A page sends its whole document, as it should\n * be served. At most 255 files.\n */\n readonly files: Readonly<Record<string, string | Blob | ArrayBuffer | ArrayBufferView | null>>;\n readonly entry?: string;\n /** At most 60 characters. */\n readonly label?: string;\n /** At most 500 characters. */\n readonly note?: string;\n}\n\ninterface PortholeArtifact {\n /** The current version and its files (fetch a file by its relative path). Level: view. */\n get(): Promise<PortholeArtifactVersion>;\n /**\n * Publishes a new version of this artifact, from a click; the app asks the person first. The\n * page can't change what it declares. On conflict: get() again, merge, publish again. Level:\n * admin.\n */\n publish(\n change: PortholeArtifactPublish,\n ): Promise<{ readonly version: string; readonly number?: number }>;\n}\n\ninterface PortholeCapabilities {\n artifact: PortholeArtifact;\n}\n",
7
- "assets": "// Porthole capability runtime, contract 1: assets (the artifact's asset library). Declare it: { assets: {} }.\n// Assets live outside every version, at \"/_blob/<id>\" on the page's own origin: keep that url (or\n// the id) in your data, and show it with assets.url(id). Images, media and fonts load; scripts and\n// stylesheets only where the app lets only admins upload, and only those an admin added. Not for\n// files that version with the page: publish those with it.\n\ninterface PortholeAsset {\n /** 32 hex characters. */\n readonly id: string;\n /** \"/_blob/<id>\": use it as given. */\n readonly url: string;\n readonly name: string;\n /** Porthole's type for the name's extension. */\n readonly type: string;\n readonly size: number;\n}\n\ninterface PortholeAssets {\n /** The library, people's uploads through the page included. Level: view. */\n list(): Promise<readonly PortholeAsset[]>;\n /**\n * Adds a file (a File from an <input type=\"file\">, a Blob, bytes) under its name (a File's own,\n * or options.name): an image, media, a font, a PDF, text or data, never HTML; a script or a\n * stylesheet only where uploads are the admins'. The app may ask the person first. Level: admin,\n * unless the app lets people who interact upload.\n */\n upload(\n file: Blob | ArrayBuffer | ArrayBufferView,\n options?: { readonly name?: string },\n ): Promise<PortholeAsset>;\n /**\n * The address that loads an asset in this page now: put it in src or href when you show it.\n * Store the id (or \"/_blob/<id>\"), never this: it carries this page's access. A \"/_blob/<id>\"\n * written in the page loads too, except in some browsers' frames (Safari's); this always does.\n */\n url(id: string): string;\n /** Removes one, from a click; the app asks the person first. Level: admin. */\n delete(id: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n assets: PortholeAssets;\n}\n",
8
- "chat": "// Porthole capability runtime, contract 1: chat. Declare it: { chat: {} }.\n\ninterface PortholeChat {\n /**\n * Sends text to the agent as the person's message (\"explain this point\"). Call it from a click.\n * Resolves true if it was sent. Level: interact.\n */\n send(text: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n chat: PortholeChat;\n}\n",
6
+ "artifact": "// Porthole capability runtime, contract 1: artifact (this artifact itself). Declare it: { artifact: {} }.\n// Use it when the page is the record: a checklist, a plan, a document someone edits in place.\n\ninterface PortholeArtifactFile {\n readonly path: string;\n readonly size: number;\n readonly sha256: string;\n}\n\ninterface PortholeArtifactVersion {\n /** The version's id: what a publish names as its base. */\n readonly version: string;\n readonly number?: number;\n /** The page it opens at (\"index.html\"). */\n readonly entry: string;\n readonly files: readonly PortholeArtifactFile[];\n}\n\ninterface PortholeArtifactPublish {\n /** The version you read and changed (from get()). If it moved, publish rejects with conflict. */\n readonly base: string;\n /**\n * A patch on base's files, by path: text, bytes (a Blob, an ArrayBuffer, a typed array), or\n * null to remove one; files not named are kept. A page sends its whole document, as it should\n * be served. At most 255 files.\n */\n readonly files: Readonly<Record<string, string | Blob | ArrayBuffer | ArrayBufferView | null>>;\n readonly entry?: string;\n /** At most 60 characters. */\n readonly label?: string;\n /** At most 500 characters. */\n readonly note?: string;\n}\n\ninterface PortholeArtifact {\n /** The current version and its files (fetch a file by its relative path). Level: view. */\n get(): Promise<PortholeArtifactVersion>;\n /**\n * Publishes a new version of this artifact; the app asks the person first. The page can't\n * change what it declares. On conflict: get() again, merge, publish again. Level: admin.\n */\n publish(\n change: PortholeArtifactPublish,\n ): Promise<{ readonly version: string; readonly number?: number }>;\n}\n\ninterface PortholeCapabilities {\n artifact: PortholeArtifact;\n}\n",
7
+ "assets": "// Porthole capability runtime, contract 1: assets (the artifact's asset library). Declare it: { assets: {} }.\n// Assets live outside every version, at \"/_blob/<id>\" on the page's own origin: keep that url (or\n// the id) in your data, and show it with assets.url(id). Images, media and fonts load; scripts and\n// stylesheets only where the app lets only admins upload, and only those an admin added. Not for\n// files that version with the page: publish those with it.\n\ninterface PortholeAsset {\n /** 32 hex characters. */\n readonly id: string;\n /** \"/_blob/<id>\": use it as given. */\n readonly url: string;\n readonly name: string;\n /** Porthole's type for the name's extension. */\n readonly type: string;\n readonly size: number;\n}\n\ninterface PortholeAssets {\n /** The library, people's uploads through the page included. Level: view. */\n list(): Promise<readonly PortholeAsset[]>;\n /**\n * Adds a file (a File from an <input type=\"file\">, a Blob, bytes) under its name (a File's own,\n * or options.name): an image, media, a font, a PDF, text or data, never HTML; a script or a\n * stylesheet only where uploads are the admins'. The app may ask the person first. Level: admin,\n * unless the app lets people who interact upload.\n */\n upload(\n file: Blob | ArrayBuffer | ArrayBufferView,\n options?: { readonly name?: string },\n ): Promise<PortholeAsset>;\n /**\n * The address that loads an asset in this page now: put it in src or href when you show it.\n * Store the id (or \"/_blob/<id>\"), never this: it carries this page's access. A \"/_blob/<id>\"\n * written in the page loads too, except in some browsers' frames (Safari's); this always does.\n */\n url(id: string): string;\n /** Removes one; the app asks the person first. Level: admin. */\n delete(id: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n assets: PortholeAssets;\n}\n",
8
+ "chat": "// Porthole capability runtime, contract 1: chat. Declare it: { chat: {} }.\n\ninterface PortholeChat {\n /**\n * Sends text to the agent as the person's message (\"explain this point\"); the app asks them\n * first. Resolves true if it was sent. Level: interact.\n */\n send(text: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n chat: PortholeChat;\n}\n",
9
9
  "clipboard": "// Porthole capability runtime, contract 1: clipboard. Built in: never declare it.\n\ninterface PortholeClipboard {\n /**\n * Copies text to the person's clipboard (at most 20,000 characters); the app shows them what\n * was copied. Nothing else in the page can write the clipboard. Call it from a click.\n * Resolves true if it was copied. Level: view.\n */\n copy(text: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n clipboard: PortholeClipboard;\n}\n",
10
- "comments": "// Porthole capability runtime, contract 1: comments. Built in: never declare it.\n\n/** Where a comment goes, in the page's own words. */\ninterface PortholeCommentAnchor {\n /** A stable name the page chose: \"slide-3\", \"refs/a.md#L12\" (at most 256 characters). */\n readonly name: string;\n /** What the app shows for it (at most 200; what a person can't see is taken out). */\n readonly label?: string;\n /** The text the comment is about (at most 2,000; what a person can't see is taken out). */\n readonly quote?: string;\n}\n\n/** How the composer opens. */\ninterface PortholeCommentOptions {\n /**\n * Text the composer starts with (at most 2,000 characters): a draft the person edits, posts\n * or discards in the app. It is never posted without them. Visible text only: new lines and\n * tabs are fine (at most 32 blanks in a row, two blank lines in a row), and so are U+200C and\n * U+200D between two letters or marks (Persian, the Indic scripts); a draft with zero-width\n * characters, a joiner anywhere else (an emoji joined with U+200D too; ❤️ is fine), bidi or tag\n * characters, or a line or paragraph separator (U+2028, U+2029) is refused.\n */\n readonly draft?: string;\n}\n\ninterface PortholeComments {\n /**\n * Opens the app's comment composer at the anchor (a name alone is { name }), starting with\n * `options.draft` if given. The person writes and posts it in the app. Resolves true if the\n * composer opened, false if it didn't (the app may refuse while the person is writing).\n * Write-only: a page never reads comments. Call it from a click in the page. Level: view.\n */\n open(anchor: PortholeCommentAnchor | string, options?: PortholeCommentOptions): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n comments: PortholeComments;\n}\n",
10
+ "comments": "// Porthole capability runtime, contract 1: comments. Built in: never declare it.\n\n/** Where a comment goes, in the page's own words. */\ninterface PortholeCommentAnchor {\n /** A stable name the page chose: \"slide-3\", \"refs/a.md#L12\" (at most 256 characters). */\n readonly name: string;\n /** What the app shows for it (at most 200; what a person can't see is taken out). */\n readonly label?: string;\n /** The text the comment is about (at most 2,000; what a person can't see is taken out). */\n readonly quote?: string;\n}\n\n/** How the composer opens. */\ninterface PortholeCommentOptions {\n /**\n * Text the composer starts with (at most 2,000 characters): a draft the person edits, posts\n * or discards in the app. It is never posted without them. Visible text only: new lines and\n * tabs are fine (at most 32 blanks in a row, two blank lines in a row), and so are U+200C and\n * U+200D between two letters or marks (Persian, the Indic scripts); a draft with zero-width\n * characters, a joiner anywhere else (an emoji joined with U+200D too; ❤️ is fine), bidi or tag\n * characters, or a line or paragraph separator (U+2028, U+2029) is refused.\n */\n readonly draft?: string;\n}\n\ninterface PortholeComments {\n /**\n * Opens the app's comment composer at the anchor (a name alone is { name }), starting with\n * `options.draft` if given. The person writes and posts it in the app. Resolves true if the\n * composer opened, false if it didn't (the app may refuse while the person is writing).\n * Write-only: a page never reads comments. Level: view.\n */\n open(anchor: PortholeCommentAnchor | string, options?: PortholeCommentOptions): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n comments: PortholeComments;\n}\n",
11
11
  "context": "// Porthole capability runtime, contract 1: context. Declare it: { context: {} }.\n\ninterface PortholeContextUpdate {\n /**\n * MCP text blocks only: [{ type: \"text\", text: \"…\" }]. Visible characters only, here and in\n * structuredContent: no zero-width or bidi controls, variation selectors, tag or private-use\n * characters, or controls other than new lines and tabs (refused), but the selectors and\n * joiners inside real emoji (☀️, 👨‍👩‍👧, 1️⃣), and a joiner or non-joiner between two letters of\n * a script it shapes (Arabic, Persian, the Indic scripts, Myanmar…).\n */\n readonly content?: readonly unknown[];\n /** Plain JSON. With the text, at most 20,000 characters. */\n readonly structuredContent?: Record<string, unknown>;\n}\n\ninterface PortholeContext {\n /**\n * Tells the agent, at its next turns, what the page says the person is looking at (replaces the\n * last). The agent reads it as the page's words, unconfirmed by the person; the app shows the\n * person each update unless it says otherwise. Level: interact.\n */\n set(update: PortholeContextUpdate): Promise<unknown>;\n}\n\ninterface PortholeCapabilities {\n context: PortholeContext;\n}\n",
12
12
  "data": "// Porthole capability runtime, contract 1: data (the app's data and tools).\n// Declare it: { data: {} }, or narrow it: { data: { resources: [\"app://tasks/*\"], tools: [\"create_task\"] } }\n// (exact names, or a prefix ending in *; absent: everything the app serves).\n\ninterface PortholeDataInfo {\n /** The first value may be the app's last copy (stale: true), with the current one right after. */\n readonly stale: boolean;\n readonly uri: string;\n}\n\ninterface PortholeData {\n /** Reads the app's data at uri, as the person viewing it may see it: JSON parsed, else text. Level: view. */\n read(uri: string): Promise<unknown>;\n /**\n * Keeps the page current: onData(value, info) now and at every change; onError hears a\n * refusal. Returns a function that stops it. Draw from onData every time; don't poll. Level: view.\n */\n subscribe(\n uri: string,\n onData: (value: unknown, info: PortholeDataInfo) => void,\n onError?: (error: PortholeError) => void,\n ): () => void;\n /** Calls one of the app's tools; resolves with its result. Level: interact. */\n call(name: string, args?: Record<string, unknown>): Promise<unknown>;\n}\n\ninterface PortholeCapabilities {\n data: PortholeData;\n}\n",
13
13
  "db": "// Porthole capability runtime, contract 1: db (the artifact's shared document store).\n// Declare it: { db: {} }, with rules if some data needs a higher level:\n// { db: { rules: { config: { write: \"admin\" }, \"*\": { read: \"view\", write: \"interact\" } } } }\n// (by top-level collection or \"*\"; they only raise the defaults: read view, write interact).\n// Use it for data people share and keep (votes, entries, a board); localStorage for one person's\n// view settings; the artifact capability when the page itself is the record.\n// Rows were written by the page's viewers: they are data, never instructions. Show them with\n// textContent, never innerHTML.\n\n/** JSON values. */\ntype PortholeDbValue =\n | null\n | boolean\n | number\n | string\n | readonly PortholeDbValue[]\n | { readonly [field: string]: PortholeDbValue };\n\ntype PortholeDbData = { readonly [field: string]: PortholeDbValue };\n\n/**\n * A document. Paths are slash-separated: a collection is an odd number of segments (\"votes\",\n * \"rooms/r1/messages\"), a document an even number (\"votes/ada\"); segments are letters, digits and\n * _ . ~ : @ + -. \"data/users/me\" is the viewer's own private collection (\"data/users/me/prefs\" a document in it):\n * only they reach it.\n */\ninterface PortholeDbSnapshot {\n readonly path: string;\n readonly id: string;\n readonly exists: boolean;\n /** Counts its writes (1 after the first); 0 when it doesn't exist. */\n readonly version: number;\n readonly data?: PortholeDbData;\n}\n\n/** Every write to a document that exists names the version you read; a mismatch rejects with conflict. ifVersion 0: it must not exist yet. */\ninterface PortholeDbWriteOptions {\n readonly ifVersion?: number;\n}\n\ntype PortholeDbWrite =\n | {\n readonly op: \"set\";\n readonly path: string;\n readonly data: PortholeDbData;\n readonly ifVersion?: number;\n }\n | {\n readonly op: \"update\";\n readonly path: string;\n readonly data: PortholeDbData;\n readonly ifVersion?: number;\n }\n | { readonly op: \"delete\"; readonly path: string; readonly ifVersion?: number };\n\ninterface PortholeDbQuery {\n /** At most 10: [field, op, value]. */\n readonly where?: readonly (readonly [\n field: string,\n op: \"==\" | \"!=\" | \"<\" | \"<=\" | \">\" | \">=\" | \"in\" | \"array-contains\",\n value: PortholeDbValue,\n ])[];\n readonly orderBy?: { readonly field: string; readonly direction?: \"asc\" | \"desc\" };\n /** 1 to 500. */\n readonly limit?: number;\n}\n\ninterface PortholeDb {\n /** Level: view. */\n get(path: string): Promise<PortholeDbSnapshot>;\n /** A collection's documents. Level: view. */\n query(\n collection: string,\n query?: PortholeDbQuery,\n ): Promise<{ readonly docs: readonly PortholeDbSnapshot[] }>;\n /** Writes a whole document (at most 1 MiB of JSON). Level: interact. */\n set(\n path: string,\n data: PortholeDbData,\n options?: PortholeDbWriteOptions,\n ): Promise<{ readonly version: number }>;\n /** Merges fields over a document's. Level: interact. */\n update(\n path: string,\n data: PortholeDbData,\n options?: PortholeDbWriteOptions,\n ): Promise<{ readonly version: number }>;\n /** Level: interact. */\n delete(path: string, options?: PortholeDbWriteOptions): Promise<null>;\n /**\n * Up to 50 writes to different documents, all or none. Each write's new version (null for a\n * delete). Each write at its own level.\n */\n batch(\n writes: readonly PortholeDbWrite[],\n ): Promise<{ readonly versions: readonly (number | null)[] }>;\n /**\n * Follows a document (a snapshot) or a collection ({ docs }) now and at every change. Returns a\n * function that stops it. Draw from onData; don't poll. Level: view.\n */\n onSnapshot(\n path: string,\n onData: (state: PortholeDbSnapshot | { readonly docs: readonly PortholeDbSnapshot[] }) => void,\n onError?: (error: PortholeError) => void,\n ): () => void;\n}\n\ninterface PortholeCapabilities {\n db: PortholeDb;\n}\n",
14
- "downloads": "// Porthole capability runtime, contract 1: downloads. Built in: never declare it.\n\n/** A file to hand the person: its name, and its text or bytes. */\ninterface PortholeDownload {\n /** A file name, no slashes: \"report.csv\". Its extension gives its type unless `type` says. */\n readonly name: string;\n readonly type?: string;\n readonly text?: string;\n readonly data?: Blob | ArrayBuffer | ArrayBufferView;\n}\n\ninterface PortholeDownloads {\n /**\n * Hands the person a file to save (<a download> and script-driven saves don't work here).\n * Call it from a click. Resolves true if the download started. Level: view.\n */\n save(file: PortholeDownload): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n downloads: PortholeDownloads;\n}\n",
15
- "links": "// Porthole capability runtime, contract 1: links. Built in: never declare it.\n\ninterface PortholeLinks {\n /**\n * Opens an http(s) link outside the page (a click on an <a href> does the same). Call it from\n * a click. Resolves true if it opened. Level: view.\n */\n open(url: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n links: PortholeLinks;\n}\n",
14
+ "downloads": "// Porthole capability runtime, contract 1: downloads. Built in: never declare it.\n\n/** A file to hand the person: its name, and its text or bytes. */\ninterface PortholeDownload {\n /** A file name, no slashes: \"report.csv\". Its extension gives its type unless `type` says. */\n readonly name: string;\n readonly type?: string;\n readonly text?: string;\n readonly data?: Blob | ArrayBuffer | ArrayBufferView;\n}\n\ninterface PortholeDownloads {\n /**\n * Hands the person a file to save (<a download> and script-driven saves don't work here);\n * the app asks them first. Resolves true if the download started. Level: view.\n */\n save(file: PortholeDownload): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n downloads: PortholeDownloads;\n}\n",
15
+ "links": "// Porthole capability runtime, contract 1: links. Built in: never declare it.\n\ninterface PortholeLinks {\n /**\n * Opens an http(s) link outside the page (a click on an <a href> does the same); the app asks\n * the person first. Resolves true if it opened. Level: view.\n */\n open(url: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n links: PortholeLinks;\n}\n",
16
16
  "porthole": "// Porthole capability runtime, contract 1: the call contract (how a page reaches any capability).\n\n/**\n * Why a call was refused: branch on it; show `message` (a sentence for the person) where the\n * result would be. Never retry in a loop.\n * - consent_required: the person hasn't allowed it yet.\n * - denied: the person said no.\n * - rate_limited: too many calls this minute.\n * - not_allowed: not available here (some places show the page without it).\n * - failed: the app tried and couldn't.\n * - forbidden: this person may see the page but not do this (their level).\n * - conflict: what you change moved since you read it: read it again, then write.\n * - too_large: past a limit.\n */\ntype PortholeErrorCode =\n | \"consent_required\"\n | \"denied\"\n | \"rate_limited\"\n | \"not_allowed\"\n | \"failed\"\n | \"forbidden\"\n | \"conflict\"\n | \"too_large\";\n\n/** What every capability method rejects with. */\ninterface PortholeError extends Error {\n readonly code: PortholeErrorCode;\n}\n\n/** Each capability's namespace, by the name `use` takes (each capability's own file adds its own). */\ninterface PortholeCapabilities {}\n\ninterface PortholeRuntime {\n /**\n * The capability's namespace, frozen; or null when it isn't there for this page: the app\n * doesn't offer it, the page didn't declare it, or no app is showing the page (a tab, a\n * preview). The reasons are indistinguishable: draw the page without it. `use` never rejects;\n * permission problems come when you call a method (a rejected promise, `PortholeError`).\n */\n use<N extends keyof PortholeCapabilities>(name: N): Promise<PortholeCapabilities[N] | null>;\n}\n\n/** The page's one global. Nothing else is added to `window`. */\ndeclare const porthole: PortholeRuntime;\n",
17
17
  "user": "// Porthole capability runtime, contract 1: user. Declare it: { user: {} }.\n\n/** Who is viewing, as the app says. */\ninterface PortholeUserInfo {\n /** The app's id for this person (whose data \"data/users/me\" is), or null if it gives none. */\n readonly id: string | null;\n readonly name: string | null;\n /** What they may do here: view < interact < admin < owner. */\n readonly level: \"view\" | \"interact\" | \"admin\" | \"owner\";\n}\n\ninterface PortholeUser {\n /** Level: view. */\n get(): Promise<PortholeUserInfo>;\n}\n\ninterface PortholeCapabilities {\n user: PortholeUser;\n}\n",
18
18
  },
@@ -3,7 +3,6 @@ import { DEFAULT_ENTRY, lookupFile, requestFilePath } from "../files/paths.js";
3
3
  import { fileTypeOf } from "../files/types.js";
4
4
  import { isCodeAsset } from "../runtime/requests.js";
5
5
  import { sha256, utf8 } from "./crypto.js";
6
- import { NESTED_FILE_HEADERS, nestedFileCsp } from "./nested.js";
7
6
  const HEX = /^[0-9a-f]{64}$/u;
8
7
  const YEAR = 31_536_000;
9
8
  const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -179,8 +178,6 @@ export async function serveFile(serving) {
179
178
  return nothing(serving, 404, method);
180
179
  }
181
180
  const { type, role } = fileTypeOf(found.path);
182
- // A nested page (P111): in its shell's child, an opaque origin.
183
- const nested = serving.compiled.config.nested === true;
184
181
  // In a frame, the version's files are at a sealed address (P083), which their own loads of the
185
182
  // artifact's assets carry as their `Referer` (P091): to this origin only, never another.
186
183
  const referrer = serving.base.startsWith("/__porthole/f/") &&
@@ -193,17 +190,11 @@ export async function serveFile(serving) {
193
190
  // A page and a script (a worker's policy is its script's) get the page's CSP, a page with its
194
191
  // frame's sandbox, on a tab of its own too (P099); anything else runs nothing when opened on
195
192
  // its own.
196
- // A nested page's files are on its shell's origin (P111, after the review): every one carries a
197
- // sandbox, so none opened as a document on its own (a tab, "open image in new tab") runs on that
198
- // origin. Pages run their scripts, opaque; anything else runs nothing (a file's is inert already,
199
- // a script's gets one too).
200
- const csp = nested
201
- ? nestedFileCsp(role, directives)
202
- : role === "file"
203
- ? INERT_FILE_CSP
204
- : role === "page"
205
- ? servedDocumentCsp(serving.compiled.config, directives)
206
- : serializeCsp(directives);
193
+ const csp = role === "file"
194
+ ? INERT_FILE_CSP
195
+ : role === "page"
196
+ ? servedDocumentCsp(serving.compiled.config, directives)
197
+ : serializeCsp(directives);
207
198
  const headers = new Headers({
208
199
  "content-type": type,
209
200
  "x-content-type-options": "nosniff",
@@ -218,8 +209,7 @@ export async function serveFile(serving) {
218
209
  if (role === "page") {
219
210
  // Every page of the set in the shell (P081): its hardening, its host functions, its theme.
220
211
  const html = serving.compiled.shellDocument({
221
- // A nested page hears its shell, on its own origin, never the host (P111).
222
- origins: nested ? [serving.origin] : serving.hostOrigins,
212
+ origins: serving.hostOrigins,
223
213
  document: await textOf(body),
224
214
  cspMeta: false,
225
215
  ...(referrer === "same-origin" ? { referrer } : {}),
@@ -255,14 +245,8 @@ export async function serveFile(serving) {
255
245
  }
256
246
  headers.set("cache-control", serving.pinned ? `private, max-age=${YEAR}, immutable` : "private, no-cache");
257
247
  // Only this origin's own pages load it: no other content origin (a sibling, same-site without
258
- // the public suffix list) can embed it with the viewer's cookie. A nested page's origin is
259
- // opaque, and its files carry their access in their path, never a cookie (P111).
248
+ // the public suffix list) can embed it with the viewer's cookie.
260
249
  headers.set("cross-origin-resource-policy", "same-origin");
261
- if (nested) {
262
- for (const [name, value] of Object.entries(NESTED_FILE_HEADERS)) {
263
- headers.set(name, value);
264
- }
265
- }
266
250
  headers.set("accept-ranges", "bytes");
267
251
  if (role === "file" && type === "application/octet-stream") {
268
252
  headers.set("content-disposition", "attachment");
@@ -80,7 +80,7 @@ export interface ContentHostOptions<V> {
80
80
  /**
81
81
  * Origins of an outer page that frame the app itself (P141): each may be an ancestor of every frame
82
82
  * the app shows, above an app origin's page, so it is in every `frame-ancestors` Porthole sends
83
- * (content, nested pages, doors, status and entry pages, the authorize route's pages) after
83
+ * (content, doors, status and entry pages, the authorize route's pages) after
84
84
  * `appOrigins`, and nowhere else. Never an origin a frame hears or tells, never an app origin for
85
85
  * redirect entry or the handoff; the app's own page must still be the frame's parent. Exact https
86
86
  * origins (`http://` on loopback), none an app origin, none the content domain's site. The app's
@@ -38,7 +38,7 @@ export { clashOf, contentDomain, ContentDomainError, hostnameOf, type ContentDom
38
38
  export { d1TicketSchema, d1TicketStore, memoryTicketStore, type D1Like, type D1StatementLike, } from "./tickets.ts";
39
39
  export { DOOR_PATH, FRAME_STATUS_METHOD } from "../isolation/types.ts";
40
40
  export { doorResponse, doorStatusResponse, type DoorOptions } from "./pages.ts";
41
- export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedFileCsp, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.ts";
41
+ export { PORTHOLE_LABEL_PREFIX } from "../isolation/served.ts";
42
42
  export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
43
43
  export { conformancePage } from "../conformance/page.ts";
44
44
  export type { PortholeConfig } from "../config/schema.ts";
@@ -37,17 +37,15 @@ export { createContentHost, HEALTH_PATH, ISSUE_BODY_BYTES, ASSET_LIBRARY_PATH, i
37
37
  export { clashOf, contentDomain, ContentDomainError, hostnameOf, } from "./domain.js";
38
38
  export { d1TicketSchema, d1TicketStore, memoryTicketStore, } from "./tickets.js";
39
39
  export { DOOR_PATH, FRAME_STATUS_METHOD } from "../isolation/types.js";
40
- // A served display's door (P125): `/server` serves it for a shell, a page that isn't nested and the
40
+ // A served display's door (P125): `/server` serves it for a shell, a page and the
41
41
  // sandbox proxy; a content Worker of a host's own answers the same at `DOOR_PATH<key>`, after
42
42
  // taking the door's own ticket (`TicketRecord.door`) and running the checks its content's address
43
43
  // runs (docs/ADOPTING.md, "The door"). A host that signs its own tickets answers it with
44
44
  // `PortholeServer.doorAnswer` once it has admitted the request itself (P126).
45
45
  export { doorResponse, doorStatusResponse } from "./pages.js";
46
- // A nested page (P111): Porthole's shell at the framed address, the page and its files below the
47
- // sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
48
- // config with `nested`; a content Worker of its own answers the same (docs/ADOPTING.md, "Nested
49
- // pages").
50
- export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedFileCsp, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
46
+ // Labels that start so are Porthole's own (its health label; until 0.16.0 a nested page's shell's,
47
+ // P114): no host's naming makes one.
48
+ export { PORTHOLE_LABEL_PREFIX } from "../isolation/served.js";
51
49
  export { isHostLabel, prefixedName } from "./naming.js";
52
50
  // The page an app serves in conformance test mode (P071).
53
51
  export { conformancePage } from "../conformance/page.js";
@@ -17,7 +17,7 @@ export function prefixedName(prefix) {
17
17
  if (!PREFIX.test(prefix)) {
18
18
  throw new TypeError("A name prefix is a lowercase letter, then letters or digits, then '-' (a-)");
19
19
  }
20
- // Porthole's own labels (a nested page's shell's, P114) are never a scope's.
20
+ // Porthole's own labels are never a scope's.
21
21
  if (prefix === "porthole-") {
22
22
  throw new TypeError("The name prefix porthole- is Porthole's own: choose another (a-)");
23
23
  }
@@ -1,7 +1,14 @@
1
1
  import type { FrameBlock } from "../host/types.ts";
2
2
  /**
3
- * Who may frame a page: the host origins, then a host's `framedBy` (P141), each checked (they go
4
- * into a header).
3
+ * The host origins a helper was given, each checked as a config's are (`hostOriginProblem`, P145):
4
+ * they go into a header (`frame-ancestors`) and into the page's own list of whom it tells, and a
5
+ * content Worker of a host's own passes them here itself. `who` names the helper in the error.
6
+ */
7
+ export declare function checkHostOrigins(who: string, hostOrigins: readonly string[]): void;
8
+ /**
9
+ * Who may frame a page: the host origins, then a host's `framedBy` (P141), each `framedBy`
10
+ * checked here (they go into a header); the host origins by whoever was given them (a config's by
11
+ * `createServer`, a helper's by `checkHostOrigins`).
5
12
  */
6
13
  export declare function ancestorsOf(hostOrigins: readonly string[], framedBy?: readonly string[]): string;
7
14
  /** Where the pages' scripts are served, on every content origin. */
@@ -1,5 +1,5 @@
1
1
  import { DOOR_SANDBOX_TOKENS } from "../compile/policy.js";
2
- import { framedByProblem, includesOrigin, normalOrigin } from "../isolation/served.js";
2
+ import { framedByProblem, hostOriginProblem, includesOrigin, normalOrigin, } from "../isolation/served.js";
3
3
  import { FRAME_STATUS_METHOD } from "../isolation/types.js";
4
4
  import { base64url, sha256, utf8 } from "./crypto.js";
5
5
  /**
@@ -24,8 +24,22 @@ const isStrict = (frameAncestors, hostOrigins) => !heldToHosts(frameAncestors, h
24
24
  /** The attribute that says so, on a page's `<main>`: none where its parent is held to its hosts. */
25
25
  const strictParent = (strict) => (strict ? ' data-porthole-strict-parent=""' : "");
26
26
  /**
27
- * Who may frame a page: the host origins, then a host's `framedBy` (P141), each checked (they go
28
- * into a header).
27
+ * The host origins a helper was given, each checked as a config's are (`hostOriginProblem`, P145):
28
+ * they go into a header (`frame-ancestors`) and into the page's own list of whom it tells, and a
29
+ * content Worker of a host's own passes them here itself. `who` names the helper in the error.
30
+ */
31
+ export function checkHostOrigins(who, hostOrigins) {
32
+ for (const origin of hostOrigins) {
33
+ const problem = hostOriginProblem(origin);
34
+ if (problem !== null) {
35
+ throw new TypeError(`${who}: hostOrigins: ${problem}`);
36
+ }
37
+ }
38
+ }
39
+ /**
40
+ * Who may frame a page: the host origins, then a host's `framedBy` (P141), each `framedBy`
41
+ * checked here (they go into a header); the host origins by whoever was given them (a config's by
42
+ * `createServer`, a helper's by `checkHostOrigins`).
29
43
  */
30
44
  export function ancestorsOf(hostOrigins, framedBy = []) {
31
45
  for (const origin of framedBy) {
@@ -209,12 +223,17 @@ export function appStatusPage(status, title, detail, frameAncestors, reason, hos
209
223
  });
210
224
  }
211
225
  /** Whom a page tells, and who may frame it: the host origins' (P141), or an embed's (P143). */
212
- const framingOf = (options) => options.embed === true
213
- ? { hosts: [], ancestors: "*" }
214
- : {
226
+ const framingOf = (who, options) => {
227
+ if (options.embed === true) {
228
+ return { hosts: [], ancestors: "*" };
229
+ }
230
+ // Checked here too: with `frameAncestors` given, `ancestorsOf` never sees them.
231
+ checkHostOrigins(who, options.hostOrigins);
232
+ return {
215
233
  hosts: options.hostOrigins,
216
234
  ancestors: options.frameAncestors ?? ancestorsOf(options.hostOrigins, options.framedBy),
217
235
  };
236
+ };
218
237
  /**
219
238
  * A page saying why a frame shows nothing, for a relay of the app's own (P072): told to the page
220
239
  * that frames it, at each web host origin and (a desktop scheme among them) to its parent (P070),
@@ -222,7 +241,7 @@ const framingOf = (options) => options.embed === true
222
241
  * any page and told to no one.
223
242
  */
224
243
  export function statusPageOf(options) {
225
- const { hosts, ancestors } = framingOf(options);
244
+ const { hosts, ancestors } = framingOf("statusPage", options);
226
245
  return appStatusPage(options.status, options.title, options.detail, ancestors, options.reason ?? "error", hosts, options.link, options.method);
227
246
  }
228
247
  /** A door's word that its display may be framed (P125), from the page's data attributes. */
@@ -256,6 +275,7 @@ const doorHeaders = (script, frameAncestors) => new Headers({
256
275
  * own ticket was taken and the checks the content's address runs passed for the same grant.
257
276
  */
258
277
  export function doorResponse(options) {
278
+ checkHostOrigins("doorResponse", options.hostOrigins);
259
279
  const hosts = escape(JSON.stringify(options.hostOrigins));
260
280
  const ancestors = options.frameAncestors ?? ancestorsOf(options.hostOrigins, options.framedBy);
261
281
  const strict = isStrict(ancestors, options.hostOrigins);
@@ -275,7 +295,7 @@ export function doorResponse(options) {
275
295
  */
276
296
  export function doorStatusResponse(options) {
277
297
  const { status, reason, code } = options;
278
- const framing = framingOf(options);
298
+ const framing = framingOf("doorStatusResponse", options);
279
299
  const hosts = escape(JSON.stringify(framing.hosts));
280
300
  const ancestors = framing.ancestors;
281
301
  const strict = isStrict(ancestors, framing.hosts);