@botiverse/porthole 0.13.0 → 0.14.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.
- package/dist/annotate/types.d.ts +32 -3
- package/dist/annotate/types.js +4 -0
- package/dist/annotate/validate.js +19 -2
- 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 +73 -3
- package/dist/host/pass-on.d.ts +15 -0
- package/dist/host/pass-on.js +65 -0
- package/dist/host/types.d.ts +22 -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/server/files.js +19 -3
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +4 -0
- package/dist/server/nested.d.ts +37 -0
- package/dist/server/nested.js +70 -0
- package/dist/server/server.js +57 -7
- package/dist/shell/annotate.d.ts +1 -1
- package/dist/shell/annotate.js +157 -7
- 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.js +49 -14
- package/docs/ADOPTING.md +56 -2
- package/docs/ARCHITECTURE.md +23 -0
- package/docs/DECISIONS.md +209 -0
- package/docs/DESIGN.md +9 -0
- package/docs/THREAT_MODEL.md +75 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +28 -3
- package/src/annotate/validate.ts +23 -2
- 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 +76 -4
- package/src/host/pass-on.ts +73 -0
- package/src/host/types.ts +20 -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/server/files.ts +19 -3
- package/src/server/index.ts +10 -0
- package/src/server/nested.ts +86 -0
- package/src/server/server.ts +65 -6
- package/src/shell/annotate.ts +157 -7
- package/src/shell/frame.ts +268 -0
- package/src/shell/plan.ts +2 -1
- package/src/shell/runtime.ts +49 -14
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.0 (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,10 @@ 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).
|
|
20
23
|
|
|
21
24
|
## 1. Two layers
|
|
22
25
|
|
|
@@ -162,6 +165,15 @@ Whatever the use:
|
|
|
162
165
|
nothing one click away that posts, submits, resolves, deletes or discards (a draft's view, P107,
|
|
163
166
|
included: no "Post" or "Submit review" in it). Its menus and popovers are part of it, portaled
|
|
164
167
|
ones too (P105; ADOPTING.md § Annotations has the code: the view `inert` while it arms).
|
|
168
|
+
One exception to "takes no focus" (P112): in a comment mode the person started themselves (the
|
|
169
|
+
host's own control, never a report), a composer their selection opens (`selected`) may take
|
|
170
|
+
focus, with `focusField`, if all it can do is save a draft: nothing in it posts, submits or sends,
|
|
171
|
+
Enter in it only adds the draft to the batch (submitting is only ever the host's own "Submit N"
|
|
172
|
+
control, outside the composer), it shows plainly that it is a draft (so the person can see where
|
|
173
|
+
their keys are going), and the rest of this guard holds (no press for 500 ms, beside the frame). The page still chooses
|
|
174
|
+
when `selected` comes, so what it can do with that moment is put the person's next keys into a
|
|
175
|
+
draft they see and can discard, never send one; outside such a mode, or for a composer that can
|
|
176
|
+
send, it takes no focus.
|
|
165
177
|
- Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
|
|
166
178
|
likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
|
|
167
179
|
`createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
|
|
@@ -322,6 +334,30 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
|
|
|
322
334
|
worker; a page's CSP opens its own version's path, not its whole origin.
|
|
323
335
|
- With a per-request check (`authorize`), the host decides again on every request; a deny is a
|
|
324
336
|
403 that says `denied`.
|
|
337
|
+
- A nested page (`nested: true`, P111): the framed address answers Porthole's shell alone, its
|
|
338
|
+
script the only one its CSP runs, framing and fetching only the origin's sealed files' prefix.
|
|
339
|
+
The page is the shell's child, `sandbox="allow-scripts"` (never `allow-same-origin`, held by a
|
|
340
|
+
static check over every sandbox Porthole writes) and the same sandbox in its own CSP, so it is an
|
|
341
|
+
opaque origin in its frame and on a tab; it is loaded, and loads its files, at its sealed address
|
|
342
|
+
without a cookie, and its files then carry `Cross-Origin-Resource-Policy: cross-origin` and
|
|
343
|
+
`Access-Control-Allow-Origin: *` (an opaque page's own loads are cross-origin: the address is
|
|
344
|
+
the access, never the request's origin). So whoever holds a page's sealed address can read its
|
|
345
|
+
files from any origin, a page of their own included, until the address ends (an hour on its own,
|
|
346
|
+
P083): it is a bearer credential, as safe as it is unleaked. Porthole keeps it out of what it
|
|
347
|
+
says: no referrer goes with any load (`Referrer-Policy: no-referrer`, the shell's frame
|
|
348
|
+
`referrerpolicy="no-referrer"`), the host's reports name it as `./` (P083), and the shell's own
|
|
349
|
+
answer is `no-store`. The page itself can read it (its address) and so pass it on by any channel
|
|
350
|
+
it has, as it can pass on its files' bytes. The page has none of the origin's storage, and nothing
|
|
351
|
+
of the shell's realm: messages between them go by `postMessage`, the page's trusted by
|
|
352
|
+
`event.source`, and the shell drops what the page says in the shell's own namespace. Only the
|
|
353
|
+
shell (same-origin) renews the page's address; a module the page loaded keeps one that ends
|
|
354
|
+
within the hour. Every answer below the sealed prefix carries a CSP sandbox, never
|
|
355
|
+
`allow-same-origin` (a page's `allow-scripts`, every other file's runs nothing): a file opened on
|
|
356
|
+
a tab of its own (an SVG or XML file with a script) is opaque, never the shell's origin (negative
|
|
357
|
+
control `file-sandbox`). The sandbox refuses no worker (measured on the four engines): a nested
|
|
358
|
+
page's workers come from Blob URLs (a worker from its set's own script is refused by its opaque
|
|
359
|
+
origin, sandbox or not), and those load the set's scripts. Assets and Porthole's libraries aren't
|
|
360
|
+
served to a nested page yet.
|
|
325
361
|
|
|
326
362
|
**The host must**
|
|
327
363
|
|
|
@@ -556,7 +592,8 @@ wall on three engines, and `defineHostConformance` runs it against a host's own
|
|
|
556
592
|
effects are its own), and group displays by page (S7).
|
|
557
593
|
|
|
558
594
|
**Annotations** (`annotate`, P053, P104, P107). The shell that draws marks and reports anchors shares
|
|
559
|
-
its realm with the content
|
|
595
|
+
its realm with the content (a nested page's too: its marks are drawn by the runtime in the page's
|
|
596
|
+
own frame, below the shell, P111), so:
|
|
560
597
|
|
|
561
598
|
- *What content learns.* Everything the host sends in a `show` is posted into the frame's window,
|
|
562
599
|
where the content can listen: each mark's id, anchor and, where given, `count` (the number on
|
|
@@ -692,6 +729,35 @@ unposted words beside the frame and tell the page when.
|
|
|
692
729
|
technology's activation within 5 s of their key or press on the page): focus goes back, and
|
|
693
730
|
their next press once the pointer has left the frame and come back, a Tab, or an activation 5 s
|
|
694
731
|
later keeps it.
|
|
732
|
+
- *Full Chromium* (P111, measured on Chromium 153, not the headless shell): a cross-site frame is
|
|
733
|
+
out of process, and the host's page sees nothing of a press in it (no `:active`, no `:hover`, no
|
|
734
|
+
pointer event past the frame's edge). For a served page that isn't nested, a person's real click
|
|
735
|
+
into its field is taken back every time there (the display stopped at the third), and
|
|
736
|
+
`comments.open` from a real click is refused within 5 s of any input on the host's page
|
|
737
|
+
(porthole#53). Nest it.
|
|
738
|
+
- *A nested page* (P111): the guard asks the page's shell, a realm the page can't reach above its
|
|
739
|
+
frame, whose transient activation turns on only from a press or key in the page (activation goes
|
|
740
|
+
up, never down). A move into the frame is the person's if the shell's activation turned on within
|
|
741
|
+
the last second and the host's page had no trusted press or key since; or a Tab, the host's own
|
|
742
|
+
move, or a press the engine shows on the frame element. Nothing else counts: no pointer over the
|
|
743
|
+
frame, no host-wide activation. A move the shell hasn't spoken of yet waits for its word (its next
|
|
744
|
+
frame) at most 500 ms, then is taken back. Measured on full Chromium, the headless shell, WebKit
|
|
745
|
+
and Firefox (`leak/served/nested.spec.ts`): a real click into the page's field keeps the
|
|
746
|
+
keyboard; the page's `focus()` as it loads, on a timer while the person types, right after a
|
|
747
|
+
click on the host's own button, 1.2 to 4.5 s after the person paused typing, and 700 ms after
|
|
748
|
+
they pressed it and went back to the composer is taken back; what a page says in the shell's
|
|
749
|
+
name, to its parent or to the host's window, moves nothing (negative controls `shell-namespace`,
|
|
750
|
+
`shell-host-input`). *What doesn't*: a press in the page within 5 s of the last one turns no
|
|
751
|
+
activation on, so a second move into it after the person went back to the host's page is taken
|
|
752
|
+
back until 5 s after their last press or key in the page, or they Tab in; the page gets the keys
|
|
753
|
+
typed while a move waits for the shell's word; a shell without `navigator.userActivation` leaves
|
|
754
|
+
0.13's rule. A page that holds the thread it shares with its shell (WebKit; Firefox and Chromium
|
|
755
|
+
where the frames share a process) from its own click handler would push the moment the shell sees
|
|
756
|
+
its activation past the person's next keys on the host's page: so the shell looks and beats every
|
|
757
|
+
50 ms and says how long it went without a look, and an activation it reports after a stall of over
|
|
758
|
+
100 ms (its own, or no word heard) is no one's gesture until it lapses (P111, after its review;
|
|
759
|
+
negative control `shell-stall`). The cost: in those engines a page that keeps its thread busy has
|
|
760
|
+
the person's real click taken for uncertain until it is idle.
|
|
695
761
|
|
|
696
762
|
### The app runtime
|
|
697
763
|
|
|
@@ -727,7 +793,11 @@ section.
|
|
|
727
793
|
- `comments` is write-only: the page learns only whether the composer opened. It opens only from
|
|
728
794
|
a gesture with the host page's focus in the calling frame (P109: a press in it or a Tab into it;
|
|
729
795
|
not the person typing in the host's UI, nor a gesture in another display; negative control
|
|
730
|
-
`comments-in-frame`).
|
|
796
|
+
`comments-in-frame`). In a nested page (P111) it opens too while the page's shell saw the
|
|
797
|
+
person's gesture within the last second, with no press or key on the host's page since: a real
|
|
798
|
+
click on the page's button a moment after typing in the host's composer opens it, on full
|
|
799
|
+
Chromium too (porthole#53); with no click it is refused, whatever the page says in the shell's
|
|
800
|
+
name. A draft it gives (P108) is at most 2,000 characters of text a person can
|
|
731
801
|
see (P109): nothing invisible (zero-width characters, bidi and tag characters, controls but a
|
|
732
802
|
new line and a tab; U+200C and U+200D only between two letters or marks, where Persian and the
|
|
733
803
|
Indic scripts need them, never first, last, doubled, beside a space or punctuation, or in an
|
|
@@ -796,7 +866,7 @@ section.
|
|
|
796
866
|
The decisions below come from the 2026-10-19 review, and all of them have merged. Each row says
|
|
797
867
|
what was wrong, what holds now, and the limit its decision accepts, if any. Later reviews' decisions
|
|
798
868
|
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).
|
|
869
|
+
of 0.12.0's drafts), P111 (a nested page, S3; in 0.14.0).
|
|
800
870
|
|
|
801
871
|
| Decision | State | What it closes | Sections |
|
|
802
872
|
| --- | --- | --- | --- |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
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": {
|
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
|
}
|
|
@@ -106,6 +111,12 @@ export interface AnchorResult {
|
|
|
106
111
|
readonly state: AnchorState;
|
|
107
112
|
/** Where it is now, when attached. */
|
|
108
113
|
readonly rect?: AnnotationRect;
|
|
114
|
+
/**
|
|
115
|
+
* Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
|
|
116
|
+
* marks included, for a host that lists marks in reading order. The content's word: an order to
|
|
117
|
+
* sort by, never a fact.
|
|
118
|
+
*/
|
|
119
|
+
readonly order?: number;
|
|
109
120
|
}
|
|
110
121
|
|
|
111
122
|
/** What the frame reports, once the host has checked it. */
|
|
@@ -118,7 +129,11 @@ export type AnnotationReport =
|
|
|
118
129
|
}
|
|
119
130
|
/** The text selection went away. */
|
|
120
131
|
| { readonly type: "unselected" }
|
|
121
|
-
/**
|
|
132
|
+
/**
|
|
133
|
+
* The person pressed Escape while picking an element (the pick ends), or while selecting text
|
|
134
|
+
* (P112: the page keeps the key; the host decides what ends). The page's word too: a page can
|
|
135
|
+
* send it, and the host takes it only while it asked for a pick or for text.
|
|
136
|
+
*/
|
|
122
137
|
| { readonly type: "cancelled" }
|
|
123
138
|
/**
|
|
124
139
|
* Where the marked anchors are now: every mark after `show`, the focused one after `focus`,
|
|
@@ -128,6 +143,12 @@ export type AnnotationReport =
|
|
|
128
143
|
* host was last told, at most once a second (P104).
|
|
129
144
|
*/
|
|
130
145
|
| { readonly type: "anchored"; readonly results: readonly AnchorResult[] }
|
|
146
|
+
/**
|
|
147
|
+
* The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
|
|
148
|
+
* an animation frame where it moved: at most 60 a second, for that mark only, clamped to the
|
|
149
|
+
* frame. The content's word: where to put a card beside it, nothing more.
|
|
150
|
+
*/
|
|
151
|
+
| { readonly type: "tracked"; readonly id: string; readonly rect: AnnotationRect }
|
|
131
152
|
/**
|
|
132
153
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
133
154
|
* (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
|
|
@@ -155,6 +176,10 @@ export const ANNOTATE_METHODS = {
|
|
|
155
176
|
anchored: "porthole/annotate.anchored",
|
|
156
177
|
/** Frame → host: a mark's marker was clicked (P104). */
|
|
157
178
|
activated: "porthole/annotate.activated",
|
|
179
|
+
/** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
|
|
180
|
+
track: "porthole/annotate.track",
|
|
181
|
+
/** Frame → host: the followed mark's box, as it moves (P112). */
|
|
182
|
+
tracked: "porthole/annotate.tracked",
|
|
158
183
|
} as const;
|
|
159
184
|
|
|
160
185
|
/** 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 };
|
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 the content origin, and the page is
|
|
221
|
+
// 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.`
|
package/src/host/create-host.ts
CHANGED
|
@@ -26,8 +26,9 @@ import { isRefused } from "../bridge/refusal.ts";
|
|
|
26
26
|
import { capabilitySpec } from "../config/capabilities.ts";
|
|
27
27
|
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
28
28
|
import { locateServed } from "./locate.ts";
|
|
29
|
+
import { mayPassOn } from "./pass-on.ts";
|
|
29
30
|
import { watchOutcome, type OutcomeWatch } from "./outcome.ts";
|
|
30
|
-
import type
|
|
31
|
+
import { STORAGE_USED_METHOD, type FrameSource } from "../isolation/types.ts";
|
|
31
32
|
import { webPlatform } from "../platform/web.ts";
|
|
32
33
|
import { TAKES } from "../platform/focus-guard.ts";
|
|
33
34
|
import type { Surface } from "../platform/types.ts";
|
|
@@ -66,8 +67,12 @@ const REPORTS: Readonly<Record<string, AnnotationReport["type"]>> = {
|
|
|
66
67
|
[ANNOTATE_METHODS.cancelled]: "cancelled",
|
|
67
68
|
[ANNOTATE_METHODS.anchored]: "anchored",
|
|
68
69
|
[ANNOTATE_METHODS.activated]: "activated",
|
|
70
|
+
[ANNOTATE_METHODS.tracked]: "tracked",
|
|
69
71
|
};
|
|
70
72
|
|
|
73
|
+
/** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
|
|
74
|
+
export const TRACKED_PER_SECOND = 60;
|
|
75
|
+
|
|
71
76
|
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
72
77
|
value !== null && typeof value === "object" && !Array.isArray(value);
|
|
73
78
|
const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
|
|
@@ -95,6 +100,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
95
100
|
|
|
96
101
|
return {
|
|
97
102
|
compiled,
|
|
103
|
+
mayPassOn: (declaration) => mayPassOn(config, declaration),
|
|
98
104
|
mount(container: HTMLElement, mount: MountOptions): DisplayHandle<C> {
|
|
99
105
|
const handlers = { ...options.handlers, ...mount.handlers };
|
|
100
106
|
// A host whose consent is a Refused refuses every consent-gated call before its handler:
|
|
@@ -184,7 +190,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
184
190
|
let annotating: Required<AnnotateMode> | null = null;
|
|
185
191
|
let marks: AnnotationMark[] = [];
|
|
186
192
|
let activeMark: string | null = null;
|
|
193
|
+
// The mark the host follows (P112), and when it took each `tracked` in the last second.
|
|
194
|
+
let tracking: string | null = null;
|
|
195
|
+
const trackedTimes: number[] = [];
|
|
187
196
|
let handshaken = false;
|
|
197
|
+
let storageTold = false;
|
|
188
198
|
const toFrame = (method: string, params: Record<string, unknown>) => {
|
|
189
199
|
if (handshaken && surface !== null) {
|
|
190
200
|
surface.transport.send({ jsonrpc: "2.0", method, params });
|
|
@@ -200,6 +210,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
200
210
|
if (annotating !== null) {
|
|
201
211
|
toFrame(ANNOTATE_METHODS.start, { ...annotating });
|
|
202
212
|
}
|
|
213
|
+
if (tracking !== null) {
|
|
214
|
+
toFrame(ANNOTATE_METHODS.track, { id: tracking });
|
|
215
|
+
}
|
|
203
216
|
};
|
|
204
217
|
/**
|
|
205
218
|
* The frame's viewport as the platform tells it now; undefined where it can't (no
|
|
@@ -243,6 +256,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
243
256
|
switch (report.type) {
|
|
244
257
|
case "selected":
|
|
245
258
|
case "activated":
|
|
259
|
+
case "tracked":
|
|
246
260
|
return { ...report, rect: clampRect(report.rect, viewport) };
|
|
247
261
|
case "anchored":
|
|
248
262
|
return {
|
|
@@ -281,6 +295,25 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
281
295
|
void through.call("annotate", null);
|
|
282
296
|
return;
|
|
283
297
|
}
|
|
298
|
+
// The followed mark's box (P112): the mark the host follows and no other, while it is
|
|
299
|
+
// shown, at most 60 a second; past the bridge's rate for reports, which a card that follows
|
|
300
|
+
// its mark at every frame would spend at once.
|
|
301
|
+
if (report.type === "tracked") {
|
|
302
|
+
const { id } = report;
|
|
303
|
+
if (id !== tracking || !marks.some((mark) => mark.id === id)) {
|
|
304
|
+
return;
|
|
305
|
+
}
|
|
306
|
+
const at = Date.now();
|
|
307
|
+
while (trackedTimes.length > 0 && at - (trackedTimes[0] as number) >= 1_000) {
|
|
308
|
+
trackedTimes.shift();
|
|
309
|
+
}
|
|
310
|
+
if (trackedTimes.length >= TRACKED_PER_SECOND) {
|
|
311
|
+
return;
|
|
312
|
+
}
|
|
313
|
+
trackedTimes.push(at);
|
|
314
|
+
emit("annotation", withinFrame(report));
|
|
315
|
+
return;
|
|
316
|
+
}
|
|
284
317
|
switch (report.type) {
|
|
285
318
|
case "selected": {
|
|
286
319
|
const kind = report.anchor.kind;
|
|
@@ -290,7 +323,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
290
323
|
) {
|
|
291
324
|
return;
|
|
292
325
|
}
|
|
293
|
-
|
|
326
|
+
// A pick ends with it; holding a block (P112) lasts until the host stops it.
|
|
327
|
+
if (kind === "element" && annotating.elements === true) {
|
|
294
328
|
annotating = annotating.text ? { elements: false, text: true } : null;
|
|
295
329
|
}
|
|
296
330
|
break;
|
|
@@ -301,10 +335,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
301
335
|
}
|
|
302
336
|
break;
|
|
303
337
|
case "cancelled":
|
|
304
|
-
|
|
338
|
+
// While the host asked for a pick or for text (P112: Escape while selecting text);
|
|
339
|
+
// a pick ends with it, text selection is the host's to stop.
|
|
340
|
+
if (annotating === null) {
|
|
305
341
|
return;
|
|
306
342
|
}
|
|
307
|
-
|
|
343
|
+
if (annotating.elements === true) {
|
|
344
|
+
annotating = annotating.text ? { elements: false, text: true } : null;
|
|
345
|
+
}
|
|
308
346
|
break;
|
|
309
347
|
case "anchored": {
|
|
310
348
|
const known = new Set(marks.map((mark) => mark.id));
|
|
@@ -354,6 +392,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
354
392
|
if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
|
|
355
393
|
activeMark = null;
|
|
356
394
|
}
|
|
395
|
+
if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
|
|
396
|
+
tracking = null;
|
|
397
|
+
toFrame(ANNOTATE_METHODS.track, { id: null });
|
|
398
|
+
}
|
|
357
399
|
toFrame(ANNOTATE_METHODS.show, {
|
|
358
400
|
marks,
|
|
359
401
|
...(activeMark === null ? {} : { active: activeMark }),
|
|
@@ -367,10 +409,20 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
367
409
|
activeMark = id;
|
|
368
410
|
toFrame(ANNOTATE_METHODS.focus, { id });
|
|
369
411
|
},
|
|
412
|
+
track(id) {
|
|
413
|
+
needsAnnotate("track");
|
|
414
|
+
if (id !== null && !marks.some((mark) => mark.id === id)) {
|
|
415
|
+
throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
|
|
416
|
+
}
|
|
417
|
+
tracking = id;
|
|
418
|
+
trackedTimes.length = 0;
|
|
419
|
+
toFrame(ANNOTATE_METHODS.track, { id });
|
|
420
|
+
},
|
|
370
421
|
clear() {
|
|
371
422
|
needsAnnotate("clear");
|
|
372
423
|
marks = [];
|
|
373
424
|
activeMark = null;
|
|
425
|
+
tracking = null;
|
|
374
426
|
toFrame(ANNOTATE_METHODS.clear, {});
|
|
375
427
|
},
|
|
376
428
|
};
|
|
@@ -436,6 +488,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
436
488
|
};
|
|
437
489
|
|
|
438
490
|
const stop = () => {
|
|
491
|
+
// A run that ran a page with storage of its own making and never heard it used: no (P111).
|
|
492
|
+
if (bridge !== null && handshaken && !storageTold && compiled.shell?.storage === "memory") {
|
|
493
|
+
emit("storage", { used: false });
|
|
494
|
+
}
|
|
495
|
+
storageTold = false;
|
|
439
496
|
// The run's bridge refuses what still waits for a confirmation: a yes to it runs nothing
|
|
440
497
|
// (P095, after the review), and the next run's bridge starts its count again.
|
|
441
498
|
bridge?.close();
|
|
@@ -469,6 +526,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
469
526
|
allow: compiled.allow,
|
|
470
527
|
referrerPolicy: compiled.referrerPolicy,
|
|
471
528
|
colorScheme: scheme,
|
|
529
|
+
// A nested page's shell (P111): the config's word, never the frame's.
|
|
530
|
+
...(config.nested === true ? { nested: true } : {}),
|
|
472
531
|
// An app reports no size: its frame fills the host's container, at least the minimum;
|
|
473
532
|
// so does any display the host mounts to fill, or whose layout fills (P065): its
|
|
474
533
|
// content scrolls itself.
|
|
@@ -563,6 +622,19 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
563
622
|
if (annotates) {
|
|
564
623
|
created.transport.listen((raw) => onAnnotation(raw, opening));
|
|
565
624
|
}
|
|
625
|
+
// Whether the page used storage (P111): once per run, the page's word (a count, no more).
|
|
626
|
+
created.transport.listen((raw) => {
|
|
627
|
+
if (
|
|
628
|
+
!storageTold &&
|
|
629
|
+
isRecord(raw) &&
|
|
630
|
+
raw.jsonrpc === "2.0" &&
|
|
631
|
+
raw.method === STORAGE_USED_METHOD &&
|
|
632
|
+
!("id" in raw)
|
|
633
|
+
) {
|
|
634
|
+
storageTold = true;
|
|
635
|
+
emit("storage", { used: true });
|
|
636
|
+
}
|
|
637
|
+
});
|
|
566
638
|
bridge = opening;
|
|
567
639
|
const opened = adapter.connect({
|
|
568
640
|
display: { id: mount.displayId, title: mount.title },
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import type { CapabilityName } from "../config/capabilities.ts";
|
|
2
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
3
|
+
import { egressOrigins, type EgressKind } from "../compile/policy.ts";
|
|
4
|
+
import { LIBRARY_CDNS } from "../presets/presets.ts";
|
|
5
|
+
import { familyOf, runtimeCapability } from "../runtime/contract.ts";
|
|
6
|
+
import type { PageDeclaration } from "../runtime/declaration.ts";
|
|
7
|
+
|
|
8
|
+
/** Every kind a page reaches the network by. */
|
|
9
|
+
const KINDS: readonly EgressKind[] = ["connect", "script", "style", "img", "font", "media"];
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* The host functions that carry what a page puts in them to someone other than the person viewing
|
|
13
|
+
* it (P112, after the review, porthole#54): stores others read (`db`, a new version through
|
|
14
|
+
* `artifact`, the asset library through `assets`), a URL the person opens (`openLink`), the agent's
|
|
15
|
+
* conversation and context (`sendPrompt`, `setModelContext`), and the host's data services, which
|
|
16
|
+
* may be someone else's (`callTool`, `readData`, `subscribeData`: their arguments are the page's).
|
|
17
|
+
* Not here: the person's own clipboard and disk (`copyText`, `downloadFile`), the host's own UI
|
|
18
|
+
* (`annotate`, `resize`, `comments`: the composer is the person's, under the host's duties), and
|
|
19
|
+
* what only reads (`user`). `reportError` is one where the config sends errors to the agent.
|
|
20
|
+
*/
|
|
21
|
+
const CARRIERS: readonly CapabilityName[] = [
|
|
22
|
+
"db",
|
|
23
|
+
"artifact",
|
|
24
|
+
"assets",
|
|
25
|
+
"openLink",
|
|
26
|
+
"sendPrompt",
|
|
27
|
+
"setModelContext",
|
|
28
|
+
"callTool",
|
|
29
|
+
"readData",
|
|
30
|
+
"subscribeData",
|
|
31
|
+
];
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Whether a page shown under `config` with `declaration` may pass on what it is given (P112: a
|
|
35
|
+
* person's draft, which a host shows a page only where it can't). It may when it can reach one of
|
|
36
|
+
* the host functions that carry what it puts in them to others (`CARRIERS`; `reportError` where
|
|
37
|
+
* errors go to the agent), or the network beyond the library CDNs (`LIBRARY_CDNS`): any https site
|
|
38
|
+
* (`anyHttps`), or an origin the host (or a capability) added for connections, scripts, styles,
|
|
39
|
+
* images, fonts or media. A library CDN serves published packages by their path, and its logs are
|
|
40
|
+
* its operator's, not the page author's: not counted. A page reaches a host function the config
|
|
41
|
+
* declares: under the runtime with a declaration, only through a built-in family or one it
|
|
42
|
+
* declared (one no family serves, wherever the config declares it); without a declaration (a page from before 0.7), or without the runtime, every one, as
|
|
43
|
+
* 0.6's globals. The host's rule made checkable: "a page with a channel gets no drafts".
|
|
44
|
+
*/
|
|
45
|
+
export function mayPassOn(config: PortholeConfig, declaration: PageDeclaration | null): boolean {
|
|
46
|
+
const declared = (declaration?.capabilities ?? {}) as Readonly<Record<string, unknown>>;
|
|
47
|
+
const reaches = (name: CapabilityName): boolean => {
|
|
48
|
+
if (config.capabilities[name] === undefined) {
|
|
49
|
+
return false;
|
|
50
|
+
}
|
|
51
|
+
if (config.runtime === undefined || declaration === null) {
|
|
52
|
+
return true;
|
|
53
|
+
}
|
|
54
|
+
// One no runtime family serves (`reportError`: the shell reports what the page throws) is
|
|
55
|
+
// the page's wherever the config declares it.
|
|
56
|
+
const family = familyOf(name);
|
|
57
|
+
return (
|
|
58
|
+
family === null ||
|
|
59
|
+
runtimeCapability(family.name).builtIn ||
|
|
60
|
+
declared[family.name] !== undefined
|
|
61
|
+
);
|
|
62
|
+
};
|
|
63
|
+
if (CARRIERS.some(reaches) || (config.errors === "agent" && reaches("reportError"))) {
|
|
64
|
+
return true;
|
|
65
|
+
}
|
|
66
|
+
if ((config.egress.anyHttps ?? []).length > 0) {
|
|
67
|
+
return true;
|
|
68
|
+
}
|
|
69
|
+
return KINDS.some((kind) => {
|
|
70
|
+
const cdns = new Set(LIBRARY_CDNS[kind] ?? []);
|
|
71
|
+
return egressOrigins(config, kind).some((origin) => !cdns.has(origin));
|
|
72
|
+
});
|
|
73
|
+
}
|