@botiverse/porthole 0.14.3 → 0.14.5

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 (45) hide show
  1. package/CHANGELOG.md +77 -0
  2. package/dist/check/page-source.js +1 -1
  3. package/dist/conformance/harness-source.js +1 -1
  4. package/dist/host/create-host.js +2 -0
  5. package/dist/host/locate.d.ts +1 -1
  6. package/dist/host/locate.js +2 -2
  7. package/dist/host/outcome.d.ts +4 -0
  8. package/dist/host/outcome.js +43 -0
  9. package/dist/host/types.d.ts +12 -4
  10. package/dist/isolation/served.d.ts +17 -1
  11. package/dist/isolation/served.js +24 -1
  12. package/dist/isolation/types.d.ts +5 -0
  13. package/dist/isolation/types.js +5 -0
  14. package/dist/platform/focus-guard.d.ts +40 -0
  15. package/dist/platform/focus-guard.js +176 -32
  16. package/dist/platform/web.js +24 -9
  17. package/dist/react/frame.d.ts +2 -1
  18. package/dist/server/files.js +7 -7
  19. package/dist/server/index.d.ts +1 -1
  20. package/dist/server/index.js +1 -1
  21. package/dist/server/nested.d.ts +13 -7
  22. package/dist/server/nested.js +31 -9
  23. package/dist/server/server.js +5 -2
  24. package/dist/shell/frame.d.ts +5 -2
  25. package/dist/shell/frame.js +41 -18
  26. package/docs/ADOPTING.md +37 -14
  27. package/docs/ARCHITECTURE.md +5 -1
  28. package/docs/DECISIONS.md +404 -2
  29. package/docs/DESIGN.md +11 -4
  30. package/docs/THREAT_MODEL.md +116 -32
  31. package/package.json +1 -1
  32. package/src/host/create-host.ts +2 -0
  33. package/src/host/locate.ts +2 -2
  34. package/src/host/outcome.ts +49 -0
  35. package/src/host/types.ts +12 -4
  36. package/src/isolation/served.ts +29 -0
  37. package/src/isolation/types.ts +6 -0
  38. package/src/platform/focus-guard.ts +218 -34
  39. package/src/platform/web.ts +29 -12
  40. package/src/react/frame.tsx +2 -1
  41. package/src/server/files.ts +5 -6
  42. package/src/server/index.ts +1 -0
  43. package/src/server/nested.ts +44 -12
  44. package/src/server/server.ts +5 -4
  45. package/src/shell/frame.ts +43 -18
@@ -7,7 +7,7 @@ import { isHostLabel, reservedLabels } from "./naming.js";
7
7
  import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
8
8
  import { libraryFile } from "./libraries.js";
9
9
  import { isNavigation, ownLoad, serveAsset, serveFile } from "./files.js";
10
- import { isNestedLabel, nestedAncestors, nestedLabelOf, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
10
+ import { isNestedLabel, nestedAncestors, nestedLabelOf, nestedFileCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
11
11
  import { DEFAULT_ENTRY } from "../files/paths.js";
12
12
  import { isPortholeCookie, setsPortholeCookie } from "./proxy.js";
13
13
  import { assetCodeRuns, assetCspDirectives, INERT_FILE_CSP, servedDocumentCsp, servedPermissionsPolicy, } from "../compile/policy.js";
@@ -966,7 +966,10 @@ export function createServer(options) {
966
966
  // A page that may use its artifact's assets loads them from its own origin (P089); every
967
967
  // served page carries its frame's sandbox, a tab of its own included (P099).
968
968
  const { config, cspDirectives } = served.compiled;
969
- const headers = documentHeaders(servedDocumentCsp(config, served.assets ? assetCspDirectives(config, cspDirectives, access.origin) : cspDirectives), servedPermissionsPolicy(config), ancestors);
969
+ const directives = served.assets
970
+ ? assetCspDirectives(config, cspDirectives, access.origin)
971
+ : cspDirectives;
972
+ const headers = documentHeaders(nested ? nestedFileCsp("page", directives) : servedDocumentCsp(config, directives), servedPermissionsPolicy(config), ancestors);
970
973
  if (cookie !== null) {
971
974
  headers.set("set-cookie", cookie);
972
975
  }
@@ -15,8 +15,11 @@
15
15
  * shell (activation goes up, never down), so the shell's activation turning on is a press or
16
16
  * key of the person's in this page. It is read at every animation frame, on its window's focus
17
17
  * and blur, and before each message of the page's is passed on (a call made in a click's handler
18
- * arrives after the state that says so). What it can't see: a gesture while its activation is
19
- * already on (within 5 s of the last one) turns nothing on;
18
+ * arrives after the state that says so), and at once when the host asks (`porthole/shell/look`,
19
+ * P120: the host heard focus move into the frame, and a key the person types into the page
20
+ * before the shell's next frame would turn its activation on as a press does). What it can't
21
+ * see: a gesture while its activation is already on (within 5 s of the last one) turns nothing
22
+ * on;
20
23
  * - renews the page's sealed files' address before it ends, and gives the page the new one
21
24
  * (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
22
25
  * are), so only the shell, on that origin, may renew it (P083);
@@ -1,5 +1,5 @@
1
1
  import { PAGE_SANDBOX_TOKENS } from "../compile/policy.js";
2
- import { hostOriginProblem } from "../isolation/served.js";
2
+ import { hostOriginProblem, onNestedLabel } from "../isolation/served.js";
3
3
  /**
4
4
  * Porthole's shell for a nested page (P111): the whole document at the address the host frames,
5
5
  * with no content in it. It frames the page (the same origin's sealed files' address) in a child
@@ -17,8 +17,11 @@ import { hostOriginProblem } from "../isolation/served.js";
17
17
  * shell (activation goes up, never down), so the shell's activation turning on is a press or
18
18
  * key of the person's in this page. It is read at every animation frame, on its window's focus
19
19
  * and blur, and before each message of the page's is passed on (a call made in a click's handler
20
- * arrives after the state that says so). What it can't see: a gesture while its activation is
21
- * already on (within 5 s of the last one) turns nothing on;
20
+ * arrives after the state that says so), and at once when the host asks (`porthole/shell/look`,
21
+ * P120: the host heard focus move into the frame, and a key the person types into the page
22
+ * before the shell's next frame would turn its activation on as a press does). What it can't
23
+ * see: a gesture while its activation is already on (within 5 s of the last one) turns nothing
24
+ * on;
22
25
  * - renews the page's sealed files' address before it ends, and gives the page the new one
23
26
  * (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
24
27
  * are), so only the shell, on that origin, may renew it (P083);
@@ -31,6 +34,12 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
31
34
  const plan = __PLAN__;
32
35
  const PREFIX = "porthole/shell/";
33
36
  const own = location.origin;
37
+ // A nested page's shell runs on a label of its own alone (P114, P121): on any other origin (its
38
+ // scope's, where other displays run content with allow-same-origin) it frames nothing and says
39
+ // nothing.
40
+ if (!/^porthole-[a-z2-7]{24}\./.test(location.hostname + ".")) {
41
+ return;
42
+ }
34
43
  let page = null;
35
44
  try {
36
45
  page = new URL(plan.page);
@@ -95,21 +104,22 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
95
104
  let focused = false;
96
105
  let lookedAt = performance.now();
97
106
  let toldAt = 0;
98
- const tell = (gap) => {
107
+ const tell = (gap, asked) => {
99
108
  toldAt = performance.now();
100
- toHost({
101
- jsonrpc: "2.0",
102
- method: PREFIX + "state",
103
- params: {
104
- supported: activation !== undefined,
105
- active,
106
- ago: active ? Math.max(0, Math.round(performance.now() - since)) : null,
107
- focused,
108
- gap: Math.max(0, Math.round(gap)),
109
- },
110
- });
109
+ const params = {
110
+ supported: activation !== undefined,
111
+ active,
112
+ ago: active ? Math.max(0, Math.round(performance.now() - since)) : null,
113
+ focused,
114
+ gap: Math.max(0, Math.round(gap)),
115
+ };
116
+ // The answer to the host's ask (P120), by its number.
117
+ if (asked !== undefined) {
118
+ params.asked = asked;
119
+ }
120
+ toHost({ jsonrpc: "2.0", method: PREFIX + "state", params });
111
121
  };
112
- const look = () => {
122
+ const look = (asked) => {
113
123
  const now = performance.now();
114
124
  const gap = now - lookedAt;
115
125
  lookedAt = now;
@@ -127,8 +137,8 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
127
137
  focused = inside;
128
138
  changed = true;
129
139
  }
130
- if (changed) {
131
- tell(gap);
140
+ if (changed || typeof asked === "number") {
141
+ tell(gap, typeof asked === "number" ? asked : undefined);
132
142
  } else if (now - toldAt >= 50) {
133
143
  // The heartbeat: the host knows the shell was looking, every 50 ms.
134
144
  toldAt = now;
@@ -166,6 +176,15 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
166
176
  return;
167
177
  }
168
178
  if (framed && source === window.parent && plan.origins.indexOf(event.origin) !== -1) {
179
+ const data = event.data;
180
+ // The host's words to the shell are never the page's to hear (P120): its ask to look now.
181
+ if (data !== null && typeof data === "object" && typeof data.method === "string" && data.method.indexOf(PREFIX) === 0) {
182
+ const n = data.params !== null && typeof data.params === "object" ? data.params.n : undefined;
183
+ if (data.method === PREFIX + "look" && typeof n === "number" && n >= 0 && Math.floor(n) === n) {
184
+ look(n);
185
+ }
186
+ return;
187
+ }
169
188
  const child = frame.contentWindow;
170
189
  if (child !== null) {
171
190
  child.postMessage(event.data, "*");
@@ -222,6 +241,10 @@ export function frameShellScript(options) {
222
241
  if (!page.pathname.startsWith("/__porthole/f/") || page.hash !== "") {
223
242
  throw new TypeError("frameShellScript: page is under /__porthole/f/, with no fragment");
224
243
  }
244
+ // The shell runs on a nested page's own label alone (P114), and its page is on its origin.
245
+ if (!onNestedLabel(page.origin)) {
246
+ throw new TypeError("frameShellScript: page is on a nested page's own label (porthole-<24 base32>, nestedLabelOf)");
247
+ }
225
248
  return FRAME_SHELL_RUNTIME.replace("__PLAN__", () => scriptJson({
226
249
  origins: options.origins,
227
250
  page: page.href,
package/docs/ADOPTING.md CHANGED
@@ -267,14 +267,20 @@ display.on("annotation", (report) => {
267
267
  if (report.type === "activated") bubble.openBeside(frame, report.rect, report.id);
268
268
  if (report.type === "anchored") bubble.follow(report.results);
269
269
  });
270
- // The selection was used (a comment posted, a draft added): take it, and its highlight, away.
271
- composer.onDone(() => display.annotations.clearSelection());
270
+ // The composer closed, whatever came of it (posted, a draft added, dismissed): take the selection,
271
+ // and its highlight, away. The page sees the clear: never clear only when a draft is added.
272
+ composer.onClose(() => display.annotations.clearSelection());
272
273
  ```
273
274
 
274
- - **Clear the selection once you used it** (`annotations.clearSelection()`, P115): the page's text
275
- selection, and the highlight the browser leaves on it (gray while focus is in your composer),
276
- stay until something clears them; the person's next click in the page would, and this does it
277
- when your composer is done with it. No `unselected` follows it (you know), and nothing else
275
+ - **Clear the selection when the composer closes, every time** (`annotations.clearSelection()`,
276
+ P115): the page's text selection, and the highlight the browser leaves on it (gray while focus
277
+ is in your composer), stay until something clears them; the person's next click in the page
278
+ would, and this does it when your composer is done with it. The page sees the clear (the
279
+ message, and a `selectionchange` with no press of its own), so it learns when the person was
280
+ done with its words (P121): clear on every close, kept or dismissed, or as the composer opens
281
+ (which tells it nothing `selected` and its blur didn't), or leave it to their next click; never
282
+ only when a draft is added, which tells the page that a draft exists there, and when. Above all
283
+ for a page `mayPassOn` says to keep drafts from (below). No `unselected` follows it (you know), and nothing else
278
284
  changes: your marks and drafts, the mode (`start`) and a followed mark stay. With nothing
279
285
  selected it does nothing; it is never sent to a frame that runs later (a reload has no selection
280
286
  to clear). Like `start` and `show`, only where the config declares `annotate`. The shell is your
@@ -293,10 +299,12 @@ composer.onDone(() => display.annotations.clearSelection());
293
299
  annotating={commenting ? { elements: false, text: true } : null}
294
300
  annotations={marks} trackedAnnotation={openCard?.markId ?? null}
295
301
  onAnnotation={(report) => {
296
- if (report.type === "tracked") card.moveBeside(report.rect);
302
+ // The page moves its mark, and so the card, at will: armed again as it moves (§6, P121).
303
+ if (report.type === "tracked" && card.moveBeside(report.rect) > 4) cardGuard.placed();
297
304
  if (report.type === "selected") composer.openBeside(report.rect, report.anchor);
298
305
  }} />
299
- composer.onDone(() => frame.current?.clearSelection());
306
+ // cardGuard = guardPresses(card.element) (below); moveBeside answers how far it moved, in px.
307
+ composer.onClose(() => frame.current?.clearSelection()); // every close, kept or dismissed
300
308
  ```
301
309
 
302
310
  - **Ids say nothing, and a count only where the page may know it**: the content reads every
@@ -323,7 +331,9 @@ composer.onDone(() => display.annotations.clearSelection());
323
331
  library CDNs (whose paths only their operators read); show such a page no draft marks.
324
332
  - **The content chooses when your view opens and where** (it can post `activated` for a mark you
325
333
  show on the person's own press in the content, under their pointer, P105), so a view that a
326
- report opens or moves takes no press of any kind for 500 ms after it appears or moves (no
334
+ report opens or moves (a card that follows a `tracked` mark included, each time it moves more
335
+ than a few px: the page moves it at will, up to 60 times a second) takes no press of any kind
336
+ for 500 ms after it appears or moves (no
327
337
  `pointerdown`, `pointerup`, `click` or key: menu triggers act on a press, and menu items click
328
338
  themselves on a release), ignores a press that began before that, opens beside the frame rather
329
339
  than over `rect` where the layout allows, takes no focus, and has nothing one click away that
@@ -417,7 +427,12 @@ focusField(composer.textarea); // Firefox ignores a plain focus() while a fighti
417
427
  page's field is taken back. A nested page's shell sees it: a move into the frame is the
418
428
  person's if the shell's activation turned on within the last second and you saw no press or key
419
429
  of your own since. A second press in the page within 5 s of the last turns nothing on: after the
420
- person went back to your composer, their next move in is taken back until then, or a Tab.
430
+ person went back to your composer, their next move in is taken back until then, or a Tab. A
431
+ nested page that takes the keyboard back as the guard returns it is fought as any page is, and
432
+ stopped (P120). A move into the page within 250 ms of the person's key on your page is taken
433
+ back on every engine (no hand presses that fast after typing, P122); on full Chromium a key the
434
+ person types into the page just as it takes the keyboard, slower than that, can still pass for a
435
+ press (THREAT_MODEL §7).
421
436
 
422
437
  ## 4. Served pages: the host kit
423
438
 
@@ -611,7 +626,7 @@ and Porthole's libraries (`egress.libraries`); the config refuses them.
611
626
 
612
627
  What a content origin serves for a nested page (`/server` does all of it; a content Worker of your
613
628
  own answers the same, with the helpers `/server` exports: `nestedLabelOf`, `nestedShellResponse`,
614
- `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the shell's own,
629
+ `nestedFileCsp`, `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the shell's own,
615
630
  `https://<nestedLabelOf(label)>.<content domain>`, where `label` is the scope's label (the one its
616
631
  other displays are served on); `<token>` is the access in the path (Porthole's sealed session, or a
617
632
  signed token of your own: the shell only needs addresses under the prefix). Your frame location
@@ -620,13 +635,16 @@ for a nested page is on `<origin>`.
620
635
  **The rule** (P114): `<origin>` answers the four rows below and Porthole's status pages, nothing
621
636
  else (no other display, no clean address, no asset, no app), and the scope's label never answers a
622
637
  nested page's shell, page or files. That is what keeps the shell's realm (its word to your page,
623
- the page's sealed address) out of every other display's reach.
638
+ the page's sealed address) out of every other display's reach. Porthole holds the shell to that
639
+ label (P121): `createHost` refuses a nested page located anywhere else (a host error, `locate`, and
640
+ no frame), `nestedShellResponse` throws for another origin, and the shell runs nowhere else. That
641
+ `<origin>` answers nothing but these is yours to hold: Porthole can't see your Worker's routes.
624
642
 
625
643
  | Request | Answer |
626
644
  | --- | --- |
627
645
  | `<origin>/__porthole/d/<key>`, the framed address (a ticket's, a cookie's reload; an entered clean address on the scope's label answers a `303` here with a one-time ticket), a navigation | 200, `text/html`: Porthole's shell, `nestedShellResponse(compiled, { origin, origins: hostOrigins, page: "<origin>/__porthole/f/<token>/<entry>", renew: { url: "<origin>/__porthole/f/<token>/__porthole/renew", expires } })`. Headers: `Content-Security-Policy: default-src 'none'; script-src 'sha256-<its script>'; frame-src <origin>/__porthole/f/; connect-src <origin>/__porthole/f/; base-uri 'none'; form-action 'none'; frame-ancestors <host origins>`; `Cache-Control: no-store`; `Referrer-Policy: no-referrer`; `X-Content-Type-Options: nosniff`; the served `Permissions-Policy`. No content in it. Any other request there: 404. |
628
- | `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy: <the page's directives, its files' prefix opened>; sandbox allow-scripts; frame-ancestors <origin> <host origins>` (never `allow-same-origin`). Access from `<token>` alone: no cookie is sent (the page's origin is opaque), and never decide by `Origin` (it is `null`) or `Sec-Fetch-Site` (`cross-site`). |
629
- | `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin`: a non-page file `default-src 'none'; sandbox`, a script its directives plus `sandbox`, so none opened on a tab of its own (an SVG, an XML file) runs on the shell's origin. |
646
+ | `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy`: `nestedFileCsp("page", fileSetCspDirectives(compiled.cspDirectives, "<origin>/__porthole/f/"))` then `; frame-ancestors ` and `nestedAncestors("<origin>", "<host origins>")`: the page's directives, its files' prefix opened, and `sandbox allow-scripts` (never `allow-same-origin`). Access from `<token>` alone: no cookie is sent (the page's origin is opaque), and never decide by `Origin` (it is `null`) or `Sec-Fetch-Site` (`cross-site`). |
647
+ | `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin` (`nestedFileCsp(fileTypeOf(path).role, directives)`, then the `frame-ancestors` above): a non-page file `default-src 'none'; sandbox`, a script its directives plus `sandbox`, so none opened on a tab of its own (an SVG, an XML file) runs on the shell's origin. |
630
648
  | `<origin>/__porthole/f/<token>/__porthole/renew` | Only the shell's own fetch (`Sec-Fetch-Site: same-origin`, not a navigation): `{ "base": "<origin>/__porthole/f/<new token>/", "expires": <epoch ms> }`, `no-store`; anything else 403. The shell renews 5 minutes before `expires` and moves the page to the new base. |
631
649
  | A token that ended, under the prefix | Porthole's status page (`401`, reason `session`), `frame-ancestors <origin> <host origins>`: it tells the shell, which tells your page (`outcome` blocked). |
632
650
 
@@ -798,6 +816,11 @@ display.on("outcome", (outcome) => {
798
816
  openButton.onclick = () => porthole.openInTab(instance); // the clean address
799
817
  ```
800
818
 
819
+ A `blocked` outcome is the word of Porthole's own pages, never of the content (P124): an opaque
820
+ frame's frame status is never taken, nor one a frame says after its first word; the host hears
821
+ those as a `hostError` of kind `"frame-status"` (log it, show nothing for it). Draw the fallback
822
+ from `outcome` only. A url-mode app is the exception: it can say any outcome (THREAT_MODEL S6).
823
+
801
824
  `porthole.config(kind)` is the served config while frames are served, the opaque one while they
802
825
  aren't, and null until the meta is known, so a frame never starts opaque and then restarts
803
826
  served. The client's functions take no `this`: pass them bare
@@ -214,6 +214,7 @@ Host app Shell (its own origin) Page (opaque child)
214
214
  │◄── the page's messages ──────│◄── postMessage (by source) ───│
215
215
  │── the host's messages ──────►│── postMessage ───────────────►│
216
216
  │◄── porthole/shell/state ─────│ its own activation, its focus │
217
+ │── porthole/shell/look ──────►│ look now (as a move is heard) │
217
218
  ```
218
219
 
219
220
  ### URL frame
@@ -292,7 +293,10 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
292
293
  transient activation, which only a press or key in the page turns on, and whether
293
294
  focus is in it), and the host, which knows the frame is nested from its config
294
295
  only, uses it to tell the person's gesture from the page's (the focus guard,
295
- `comments.open`). Everything else the page says is still the content's word.
296
+ `comments.open`). The host's own words in that namespace (its ask to look, P120)
297
+ go to the shell alone. A key and a press look the same in that word, so the host
298
+ doesn't ask it while it fights a frame for the keyboard (P120). Everything else
299
+ the page says is still the content's word.
296
300
 
297
301
  5. **Host's decision ↔ content domain.** Authentication and authorization
298
302
  *policy* are the host's; carrying the host's decision safely onto the content