@botiverse/porthole 0.14.15 → 0.14.17

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 +50 -0
  2. package/dist/annotate/types.d.ts +10 -1
  3. package/dist/annotate/validate.d.ts +9 -2
  4. package/dist/annotate/validate.js +9 -2
  5. package/dist/check/page-source.js +1 -1
  6. package/dist/conformance/harness-source.js +1 -1
  7. package/dist/host/create-host.js +11 -8
  8. package/dist/host/types.d.ts +13 -6
  9. package/dist/isolation/served.d.ts +8 -0
  10. package/dist/isolation/served.js +16 -0
  11. package/dist/react/frame.d.ts +9 -1
  12. package/dist/react/frame.js +23 -3
  13. package/dist/server/host.d.ts +14 -1
  14. package/dist/server/host.js +8 -3
  15. package/dist/server/nested.d.ts +5 -4
  16. package/dist/server/nested.js +8 -6
  17. package/dist/server/pages.d.ts +16 -2
  18. package/dist/server/pages.js +51 -16
  19. package/dist/server/server.js +26 -2
  20. package/dist/server/types.d.ts +8 -0
  21. package/dist/shell/annotate.d.ts +5 -3
  22. package/dist/shell/annotate.js +36 -16
  23. package/dist/shell/frame.d.ts +6 -0
  24. package/dist/shell/frame.js +16 -3
  25. package/dist/shell/runtime.d.ts +10 -0
  26. package/dist/shell/runtime.js +72 -26
  27. package/docs/ADOPTING.md +40 -22
  28. package/docs/DECISIONS.md +318 -3
  29. package/docs/DESIGN.md +19 -10
  30. package/docs/THREAT_MODEL.md +39 -7
  31. package/package.json +1 -1
  32. package/src/annotate/types.ts +10 -1
  33. package/src/annotate/validate.ts +15 -3
  34. package/src/host/create-host.ts +13 -14
  35. package/src/host/types.ts +13 -6
  36. package/src/isolation/served.ts +21 -0
  37. package/src/react/frame.tsx +36 -5
  38. package/src/server/host.ts +22 -4
  39. package/src/server/nested.ts +13 -5
  40. package/src/server/pages.ts +72 -18
  41. package/src/server/server.ts +32 -1
  42. package/src/server/types.ts +8 -0
  43. package/src/shell/annotate.ts +36 -16
  44. package/src/shell/frame.ts +22 -3
  45. package/src/shell/runtime.ts +73 -26
package/CHANGELOG.md CHANGED
@@ -4,6 +4,56 @@
4
4
  section); the reasons for every change are in [docs/DECISIONS.md](docs/DECISIONS.md), by the
5
5
  P-numbers below.
6
6
 
7
+ ## 0.14.17
8
+
9
+ - **An app framed by another (P141): `framedBy`.** `createContentHost({ framedBy })` and
10
+ `createServer({ framedBy })` name the origins of an outer page that frames your app (Raft's Deck).
11
+ `frame-ancestors` is checked against every ancestor, so until now each of your frames was blank
12
+ inside it. Each may now be an ancestor of every frame Porthole serves (content, nested pages,
13
+ doors, status, entry and tab-only pages, the authorize route's pages), after the host origins,
14
+ and is never a host: no frame hears or tells it, it is in no page's `data-porthole-hosts` or
15
+ shell's plan, and redirect entry and the handoff stay `appOrigins`' alone. Exact https origins
16
+ (`http://` on loopback); a wildcard, a path, a desktop scheme, an app origin or the content
17
+ domain's site throws. `statusPage`, `doorResponse`, `doorStatusResponse` and
18
+ `nestedShellResponse` take `framedBy` for a content Worker of your own. Without it every response
19
+ is as before.
20
+ - **Security (P141):** a loosening, bounded: the outer origins only in `frame-ancestors`, and
21
+ checked. Where they are set, a page or a nested page's shell says its `*` fallback (a desktop
22
+ scheme among the host origins) only to a parent the engine names as a host origin, so an outer
23
+ page that frames content directly is told nothing by Porthole and heard by nothing; it can hear
24
+ what the content itself says to its parent.
25
+
26
+ ## 0.14.16
27
+
28
+ - **On a tab the shell asks no host (P139).** A page opened on a tab of its own no longer asks
29
+ `ui/initialize` 40 times over 10 s before the runtime says it has nothing to offer: there is no
30
+ host there to answer, so it says so at once, with no request and no timer. In a frame nothing
31
+ changes. `porthole.use` was already null at once on a tab, so pages draw as before.
32
+ - **The shell says how its handshake ended (P139).** The document's root (`<html>`) carries
33
+ `data-porthole-host`, kept when a whole page replaces the shell's body: `"none"` once no host
34
+ will answer (on a tab, before the page's own scripts run), `"answered"` once one has. A tool that shoots pages on a tab (a publish check) can wait for
35
+ it instead of a fixed 10 s, keeping the fixed wait where it is absent (an older shell). It is the
36
+ page's word, never a gate. Upgrade the content server for it.
37
+ - **Security (P139):** no CSP, sandbox, egress, gate or message changes. On a tab the shell sent
38
+ nothing before either (its parent is itself).
39
+ - **Annotations: a pick stays lit only for a host that follows it (P140, Ferryman's audit of
40
+ 0.14.15).** 0.14.15 kept every pick outlined after `selected`, and every selection in the frame's
41
+ memory, for every host, including one that never follows the selection. Now that happens only for
42
+ a host that says it follows what is selected: `annotations.start({ ..., keepSelection: true })`
43
+ (React does it for you on a start made while `trackedSelection` is given; giving it or leaving it
44
+ out later restarts no mode). Any other host gets 0.14.14's
45
+ behaviour: the outline goes with the pick, and the frame keeps nothing. A follow asked before the
46
+ pick follows it without the option. **If you follow the selection after `selected`** (0.14.15's
47
+ sample, and React with `trackedSelection`), start with `keepSelection: true`, or give
48
+ `trackedSelection` from the first render (`false` until the composer opens): without it a newer
49
+ content server has nothing to follow and answers `orphaned`, so upgrade the host with the content
50
+ server.
51
+ - **Annotations: an unasked `selectionTracked` is no refusal (P140).** A host that follows no
52
+ selection drops it unread, as 0.14.14 did, instead of counting a malformed one as `invalid`.
53
+ - **Security (P140):** a narrowing: less drawn and less kept for a host that doesn't follow, and a
54
+ page's word read by fewer hosts. No CSP, sandbox, egress or gate changes; control
55
+ `track-selection-checks` covers the unread drop too.
56
+
7
57
  ## 0.14.15
8
58
 
9
59
  - **Annotations: the selection followed (P138).** `annotations.track({ selection: true })` (React:
@@ -76,11 +76,20 @@ export interface AnnotateMode {
76
76
  readonly elements?: boolean | "hold";
77
77
  /** Text, by selecting it: each settled selection is reported, and its clearing. */
78
78
  readonly text?: boolean;
79
+ /**
80
+ * That you follow what is selected (P140): `annotations.track({ selection: true })` once
81
+ * `selected` comes (React sets it while `trackedSelection` is given). Only then does the frame
82
+ * keep it for you to follow, the element just picked outlined until the follow takes over. Without
83
+ * it the frame keeps nothing and a pick's outline goes with the pick, as before 0.14.15; a follow
84
+ * asked before the pick still follows each selection reported while it lasts.
85
+ */
86
+ readonly keepSelection?: boolean;
79
87
  }
80
88
  /**
81
89
  * What `annotations.track` follows (P112, P138): a shown mark, by its id; the selection the frame
82
90
  * last reported as `selected` (the element picked, or the words selected), highlighted in the
83
- * frame while followed; or nothing (`null`). One at a time: each replaces the last.
91
+ * frame while followed, and kept for a follow asked after `selected` only under `start`'s
92
+ * `keepSelection` (P140); or nothing (`null`). One at a time: each replaces the last.
84
93
  */
85
94
  export type AnnotationTrackTarget = string | {
86
95
  readonly selection: true;
@@ -34,8 +34,15 @@ export declare function inViewport(rect: AnnotationRect, viewport: {
34
34
  } | null | undefined): boolean;
35
35
  /** A report from the frame, checked; null if malformed (it is then dropped). */
36
36
  export declare function parseReport(value: unknown): AnnotationReport | null;
37
- /** What the host may start with: elements, text, or both (default both). */
38
- export declare function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateMode>;
37
+ /** A mode as the frame gets it: `keepSelection` only where it is true (P140). */
38
+ export type StartedMode = Required<Omit<AnnotateMode, "keepSelection">> & {
39
+ readonly keepSelection?: true;
40
+ };
41
+ /**
42
+ * What the host may start with: elements, text, or both (default both); and whether it follows
43
+ * what is selected (`keepSelection`, P140).
44
+ */
45
+ export declare function annotateMode(mode: AnnotateMode | undefined): StartedMode;
39
46
  /**
40
47
  * Whether a mark gets a marker, the one thing a person can click (P104): one with a `count`, and
41
48
  * every draft (P107).
@@ -286,16 +286,23 @@ export function parseReport(value) {
286
286
  return null;
287
287
  }
288
288
  }
289
- /** What the host may start with: elements, text, or both (default both). */
289
+ /**
290
+ * What the host may start with: elements, text, or both (default both); and whether it follows
291
+ * what is selected (`keepSelection`, P140).
292
+ */
290
293
  export function annotateMode(mode) {
291
294
  const elements = mode?.elements ?? true;
292
295
  const words = mode?.text ?? true;
296
+ const keep = mode?.keepSelection ?? false;
293
297
  if ((typeof elements !== "boolean" && elements !== "hold") ||
294
298
  typeof words !== "boolean" ||
295
299
  (elements === false && !words)) {
296
300
  throw new TypeError("annotations.start: elements, text, or both");
297
301
  }
298
- return { elements, text: words };
302
+ if (typeof keep !== "boolean") {
303
+ throw new TypeError("annotations.start: keepSelection is true or false");
304
+ }
305
+ return { elements, text: words, ...(keep ? { keepSelection: true } : {}) };
299
306
  }
300
307
  /**
301
308
  * Whether a mark gets a marker, the one thing a person can click (P104): one with a `count`, and