@botiverse/porthole 0.13.0 → 0.14.1
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.
- package/CHANGELOG.md +770 -0
- package/dist/annotate/types.d.ts +36 -4
- package/dist/annotate/types.js +6 -0
- package/dist/annotate/validate.d.ts +2 -1
- package/dist/annotate/validate.js +30 -6
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.d.ts +7 -0
- package/dist/compile/policy.js +13 -1
- package/dist/config/schema.d.ts +11 -0
- package/dist/config/validate.js +19 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +3 -1
- package/dist/guide/limits.js +1 -1
- package/dist/host/create-host.d.ts +2 -0
- package/dist/host/create-host.js +78 -3
- package/dist/host/pass-on.d.ts +15 -0
- package/dist/host/pass-on.js +65 -0
- package/dist/host/types.d.ts +29 -0
- package/dist/index.d.ts +4 -1
- package/dist/index.js +4 -1
- package/dist/isolation/types.d.ts +8 -0
- package/dist/isolation/types.js +8 -0
- package/dist/platform/focus-guard.d.ts +71 -2
- package/dist/platform/focus-guard.js +187 -12
- package/dist/platform/types.d.ts +8 -1
- package/dist/platform/web.js +60 -4
- package/dist/presets/presets.d.ts +2 -0
- package/dist/presets/presets.js +1 -0
- package/dist/react/frame.d.ts +4 -3
- package/dist/server/files.js +19 -3
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +5 -0
- package/dist/server/naming.js +4 -0
- package/dist/server/nested.d.ts +59 -0
- package/dist/server/nested.js +96 -0
- package/dist/server/server.js +193 -23
- package/dist/server/types.d.ts +5 -0
- package/dist/shell/annotate.d.ts +4 -3
- package/dist/shell/annotate.js +179 -9
- package/dist/shell/frame.d.ts +45 -0
- package/dist/shell/frame.js +250 -0
- package/dist/shell/plan.js +2 -1
- package/dist/shell/runtime.d.ts +6 -0
- package/dist/shell/runtime.js +60 -15
- package/docs/ADOPTING.md +85 -2
- package/docs/ARCHITECTURE.md +28 -0
- package/docs/DECISIONS.md +416 -1
- package/docs/DESIGN.md +21 -4
- package/docs/THREAT_MODEL.md +102 -5
- package/package.json +6 -5
- package/src/annotate/types.ts +32 -4
- package/src/annotate/validate.ts +34 -8
- package/src/compile/policy.ts +14 -1
- package/src/config/schema.ts +11 -0
- package/src/config/validate.ts +23 -0
- package/src/displays/displays.ts +3 -1
- package/src/guide/limits.ts +1 -1
- package/src/host/create-host.ts +81 -4
- package/src/host/pass-on.ts +73 -0
- package/src/host/types.ts +27 -0
- package/src/index.ts +4 -1
- package/src/isolation/types.ts +12 -0
- package/src/platform/focus-guard.ts +258 -15
- package/src/platform/types.ts +8 -1
- package/src/platform/web.ts +81 -9
- package/src/presets/presets.ts +3 -0
- package/src/react/frame.tsx +4 -3
- package/src/server/files.ts +19 -3
- package/src/server/index.ts +14 -0
- package/src/server/naming.ts +4 -0
- package/src/server/nested.ts +116 -0
- package/src/server/server.ts +224 -21
- package/src/server/types.ts +5 -0
- package/src/shell/annotate.ts +179 -9
- package/src/shell/frame.ts +268 -0
- package/src/shell/plan.ts +2 -1
- package/src/shell/runtime.ts +61 -15
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.
|
|
8
|
+
**Status.** This describes Porthole 0.14.1 (2026-10-28). A review on 2026-10-19 found gaps, and every decision it led to
|
|
9
9
|
has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
|
|
10
10
|
and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
11
|
annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
|
|
@@ -16,7 +16,13 @@ around it). The review of 0.12.0's drafts led to P109, in 0.13.0: a display can
|
|
|
16
16
|
`createHost` now gives back (§6, §7 "The keyboard"); `comments.open` needs the person in the
|
|
17
17
|
calling frame; a page's draft text is stricter, and the composer it fills is the person's to act
|
|
18
18
|
on (§7). 0.13.0 also makes P106's lint fail soft and read only what it may (P110, no change to
|
|
19
|
-
isolation).
|
|
19
|
+
isolation). 0.14.0 adds a nested page (P111, `nested: true`, S3): the framed address is Porthole's
|
|
20
|
+
shell alone and the page its opaque child, so a realm the page can't reach tells the host when the
|
|
21
|
+
person, not the page, pressed in it (§7 "The keyboard", `comments`); and P112's annotation
|
|
22
|
+
additions for a host's comment modes (hints, as every report is, §7). 0.14.1: P114
|
|
23
|
+
(porthole#56) serves a nested page's shell on a label of its own, on which nothing but nested
|
|
24
|
+
pages' shells, their pages, those pages' files and status pages is ever served, so no other
|
|
25
|
+
display of the scope is same-origin with the shell (S3).
|
|
20
26
|
|
|
21
27
|
## 1. Two layers
|
|
22
28
|
|
|
@@ -162,6 +168,15 @@ Whatever the use:
|
|
|
162
168
|
nothing one click away that posts, submits, resolves, deletes or discards (a draft's view, P107,
|
|
163
169
|
included: no "Post" or "Submit review" in it). Its menus and popovers are part of it, portaled
|
|
164
170
|
ones too (P105; ADOPTING.md § Annotations has the code: the view `inert` while it arms).
|
|
171
|
+
One exception to "takes no focus" (P112): in a comment mode the person started themselves (the
|
|
172
|
+
host's own control, never a report), a composer their selection opens (`selected`) may take
|
|
173
|
+
focus, with `focusField`, if all it can do is save a draft: nothing in it posts, submits or sends,
|
|
174
|
+
Enter in it only adds the draft to the batch (submitting is only ever the host's own "Submit N"
|
|
175
|
+
control, outside the composer), it shows plainly that it is a draft (so the person can see where
|
|
176
|
+
their keys are going), and the rest of this guard holds (no press for 500 ms, beside the frame). The page still chooses
|
|
177
|
+
when `selected` comes, so what it can do with that moment is put the person's next keys into a
|
|
178
|
+
draft they see and can discard, never send one; outside such a mode, or for a composer that can
|
|
179
|
+
send, it takes no focus.
|
|
165
180
|
- Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
|
|
166
181
|
likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
|
|
167
182
|
`createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
|
|
@@ -322,6 +337,40 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
|
|
|
322
337
|
worker; a page's CSP opens its own version's path, not its whole origin.
|
|
323
338
|
- With a per-request check (`authorize`), the host decides again on every request; a deny is a
|
|
324
339
|
403 that says `denied`.
|
|
340
|
+
- A nested page (`nested: true`, P111): the framed address answers Porthole's shell alone, its
|
|
341
|
+
script the only one its CSP runs, framing and fetching only the origin's sealed files' prefix.
|
|
342
|
+
**The shell's origin hosts nothing but the shell, its opaque page, the sealed files and status
|
|
343
|
+
pages** (P114, porthole#56): the shell, the page and its files are served on a label of the
|
|
344
|
+
scope's own, `porthole-<24 base32>` (`nestedLabelOf`), never on the scope's label, where its
|
|
345
|
+
other displays (inline and live widgets, MCP apps, artifacts that aren't nested) run agent-made
|
|
346
|
+
content with `allow-same-origin`. `/server` holds it: that label answers no clean address,
|
|
347
|
+
entry, asset, library, app or other display, and takes no other instance's ticket, cookie or
|
|
348
|
+
sealed address; the scope's label answers no nested page (its clean address goes on to the
|
|
349
|
+
shell's label with a one-time ticket); no host's naming makes a `porthole-` label. So no
|
|
350
|
+
content, of any scope, can read the shell's realm (its word to the host, the page's sealed
|
|
351
|
+
address) or drive it (`leak/served/nested-siblings.spec.ts`, negative control `shell-label`).
|
|
352
|
+
The page is the shell's child, `sandbox="allow-scripts"` (never `allow-same-origin`, held by a
|
|
353
|
+
static check over every sandbox Porthole writes) and the same sandbox in its own CSP, so it is an
|
|
354
|
+
opaque origin in its frame and on a tab; it is loaded, and loads its files, at its sealed address
|
|
355
|
+
without a cookie, and its files then carry `Cross-Origin-Resource-Policy: cross-origin` and
|
|
356
|
+
`Access-Control-Allow-Origin: *` (an opaque page's own loads are cross-origin: the address is
|
|
357
|
+
the access, never the request's origin). So whoever holds a page's sealed address can read its
|
|
358
|
+
files from any origin, a page of their own included, until the address ends (an hour on its own,
|
|
359
|
+
P083): it is a bearer credential, as safe as it is unleaked. Porthole keeps it out of what it
|
|
360
|
+
says: no referrer goes with any load (`Referrer-Policy: no-referrer`, the shell's frame
|
|
361
|
+
`referrerpolicy="no-referrer"`), the host's reports name it as `./` (P083), and the shell's own
|
|
362
|
+
answer is `no-store`. The page itself can read it (its address) and so pass it on by any channel
|
|
363
|
+
it has, as it can pass on its files' bytes. The page has none of the origin's storage, and nothing
|
|
364
|
+
of the shell's realm: messages between them go by `postMessage`, the page's trusted by
|
|
365
|
+
`event.source`, and the shell drops what the page says in the shell's own namespace. Only the
|
|
366
|
+
shell (same-origin) renews the page's address; a module the page loaded keeps one that ends
|
|
367
|
+
within the hour. Every answer below the sealed prefix carries a CSP sandbox, never
|
|
368
|
+
`allow-same-origin` (a page's `allow-scripts`, every other file's runs nothing): a file opened on
|
|
369
|
+
a tab of its own (an SVG or XML file with a script) is opaque, never the shell's origin (negative
|
|
370
|
+
control `file-sandbox`). The sandbox refuses no worker (measured on the four engines): a nested
|
|
371
|
+
page's workers come from Blob URLs (a worker from its set's own script is refused by its opaque
|
|
372
|
+
origin, sandbox or not), and those load the set's scripts. Assets and Porthole's libraries aren't
|
|
373
|
+
served to a nested page yet.
|
|
325
374
|
|
|
326
375
|
**The host must**
|
|
327
376
|
|
|
@@ -335,6 +384,10 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
|
|
|
335
384
|
uncached (the default; `authorizeTtlSeconds` in the host kit) or call `content.forget(…)` when
|
|
336
385
|
revoking, or a cached answer holds for up to that long.
|
|
337
386
|
- Send the page's `frame-src`.
|
|
387
|
+
- With nested pages, route the shell's label (`porthole-<…>.<domain>`) to the content server as
|
|
388
|
+
every content label is (a wildcard needs nothing; a pattern of the host's own, `a-*`, must add
|
|
389
|
+
it). A content Worker of the host's own serves nested pages on that label alone, and nothing
|
|
390
|
+
else there (P114).
|
|
338
391
|
|
|
339
392
|
**Not guaranteed**
|
|
340
393
|
|
|
@@ -556,7 +609,8 @@ wall on three engines, and `defineHostConformance` runs it against a host's own
|
|
|
556
609
|
effects are its own), and group displays by page (S7).
|
|
557
610
|
|
|
558
611
|
**Annotations** (`annotate`, P053, P104, P107). The shell that draws marks and reports anchors shares
|
|
559
|
-
its realm with the content
|
|
612
|
+
its realm with the content (a nested page's too: its marks are drawn by the runtime in the page's
|
|
613
|
+
own frame, below the shell, P111), so:
|
|
560
614
|
|
|
561
615
|
- *What content learns.* Everything the host sends in a `show` is posted into the frame's window,
|
|
562
616
|
where the content can listen: each mark's id, anchor and, where given, `count` (the number on
|
|
@@ -634,6 +688,15 @@ its realm with the content, so:
|
|
|
634
688
|
`Element.prototype.matches` on them), so content can reach the closed shadow root that way,
|
|
635
689
|
read the markers and rewrite them (the review of P104, on all three engines). Nothing in the
|
|
636
690
|
layer is secret: it holds only what `show` sent, which the content can read anyway.
|
|
691
|
+
- *Clearing the selection* (P115). `annotations.clearSelection()` is the host's word to the frame
|
|
692
|
+
(`porthole/annotate.clearSelection`), with nothing back: the shell takes the page's selection
|
|
693
|
+
away through `Selection.prototype.removeAllRanges` as it was before content ran (control
|
|
694
|
+
`clear-selection`: a page that replaced it keeps its selection otherwise) and forgets the one it
|
|
695
|
+
told, so the clear makes no `unselected` or `selected`. It goes host to frame only: the host
|
|
696
|
+
takes no such message from a frame, and the shell takes it only from its frame's parent (a page
|
|
697
|
+
that posts it to its own window is dropped). It gives the page nothing new: a page can clear or
|
|
698
|
+
select its own text at any time, and can select the words again right after a clear (the host
|
|
699
|
+
hears that as any selection, while it asked for text).
|
|
637
700
|
- *What content can always do.* Hide, shrink, move or cover the layer (its scripts can rewrite the
|
|
638
701
|
layer's style, lay elements over it, or transform the page it sits in), change its words so a
|
|
639
702
|
mark is orphaned, or flood the shared rate so real reports are refused. It can also make the
|
|
@@ -692,6 +755,35 @@ unposted words beside the frame and tell the page when.
|
|
|
692
755
|
technology's activation within 5 s of their key or press on the page): focus goes back, and
|
|
693
756
|
their next press once the pointer has left the frame and come back, a Tab, or an activation 5 s
|
|
694
757
|
later keeps it.
|
|
758
|
+
- *Full Chromium* (P111, measured on Chromium 153, not the headless shell): a cross-site frame is
|
|
759
|
+
out of process, and the host's page sees nothing of a press in it (no `:active`, no `:hover`, no
|
|
760
|
+
pointer event past the frame's edge). For a served page that isn't nested, a person's real click
|
|
761
|
+
into its field is taken back every time there (the display stopped at the third), and
|
|
762
|
+
`comments.open` from a real click is refused within 5 s of any input on the host's page
|
|
763
|
+
(porthole#53). Nest it.
|
|
764
|
+
- *A nested page* (P111): the guard asks the page's shell, a realm the page can't reach above its
|
|
765
|
+
frame, whose transient activation turns on only from a press or key in the page (activation goes
|
|
766
|
+
up, never down). A move into the frame is the person's if the shell's activation turned on within
|
|
767
|
+
the last second and the host's page had no trusted press or key since; or a Tab, the host's own
|
|
768
|
+
move, or a press the engine shows on the frame element. Nothing else counts: no pointer over the
|
|
769
|
+
frame, no host-wide activation. A move the shell hasn't spoken of yet waits for its word (its next
|
|
770
|
+
frame) at most 500 ms, then is taken back. Measured on full Chromium, the headless shell, WebKit
|
|
771
|
+
and Firefox (`leak/served/nested.spec.ts`): a real click into the page's field keeps the
|
|
772
|
+
keyboard; the page's `focus()` as it loads, on a timer while the person types, right after a
|
|
773
|
+
click on the host's own button, 1.2 to 4.5 s after the person paused typing, and 700 ms after
|
|
774
|
+
they pressed it and went back to the composer is taken back; what a page says in the shell's
|
|
775
|
+
name, to its parent or to the host's window, moves nothing (negative controls `shell-namespace`,
|
|
776
|
+
`shell-host-input`). *What doesn't*: a press in the page within 5 s of the last one turns no
|
|
777
|
+
activation on, so a second move into it after the person went back to the host's page is taken
|
|
778
|
+
back until 5 s after their last press or key in the page, or they Tab in; the page gets the keys
|
|
779
|
+
typed while a move waits for the shell's word; a shell without `navigator.userActivation` leaves
|
|
780
|
+
0.13's rule. A page that holds the thread it shares with its shell (WebKit; Firefox and Chromium
|
|
781
|
+
where the frames share a process) from its own click handler would push the moment the shell sees
|
|
782
|
+
its activation past the person's next keys on the host's page: so the shell looks and beats every
|
|
783
|
+
50 ms and says how long it went without a look, and an activation it reports after a stall of over
|
|
784
|
+
100 ms (its own, or no word heard) is no one's gesture until it lapses (P111, after its review;
|
|
785
|
+
negative control `shell-stall`). The cost: in those engines a page that keeps its thread busy has
|
|
786
|
+
the person's real click taken for uncertain until it is idle.
|
|
695
787
|
|
|
696
788
|
### The app runtime
|
|
697
789
|
|
|
@@ -727,7 +819,11 @@ section.
|
|
|
727
819
|
- `comments` is write-only: the page learns only whether the composer opened. It opens only from
|
|
728
820
|
a gesture with the host page's focus in the calling frame (P109: a press in it or a Tab into it;
|
|
729
821
|
not the person typing in the host's UI, nor a gesture in another display; negative control
|
|
730
|
-
`comments-in-frame`).
|
|
822
|
+
`comments-in-frame`). In a nested page (P111) it opens too while the page's shell saw the
|
|
823
|
+
person's gesture within the last second, with no press or key on the host's page since: a real
|
|
824
|
+
click on the page's button a moment after typing in the host's composer opens it, on full
|
|
825
|
+
Chromium too (porthole#53); with no click it is refused, whatever the page says in the shell's
|
|
826
|
+
name. A draft it gives (P108) is at most 2,000 characters of text a person can
|
|
731
827
|
see (P109): nothing invisible (zero-width characters, bidi and tag characters, controls but a
|
|
732
828
|
new line and a tab; U+200C and U+200D only between two letters or marks, where Persian and the
|
|
733
829
|
Indic scripts need them, never first, last, doubled, beside a space or punctuation, or in an
|
|
@@ -796,7 +892,8 @@ section.
|
|
|
796
892
|
The decisions below come from the 2026-10-19 review, and all of them have merged. Each row says
|
|
797
893
|
what was wrong, what holds now, and the limit its decision accepts, if any. Later reviews' decisions
|
|
798
894
|
are in the status line and in DECISIONS.md: P105 (after the review of P104), P109 (after the review
|
|
799
|
-
of 0.12.0's drafts).
|
|
895
|
+
of 0.12.0's drafts), P111 (a nested page, S3; in 0.14.0), P114 (a nested page's shell on a label of
|
|
896
|
+
its own, after porthole#56; in 0.14.1).
|
|
800
897
|
|
|
801
898
|
| Decision | State | What it closes | Sections |
|
|
802
899
|
| --- | --- | --- | --- |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.1",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -22,6 +22,7 @@
|
|
|
22
22
|
"docs",
|
|
23
23
|
"examples",
|
|
24
24
|
"README.md",
|
|
25
|
+
"CHANGELOG.md",
|
|
25
26
|
"THIRD_PARTY_NOTICES.md"
|
|
26
27
|
],
|
|
27
28
|
"type": "module",
|
|
@@ -65,10 +66,10 @@
|
|
|
65
66
|
}
|
|
66
67
|
},
|
|
67
68
|
"devDependencies": {
|
|
68
|
-
"@modelcontextprotocol/ext-apps": "2.0.
|
|
69
|
-
"@modelcontextprotocol/server-basic-react": "2.0.
|
|
70
|
-
"@modelcontextprotocol/server-basic-vanillajs": "2.0.
|
|
71
|
-
"@modelcontextprotocol/server-threejs": "2.0.
|
|
69
|
+
"@modelcontextprotocol/ext-apps": "2.0.4",
|
|
70
|
+
"@modelcontextprotocol/server-basic-react": "2.0.4",
|
|
71
|
+
"@modelcontextprotocol/server-basic-vanillajs": "2.0.4",
|
|
72
|
+
"@modelcontextprotocol/server-threejs": "2.0.4",
|
|
72
73
|
"@playwright/test": "1.63.0",
|
|
73
74
|
"@types/node": "26.6.3",
|
|
74
75
|
"@types/react": "19.3.0",
|
package/src/annotate/types.ts
CHANGED
|
@@ -63,8 +63,13 @@ export interface AnnotationRect {
|
|
|
63
63
|
|
|
64
64
|
/** What the person may point at while the host is asking. */
|
|
65
65
|
export interface AnnotateMode {
|
|
66
|
-
/**
|
|
67
|
-
|
|
66
|
+
/**
|
|
67
|
+
* Elements, picked with a click or tap (the one under the pointer is outlined); one pick. Or
|
|
68
|
+
* `"hold"` (P112): a finger held still on a block for 500 ms selects it (reported as `selected`,
|
|
69
|
+
* and the click its release makes never reaches the page); every other tap, and any mouse, is the
|
|
70
|
+
* page's; it lasts until the host stops it.
|
|
71
|
+
*/
|
|
72
|
+
readonly elements?: boolean | "hold";
|
|
68
73
|
/** Text, by selecting it: each settled selection is reported, and its clearing. */
|
|
69
74
|
readonly text?: boolean;
|
|
70
75
|
}
|
|
@@ -79,7 +84,8 @@ export interface AnnotationMark {
|
|
|
79
84
|
readonly anchor: AnnotationAnchor;
|
|
80
85
|
/**
|
|
81
86
|
* A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
|
|
82
|
-
* `ANNOTATION_LIMITS.count
|
|
87
|
+
* `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0 draws
|
|
88
|
+
* the bubble alone) at the end of a
|
|
83
89
|
* text anchor and the top right of an element. The person can click it: the frame reports
|
|
84
90
|
* `activated`. The content can read the number; give one only where the page may know it. A
|
|
85
91
|
* draft's is dropped (P107): its marker has no number.
|
|
@@ -106,6 +112,12 @@ export interface AnchorResult {
|
|
|
106
112
|
readonly state: AnchorState;
|
|
107
113
|
/** Where it is now, when attached. */
|
|
108
114
|
readonly rect?: AnnotationRect;
|
|
115
|
+
/**
|
|
116
|
+
* Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
|
|
117
|
+
* marks included, for a host that lists marks in reading order. The content's word: an order to
|
|
118
|
+
* sort by, never a fact.
|
|
119
|
+
*/
|
|
120
|
+
readonly order?: number;
|
|
109
121
|
}
|
|
110
122
|
|
|
111
123
|
/** What the frame reports, once the host has checked it. */
|
|
@@ -118,7 +130,11 @@ export type AnnotationReport =
|
|
|
118
130
|
}
|
|
119
131
|
/** The text selection went away. */
|
|
120
132
|
| { readonly type: "unselected" }
|
|
121
|
-
/**
|
|
133
|
+
/**
|
|
134
|
+
* The person pressed Escape while picking an element (the pick ends), or while selecting text
|
|
135
|
+
* (P112: the page keeps the key; the host decides what ends). The page's word too: a page can
|
|
136
|
+
* send it, and the host takes it only while it asked for a pick or for text.
|
|
137
|
+
*/
|
|
122
138
|
| { readonly type: "cancelled" }
|
|
123
139
|
/**
|
|
124
140
|
* Where the marked anchors are now: every mark after `show`, the focused one after `focus`,
|
|
@@ -128,6 +144,12 @@ export type AnnotationReport =
|
|
|
128
144
|
* host was last told, at most once a second (P104).
|
|
129
145
|
*/
|
|
130
146
|
| { readonly type: "anchored"; readonly results: readonly AnchorResult[] }
|
|
147
|
+
/**
|
|
148
|
+
* The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
|
|
149
|
+
* an animation frame where it moved: at most 60 a second, for that mark only, clamped to the
|
|
150
|
+
* frame. The content's word: where to put a card beside it, nothing more.
|
|
151
|
+
*/
|
|
152
|
+
| { readonly type: "tracked"; readonly id: string; readonly rect: AnnotationRect }
|
|
131
153
|
/**
|
|
132
154
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
133
155
|
* (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
|
|
@@ -155,6 +177,12 @@ export const ANNOTATE_METHODS = {
|
|
|
155
177
|
anchored: "porthole/annotate.anchored",
|
|
156
178
|
/** Frame → host: a mark's marker was clicked (P104). */
|
|
157
179
|
activated: "porthole/annotate.activated",
|
|
180
|
+
/** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
|
|
181
|
+
track: "porthole/annotate.track",
|
|
182
|
+
/** Frame → host: the followed mark's box, as it moves (P112). */
|
|
183
|
+
tracked: "porthole/annotate.tracked",
|
|
184
|
+
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
185
|
+
clearSelection: "porthole/annotate.clearSelection",
|
|
158
186
|
} as const;
|
|
159
187
|
|
|
160
188
|
/** The most of each part of an anchor or report the host takes. */
|
package/src/annotate/validate.ts
CHANGED
|
@@ -155,7 +155,20 @@ function results(value: unknown): AnchorResult[] | null {
|
|
|
155
155
|
if (rect === null) {
|
|
156
156
|
return null;
|
|
157
157
|
}
|
|
158
|
-
|
|
158
|
+
// A place among the marks (P112): a whole number below the most marks a show carries.
|
|
159
|
+
const order = each.order;
|
|
160
|
+
if (
|
|
161
|
+
order !== undefined &&
|
|
162
|
+
!(typeof order === "number" && Number.isInteger(order) && order >= 0 && order < LIMITS.marks)
|
|
163
|
+
) {
|
|
164
|
+
return null;
|
|
165
|
+
}
|
|
166
|
+
out.push({
|
|
167
|
+
id: each.id,
|
|
168
|
+
state: "attached",
|
|
169
|
+
...(rect === undefined ? {} : { rect }),
|
|
170
|
+
...(order === undefined ? {} : { order }),
|
|
171
|
+
});
|
|
159
172
|
}
|
|
160
173
|
return out;
|
|
161
174
|
}
|
|
@@ -183,6 +196,10 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
183
196
|
const rect = parseRect(value.rect);
|
|
184
197
|
return !markId(value.id) || rect === null ? null : { type: "activated", id: value.id, rect };
|
|
185
198
|
}
|
|
199
|
+
case "tracked": {
|
|
200
|
+
const rect = parseRect(value.rect);
|
|
201
|
+
return !markId(value.id) || rect === null ? null : { type: "tracked", id: value.id, rect };
|
|
202
|
+
}
|
|
186
203
|
default:
|
|
187
204
|
return null;
|
|
188
205
|
}
|
|
@@ -192,7 +209,11 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
192
209
|
export function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateMode> {
|
|
193
210
|
const elements = mode?.elements ?? true;
|
|
194
211
|
const words = mode?.text ?? true;
|
|
195
|
-
if (
|
|
212
|
+
if (
|
|
213
|
+
(typeof elements !== "boolean" && elements !== "hold") ||
|
|
214
|
+
typeof words !== "boolean" ||
|
|
215
|
+
(elements === false && !words)
|
|
216
|
+
) {
|
|
196
217
|
throw new TypeError("annotations.start: elements, text, or both");
|
|
197
218
|
}
|
|
198
219
|
return { elements, text: words };
|
|
@@ -206,7 +227,8 @@ export const hasMarker = (mark: AnnotationMark): boolean =>
|
|
|
206
227
|
mark.count !== undefined || mark.kind === "draft";
|
|
207
228
|
|
|
208
229
|
/**
|
|
209
|
-
* The host's marks, checked before they go to the frame; throws on the first bad one
|
|
230
|
+
* The host's marks, checked before they go to the frame; throws on the first bad one (a count above
|
|
231
|
+
* `ANNOTATION_LIMITS.count` isn't bad: it is clamped to it, P116). Each is
|
|
210
232
|
* rebuilt as the frame gets it: a posted mark as 0.10.0 sent it (no `kind`), a draft with
|
|
211
233
|
* `kind: "draft"` and without its count (P107: a draft's marker shows no number, so the page isn't
|
|
212
234
|
* told one).
|
|
@@ -223,10 +245,10 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
|
223
245
|
`annotations.show: mark ${index} needs a unique id (1 to ${LIMITS.id} characters) and a valid anchor`,
|
|
224
246
|
);
|
|
225
247
|
}
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
);
|
|
248
|
+
// A count above the limit is clamped to it (P116): the marker reads "99+" either way, and a
|
|
249
|
+
// count is data anyone can grow (a thread's replies), so it mustn't reject the whole list.
|
|
250
|
+
if (mark.count !== undefined && !count(mark.count, Infinity)) {
|
|
251
|
+
throw new TypeError(`annotations.show: mark ${index}'s count is a whole number, 0 or more`);
|
|
230
252
|
}
|
|
231
253
|
const kind: unknown = mark.kind;
|
|
232
254
|
if (kind !== undefined && kind !== "posted" && kind !== "draft") {
|
|
@@ -236,6 +258,10 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
|
236
258
|
if (kind === "draft") {
|
|
237
259
|
return { id: mark.id, anchor, kind };
|
|
238
260
|
}
|
|
239
|
-
return {
|
|
261
|
+
return {
|
|
262
|
+
id: mark.id,
|
|
263
|
+
anchor,
|
|
264
|
+
...(mark.count === undefined ? {} : { count: Math.min(mark.count, LIMITS.count) }),
|
|
265
|
+
};
|
|
240
266
|
});
|
|
241
267
|
}
|
package/src/compile/policy.ts
CHANGED
|
@@ -217,6 +217,8 @@ export function sandboxTokens(config: PortholeConfig): string[] {
|
|
|
217
217
|
case "opaque":
|
|
218
218
|
return ["allow-scripts"];
|
|
219
219
|
case "domain":
|
|
220
|
+
// Nested (P111), this frame holds Porthole's shell, on a label of its own where no content
|
|
221
|
+
// runs with this origin (P114), and the page is the shell's child (`PAGE_SANDBOX_TOKENS`).
|
|
220
222
|
return ["allow-scripts", "allow-same-origin"];
|
|
221
223
|
case "external":
|
|
222
224
|
// The host may add a documented few (popups, modals, downloads), never top navigation.
|
|
@@ -235,9 +237,20 @@ export function sandboxTokens(config: PortholeConfig): string[] {
|
|
|
235
237
|
* own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
|
|
236
238
|
*/
|
|
237
239
|
export function servedSandboxDirective(config: PortholeConfig): CspDirective | null {
|
|
238
|
-
|
|
240
|
+
if (config.isolation !== "domain") {
|
|
241
|
+
return null;
|
|
242
|
+
}
|
|
243
|
+
return ["sandbox", ...(config.nested === true ? PAGE_SANDBOX_TOKENS : sandboxTokens(config))];
|
|
239
244
|
}
|
|
240
245
|
|
|
246
|
+
/**
|
|
247
|
+
* A nested page's sandbox (P111): its frame's attribute, set by Porthole's shell, and its own CSP
|
|
248
|
+
* header's, so it is an opaque origin in the shell's child frame and on a tab of its own. Scripts
|
|
249
|
+
* only: never `allow-same-origin`, which would give the page its served origin, the shell's, and
|
|
250
|
+
* so the shell's realm (a test holds every sandbox Porthole writes to this).
|
|
251
|
+
*/
|
|
252
|
+
export const PAGE_SANDBOX_TOKENS: readonly string[] = ["allow-scripts"];
|
|
253
|
+
|
|
241
254
|
/** A served page's CSP header: the page's directives, then its sandbox (P099). */
|
|
242
255
|
export function servedDocumentCsp(
|
|
243
256
|
config: PortholeConfig,
|
package/src/config/schema.ts
CHANGED
|
@@ -258,6 +258,17 @@ export interface PortholeConfig {
|
|
|
258
258
|
* `db`). Absent: 0.6's frames, globals and manual, exactly.
|
|
259
259
|
*/
|
|
260
260
|
readonly runtime?: RuntimeVersion;
|
|
261
|
+
/**
|
|
262
|
+
* Domain isolation, artifact pages (P111): the address the host frames serves Porthole's shell
|
|
263
|
+
* alone, a document of Porthole's own with no content in it, and the page runs in a child frame
|
|
264
|
+
* of the shell's, sandboxed without `allow-same-origin` (an opaque origin), served from the same
|
|
265
|
+
* origin at its files' sealed address. The shell is then a realm the page can't reach, above the
|
|
266
|
+
* page's frame: it relays the page's messages, and tells the host when its own transient
|
|
267
|
+
* activation turns on (a press in the page activates its ancestors only), which is how the host
|
|
268
|
+
* knows the person, not the page, moved the keyboard into the frame or opened a comment. The
|
|
269
|
+
* page has no storage of its own (an in-memory stand-in) and fetches nothing with a cookie.
|
|
270
|
+
*/
|
|
271
|
+
readonly nested?: true;
|
|
261
272
|
}
|
|
262
273
|
|
|
263
274
|
export interface StorageConfig {
|
package/src/config/validate.ts
CHANGED
|
@@ -324,6 +324,7 @@ export function validateConfig(
|
|
|
324
324
|
"storage",
|
|
325
325
|
"errors",
|
|
326
326
|
"runtime",
|
|
327
|
+
"nested",
|
|
327
328
|
],
|
|
328
329
|
"config",
|
|
329
330
|
);
|
|
@@ -687,6 +688,28 @@ export function validateConfig(
|
|
|
687
688
|
}
|
|
688
689
|
}
|
|
689
690
|
|
|
691
|
+
if (config.nested !== undefined) {
|
|
692
|
+
if (config.nested !== true) {
|
|
693
|
+
fail("config.nested", "must be true, or left out");
|
|
694
|
+
}
|
|
695
|
+
if (config.isolation !== "domain" || config.mode !== "artifact") {
|
|
696
|
+
fail("config.nested", "nests artifact pages served on their own origin (domain isolation)");
|
|
697
|
+
}
|
|
698
|
+
// The page's origin is opaque (P111): nothing of the content origin's own is its.
|
|
699
|
+
if (config.storage !== undefined) {
|
|
700
|
+
fail("config.nested", "a nested page keeps no storage: drop config.storage");
|
|
701
|
+
}
|
|
702
|
+
if (capabilities.assets !== undefined) {
|
|
703
|
+
fail(
|
|
704
|
+
"config.nested",
|
|
705
|
+
"a nested page can't load its asset library (/_blob/) yet: drop assets",
|
|
706
|
+
);
|
|
707
|
+
}
|
|
708
|
+
if (isObject(config.egress) && config.egress.libraries === true) {
|
|
709
|
+
fail("config.nested", "a nested page can't load Porthole's libraries from its origin yet");
|
|
710
|
+
}
|
|
711
|
+
}
|
|
712
|
+
|
|
690
713
|
if (config.errors !== undefined) {
|
|
691
714
|
if (config.errors !== "agent" && config.errors !== "host" && config.errors !== "none") {
|
|
692
715
|
fail("config.errors", 'must be "agent", "host" or "none"');
|
package/src/displays/displays.ts
CHANGED
|
@@ -93,9 +93,11 @@ export function defineDisplays<N extends string>(
|
|
|
93
93
|
return presets.url({ ...kind.options, contentOrigins: [source] });
|
|
94
94
|
}
|
|
95
95
|
const options = kind.options ?? {};
|
|
96
|
+
// Nesting (P111) is a served page's: an opaque frame has nothing to nest.
|
|
97
|
+
const { nested: _nested, ...opaque } = options;
|
|
96
98
|
return presets[kind.preset](
|
|
97
99
|
source === null
|
|
98
|
-
?
|
|
100
|
+
? opaque
|
|
99
101
|
: { ...options, ...kind.served, isolation: "domain", contentOrigins: [source] },
|
|
100
102
|
);
|
|
101
103
|
};
|
package/src/guide/limits.ts
CHANGED
|
@@ -196,7 +196,7 @@ export function manualLimits(config: PortholeConfig, network: string): ManualLim
|
|
|
196
196
|
);
|
|
197
197
|
add(
|
|
198
198
|
"storage",
|
|
199
|
-
config.isolation === "opaque"
|
|
199
|
+
config.isolation === "opaque" || config.nested === true
|
|
200
200
|
? `State isn't saved: localStorage works but lasts only while the ${it} is on screen, and a reload or another device starts fresh. Keep what matters in the ${it}'s code.`
|
|
201
201
|
: config.storage?.scope !== undefined
|
|
202
202
|
? `localStorage is kept for ${config.storage.scope}, in this browser; another browser or device starts fresh. Reads and writes can throw (private windows, strict settings): wrap them in try/catch and keep only what can be lost.`
|