@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
package/CHANGELOG.md CHANGED
@@ -4,6 +4,95 @@
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.16.0
8
+
9
+ **Breaking.** What guessed at the person's intent is taken out (P149; supersedes P111, P114,
10
+ P120, P122, P136, P148, and parts of P105, P109, P121, P123). It began with a host's report
11
+ that a page's own comment button, pressed by a real person, was refused ("This needs a click"):
12
+ the checks below ran on a guess at where the person was, each release made the guess larger,
13
+ and none of them protected more than the moment a page asks. No isolation wall changes: origins,
14
+ sandboxes, CSP, tickets, the door and every message check are as in 0.15.3.
15
+
16
+ - **No proof of a click is asked, except for `copyText`.** Default gates: `sendPrompt`,
17
+ `openLink` and `downloadFile` are `confirm` and 30 a minute (they had no rate); `comments` is
18
+ 30 a minute alone; `artifact.publish` and `assets.delete` are `confirm`. A page may call them
19
+ as it loads or on a timer: each still ends at the person's confirmation, or at a composer that
20
+ posts nothing by itself, and declines still mute the display. A marker's `activated` is taken
21
+ with or without a gesture (a view it opens still takes no press for 500 ms: that is your
22
+ view's guard, ADOPTING § Annotations). `copyText` keeps its click. The `user-activation` gate
23
+ stays in the vocabulary: name it for any capability (`gates`) or method (`methodGates`) to get
24
+ 0.15's default back for it. `CapabilitySpec.inFrame` is gone.
25
+ **For a host:** remove any `gates` override you wrote only to drop `user-activation`; the
26
+ default is now what you overrode to, plus the rate. A handler for `comments` is asked more
27
+ freely: answer `false` while the person is writing, and space out or refuse a page whose opens
28
+ the person keeps closing. The manual and the typed runtime (`types/runtime/v1`) no longer say
29
+ "call it from a click" for these.
30
+ - **The focus guard is removed.** A display that takes the keyboard keeps it until the person
31
+ clicks back (the accepted risk of THREAT_MODEL §5; the guard could not hold it and refused
32
+ people's own clicks). Gone: the `focusTaken` event, `PortholeFrame`'s and `PortholeView`'s
33
+ `onFocusTaken`, `Surface.onFocusTaken`, the "kept taking the keyboard" content error.
34
+ `display.focus()` is the frame's own `focus()`. `focusField(field)` stays, as a plain helper.
35
+ `Surface.focused`, optional, is read by the find shortcut alone.
36
+ **For a host:** delete your `focusTaken` / `onFocusTaken` handlers. Nothing else to do.
37
+ - **Nested pages are removed** (`nested: true`). The config field is refused as unknown. Gone
38
+ from the main entry: `SHELL_STATE_METHOD`, `SHELL_GESTURE_MS`, `PAGE_SANDBOX_TOKENS`. Gone from
39
+ `/server`: `isNestedLabel`, `nestedLabelOf`, `nestedShellResponse`, `nestedShellCsp`,
40
+ `nestedFileCsp`, `nestedAncestors`, `NESTED_FILE_HEADERS`, `NESTED_FILES_PREFIX`. The
41
+ `porthole-` label prefix stays reserved (`PORTHOLE_LABEL_PREFIX`).
42
+ **For a host that used `nested: true`:** go back to a served page.
43
+ 1. Remove `nested: true` from the kind's options. The page is then framed on its scope's own
44
+ label, as every served artifact is, with `allow-same-origin`: it has that origin's storage
45
+ again (`localStorage` lasts; set `served.storage` as you would for any served kind), and
46
+ the asset library and Porthole's libraries, which nested pages never had.
47
+ 2. A nested page was opaque to its scope's other displays. A served one shares its scope's
48
+ origin with them (THREAT_MODEL S7): if displays in one scope must not reach each other,
49
+ give them different scopes.
50
+ 3. A content Worker of your own: drop the routes for the shell's label
51
+ (`porthole-<…>.<domain>`) and the calls to the helpers above; `/server` users have nothing
52
+ to change. An edge route for that label can go too.
53
+ 4. Do step 1 before you upgrade: 0.15 serves the kind as a served page once the field is
54
+ gone, on both sides, and 0.16.0 refuses a config that still has it.
55
+ - **The page runtime.** The shell runtime every served document inlines is 0.15.2's without the
56
+ nested-only renewal hook (nine lines); `use` and `legacy` are unchanged. A page published
57
+ under 0.15 runs under 0.16 unchanged, and its calls that needed a click no longer need one.
58
+ - **Conformance.** `12.prompt-gesture-confirm` is `12.prompt-confirm` (a prompt on load is
59
+ asked, and a no sends nothing); `12.raw-message` now expects a raw `ui/message` to be asked
60
+ too; `12.raw-copy` is new (a raw copy with no click is refused by the host). 28 negative
61
+ controls are removed with the code they weakened.
62
+ - **The find shortcut in a shadow root.** `focused` reads the `activeElement` of the frame's own
63
+ root, so a display mounted inside a shadow root no longer reads as unfocused.
64
+
65
+ ## 0.15.3
66
+
67
+ - **A nested page's real presses count, each of them** (P148, amends P111). A nested page's shell
68
+ knew of a press in the page only as its own activation turning on, and an activation stays on
69
+ for 5 s: a second press in that time, or a press within 5 s of one on the host's page (a
70
+ dialog's Cancel), turned nothing on, and `comments.open` from it was refused ("This needs a
71
+ click"), or a move into the page taken back. The page's runtime now tells its shell each press
72
+ the browser itself made (a mouse down; a finger or pen up; Enter or Space, not held, on a native
73
+ control that isn't editable; a click on one), over a `MessagePort` the shell sends at each load
74
+ and the runtime takes before any content runs. The shell says when it heard the last
75
+ (`porthole/shell/state`: `pressed`, `presses`), and the host takes it as it takes the
76
+ activation turning on: for a second, with no press or key on the host's page since, and under
77
+ P120's and P122's rules. Nothing a page dispatches is a press, no click while a key is down is
78
+ one, and no content holds the port;
79
+ where the runtime can't install all of it, nothing is told and P111's rule stands alone.
80
+ Only for nested pages (`nested: true`): a served page that isn't nested is as before, and in
81
+ full Chromium ADOPTING's advice for it stands (nest it).
82
+ **For a host:** no API change. The nested shell's script and the shell runtime every served
83
+ document inlines change (the nested shell's `script-src` hash with it; `nestedShellResponse`
84
+ and `/server` compute it, as before). Both sides need 0.15.3 for the change to show: the host's
85
+ page (`createHost`) and whatever serves the content origins. Either side alone behaves as
86
+ 0.15.2.
87
+ - **The helpers that take host origins check them** (amends P145, after the audit of 0.15.1).
88
+ `statusPage`, `doorResponse`, `doorStatusResponse` and `nestedShellCsp` took `hostOrigins`
89
+ unchecked: `:0` passed, and a string with a `;` went into the CSP header as written. They are a
90
+ host's own configuration, never content's; each helper now throws a `TypeError` on one
91
+ `hostOriginProblem` refuses, as `createServer` and the host kit already did. `isHostOrigin` now
92
+ refuses what `hostOriginProblem` does (it took `:0`, a port past 65535 and a host the URL parser
93
+ rewrites). **For a host:** a content Worker of your own that passed a malformed origin to one of
94
+ these now gets an error where it got a header no browser would match.
95
+
7
96
  ## 0.15.2
8
97
 
9
98
  - **Marks ride the document's scroll** (P147, amends P104 and P132). A commented passage's
@@ -14,8 +14,7 @@ import type { CapabilityHandlers, Confirm, ConfirmDisplay, Consent, DataCache, H
14
14
  * every capability its host function's own rate (P091, P095) → arguments well formed and within
15
15
  * their limits → who may (P087: the level of each method the call runs for the viewer, a page's
16
16
  * named data with or without a viewer, db's rules) → not muted, if confirm-gated → the own rate
17
- * of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so (and
18
- * for `comments`, the host page's focus in the calling frame: P109) → the
17
+ * of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so → the
19
18
  * viewer's consent, if gated so → a person's confirmation, if gated so (at most 10 waiting) →
20
19
  * shown to the person, if gated so (P100) → the handler (or, for a read, a result the host already
21
20
  * gave for it, or for a stale-allowed one the host's cache).
@@ -67,12 +66,6 @@ export interface BridgeOptions {
67
66
  readonly cached?: DataCache;
68
67
  /** Whether the embedding page has user activation now; undefined where it can't tell. */
69
68
  readonly userActivation?: () => boolean | undefined;
70
- /**
71
- * Whether the embedding page's focus is in this display's frame now (P109); undefined where it
72
- * can't tell. A capability whose gesture must be in its frame (`inFrame`: `comments`) is refused
73
- * without it.
74
- */
75
- readonly focused?: () => boolean | undefined;
76
69
  readonly onEvent: (event: BridgeEvent) => void;
77
70
  /** The clock, in milliseconds (tests pass their own). */
78
71
  readonly now?: () => number;
@@ -13,8 +13,6 @@ import { atLeast, higher } from "../runtime/levels.js";
13
13
  import { isCodeAsset, parseArtifactRequest, parseAssetRequest, parseCommentRequest, } from "../runtime/requests.js";
14
14
  import { defaultReason, isRefused, pendingReason, reasonOf, } from "./refusal.js";
15
15
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
16
- /** Whether `capability`'s gesture must be in its own frame (P109: the host page's focus there). */
17
- const inFrame = (capability) => capabilitySpec(capability).inFrame === true;
18
16
  const MAX_URL = 4_096;
19
17
  /**
20
18
  * The most confirmations one display has waiting at once (P095): past it a call is refused as
@@ -452,11 +450,6 @@ export function createBridge(options) {
452
450
  if (activated === false) {
453
451
  return refuse(capability, "no-user-activation");
454
452
  }
455
- // A gesture in this frame, not anywhere on the host's page (P109): the person typing in
456
- // the host's composer gives its page activation, which a frame's call would borrow.
457
- if (inFrame(capability) && options.focused?.() === false) {
458
- return refuse(capability, "no-user-activation");
459
- }
460
453
  }
461
454
  if (gates.includes("consent")) {
462
455
  const consent = options.consent;