@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/CHANGELOG.md
ADDED
|
@@ -0,0 +1,770 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
`@botiverse/porthole`. Each published release is a `v*` tag (0.11.0 was never published: see its
|
|
4
|
+
section); the reasons for every change are in [docs/DECISIONS.md](docs/DECISIONS.md), by the
|
|
5
|
+
P-numbers below.
|
|
6
|
+
|
|
7
|
+
## 0.14.1
|
|
8
|
+
|
|
9
|
+
- **Security (P114, porthole#56's P1):** a nested page's shell, its page and the page's files are
|
|
10
|
+
served on a label of their own, `porthole-<24 base32>.<content domain>` (`nestedLabelOf(label)`,
|
|
11
|
+
one per scope), on which nothing but nested pages' shells, their opaque pages, those pages' files
|
|
12
|
+
and status pages is ever served. In 0.14.0 the shell was on its scope's label, where the scope's
|
|
13
|
+
other displays (inline and live widgets, MCP apps, artifacts that aren't nested) run agent-made
|
|
14
|
+
content with `allow-same-origin`: such a display on the same page could read the shell's document,
|
|
15
|
+
drive its word to the host (the keyboard rule, `comments.open`) and take the page's sealed
|
|
16
|
+
address. `issue` answers the shell's origin for a nested page; the scope's label never answers a
|
|
17
|
+
nested page (a clean address sends the browser on to the shell's label with a one-time ticket).
|
|
18
|
+
An entry code is no longer taken as a document's ticket.
|
|
19
|
+
- **Adopters with nested pages:** route `porthole-*.<content domain>` to the content server as
|
|
20
|
+
your other labels (a wildcard DNS name and certificate already cover it; a route or edge rule of
|
|
21
|
+
your own that matches `a-*` must add it). Every `porthole-` label is Porthole's: a naming that
|
|
22
|
+
makes one throws, and `prefixedName("porthole-")` is refused. A content Worker of your own serves
|
|
23
|
+
nested pages on `nestedLabelOf(label)` alone (ADOPTING "Nested pages"). New exports from
|
|
24
|
+
`/server`: `nestedLabelOf`, `isNestedLabel`, `PORTHOLE_LABEL_PREFIX`; `TicketRecord.page`.
|
|
25
|
+
- **Tests (P114):** `leak/served/nested-siblings.spec.ts` (a same-scope inline widget and artifact
|
|
26
|
+
beside a nested page read nothing of its shell), negative control `shell-label`; the nested
|
|
27
|
+
suite's first case shares its scope with a widget; `test/nested.test.ts`, `test/entry.test.ts`;
|
|
28
|
+
the kit app and the prod-shape profile frame a nested page and open its clean address.
|
|
29
|
+
- **New:** `display.annotations.clearSelection()` (P115): takes the page's text selection away,
|
|
30
|
+
and the highlight the browser leaves on it, once the host has used it (a comment posted, a draft
|
|
31
|
+
added; asked for by Raft's comment mode). The shell clears it with the DOM's own
|
|
32
|
+
`removeAllRanges`, taken before content runs, and reports nothing back (no `unselected`); marks,
|
|
33
|
+
drafts, the mode and a followed mark stay. With nothing selected, nothing happens. Host to frame
|
|
34
|
+
only (`porthole/annotate.clearSelection`); an older shell ignores it.
|
|
35
|
+
- **Tests:** `leak/annotate.spec.ts` "clearSelection takes the page's selection away…", and through
|
|
36
|
+
a nested page's shell (`leak/served/nested.spec.ts`); negative control `clear-selection`.
|
|
37
|
+
- **Fixed:** `annotations.show` clamps a mark's `count` above `ANNOTATION_LIMITS.count` (999) to
|
|
38
|
+
it, where it threw and refused every mark (P116; porthole#40: a thread of 1,000 comments broke a
|
|
39
|
+
host's page). The marker reads "99+" either way. A count that isn't a whole number from 0 still
|
|
40
|
+
throws.
|
|
41
|
+
- **Fixed:** `PortholeFrame` and `PortholeView` take `declaration: null` (porthole#17), the
|
|
42
|
+
host's word under `config.runtime` for a page published before 0.7, as `MountOptions.declaration`
|
|
43
|
+
does. It already worked at run time; only the type refused it.
|
|
44
|
+
- **Fixed:** a streamed draft no longer shows a stray `<` when the content so far ends in `<` or
|
|
45
|
+
`</` (P117, porthole#16): the shell holds back a tag start it was cut in until more comes. The
|
|
46
|
+
whole content is drawn as it is.
|
|
47
|
+
- **Package:** the npm package ships `CHANGELOG.md` (copied from the repository's by `pnpm build`,
|
|
48
|
+
as `docs/` is), so the upgrade notes are in `node_modules` (porthole#32). 0.8.0's "Act on these
|
|
49
|
+
when upgrading" now says that `declareCapabilities`' declarations have no prototype either, and
|
|
50
|
+
what an ORM needs.
|
|
51
|
+
|
|
52
|
+
## 0.14.0
|
|
53
|
+
|
|
54
|
+
**Withdrawn: do not use; stay on 0.13.0.** It was published by mistake on 2026-10-28, while
|
|
55
|
+
porthole#56's Firefox P0 (a nested page can read what the person types into the host's fields) and
|
|
56
|
+
its P1 were still open. The fixes ship as 0.14.1.
|
|
57
|
+
|
|
58
|
+
A nested page (P111): the address a served artifact's frame loads is Porthole's shell alone, and the
|
|
59
|
+
page runs in its child frame with an opaque origin, so the person's press in the page is seen in
|
|
60
|
+
full Chromium too, where a cross-site frame is out of process and the host's page sees nothing of
|
|
61
|
+
it. Fixes porthole#53. And what annotations add for a host's comment modes (P112): Escape while
|
|
62
|
+
selecting text, a mark followed as it moves, marks' places in the document, holding a block on
|
|
63
|
+
touch, and `mayPassOn`.
|
|
64
|
+
|
|
65
|
+
- **New:** `nested: true` on an artifact config with domain isolation (`presets.artifact`,
|
|
66
|
+
`defineDisplays` options). The host kit serves the shell at the framed address and the page at
|
|
67
|
+
its sealed files' address, `sandbox allow-scripts` in its frame and its CSP, fetched without a
|
|
68
|
+
cookie; its files carry `Cross-Origin-Resource-Policy: cross-origin` and
|
|
69
|
+
`Access-Control-Allow-Origin: *`. A content Worker of your own answers the same (ADOPTING.md
|
|
70
|
+
"Nested pages", with `nestedShellResponse`, `NESTED_FILE_HEADERS`, `nestedAncestors` from
|
|
71
|
+
`/server`). Not with `storage`, `assets` or `egress.libraries` (refused).
|
|
72
|
+
- **The keyboard and `comments.open` in a nested page:** the focus guard takes a move into the
|
|
73
|
+
frame for the person's if the page's shell saw its own activation turn on within the last second
|
|
74
|
+
and the host's page had no trusted press or key since (or a Tab, the host's own move, a press the
|
|
75
|
+
engine shows); `comments.open` opens on the same signal, so a click on the page's button a moment
|
|
76
|
+
after typing in the host's composer opens it (porthole#53). Limit: a press in the page within 5 s
|
|
77
|
+
of the last one turns no activation on (THREAT_MODEL §7 "The keyboard").
|
|
78
|
+
- **A stalled shell** (after the review, porthole#54): the shell looks and beats every 50 ms; an
|
|
79
|
+
activation it reports after a stall of over 100 ms is uncertain, no one's gesture, until it lapses.
|
|
80
|
+
- **Every file of a nested page sandboxed** (after the review): a script's answer too, so no file
|
|
81
|
+
opened on a tab of its own runs on the shell's origin.
|
|
82
|
+
- **Workers in a nested page** (measured, P111): from Blob URLs, which may `importScripts` the
|
|
83
|
+
set's scripts; a worker from the set's own script is refused (the page's origin is opaque), and
|
|
84
|
+
Chromium refuses a Blob module worker there. The sandbox on scripts' answers refuses none.
|
|
85
|
+
- **New event** `storage` (`{ used }`, once per run) for displays whose storage is the in-memory
|
|
86
|
+
stand-in (opaque, nested): whether the page touched `localStorage` or `sessionStorage`.
|
|
87
|
+
- **Annotations (P112):** Escape while selecting text reports `cancelled` too (the page keeps
|
|
88
|
+
the key); the host takes it only while it asked for a pick or for text.
|
|
89
|
+
`annotations.track(id | null)` follows one shown mark: `{ type: "tracked", id, rect }` as it
|
|
90
|
+
moves, at most 60 a second, clamped to the frame. Each attached `anchored` result carries
|
|
91
|
+
`order`, its place in the document among the found marks (offscreen ones too).
|
|
92
|
+
`start({ text: true, elements: "hold" })`: on touch, holding a block 500 ms selects it (its
|
|
93
|
+
release's click is the shell's); other taps stay the page's.
|
|
94
|
+
`mayPassOn(config, declaration)` / `host.mayPassOn(declaration)`: whether a page can pass a draft
|
|
95
|
+
on (any store others read, `openLink`, the agent, the host's data services, or egress beyond the
|
|
96
|
+
library CDNs), so a host can show it none.
|
|
97
|
+
- **Docs (P112):** THREAT_MODEL §6 and ADOPTING's keyboard section agree: a composer the person's
|
|
98
|
+
selection opens may take focus (`focusField`) only in a comment mode they started and only if it
|
|
99
|
+
can do nothing but save a draft.
|
|
100
|
+
- **Tests:** `leak/served/nested.spec.ts` runs on full Chromium (`chromium-oopif`, a new CI leg),
|
|
101
|
+
the headless shell, WebKit and Firefox; negative controls `shell-namespace`, `shell-host-input`.
|
|
102
|
+
`PORTHOLE_WEBKIT_PATH` runs the leak suite on a WebKit build of the machine's own.
|
|
103
|
+
|
|
104
|
+
## 0.13.0
|
|
105
|
+
|
|
106
|
+
After the review of 0.12.0's drafts (P109): a display no longer keeps the keyboard it takes from
|
|
107
|
+
the host's composer, `comments.open` needs the person in the frame that calls it, a page's draft is
|
|
108
|
+
stricter text, and the composer it fills is the person's to act on. What a host must act on comes
|
|
109
|
+
first. 0.11.0 was never published, so its upgrade notes are repeated at the end for hosts coming
|
|
110
|
+
from 0.10.0.
|
|
111
|
+
|
|
112
|
+
- **Act on these when upgrading:**
|
|
113
|
+
- **The composer a page's draft fills** (THREAT_MODEL §7, ADOPTING.md `openPageDraft`): an open
|
|
114
|
+
never replaces, appends to or retargets what the person typed or the place they chose (answer
|
|
115
|
+
`false`, or show the page's words as a separate suggestion that takes no focus); it takes no
|
|
116
|
+
focus when it opens and sends on no Enter until the person has focused or edited it (Send is a
|
|
117
|
+
click until then); it says "Suggested by this page" (drawn by you, outside the frame) until they
|
|
118
|
+
edit it, and is never shown as one of their own drafts; render it as plain text, and show the
|
|
119
|
+
anchor's label and quote as isolated text (`<bdi>`, `dir="auto"`). The 0.12.0 one-liner,
|
|
120
|
+
`comments: ({ anchor, draft }) => composer.open(anchor, { draft })`, does none of this.
|
|
121
|
+
- **Nothing one click away that posts, submits, resolves, deletes or discards** in a view a
|
|
122
|
+
frame's report opens, a draft's view included (no "Post" or "Submit review" in it: THREAT_MODEL
|
|
123
|
+
§6, P107).
|
|
124
|
+
- **Moving focus into a display yourself:** `display.focus()` (new), not the frame's own
|
|
125
|
+
`focus()`, which from one of your text fields is taken for the page's and undone.
|
|
126
|
+
- **Opening your composer focused:** `focusField(textarea)` (new), not `textarea.focus()`: on
|
|
127
|
+
Firefox a page that has the person's gesture (the selection that opened the composer) and takes
|
|
128
|
+
focus back on its blur keeps a plain `focus()` from landing, and gets the keys.
|
|
129
|
+
- **A platform of your own** (not the web platform): implement `focused`, `onFocusTaken` and
|
|
130
|
+
`focus` on its surfaces, or a display can read what is typed beside it, and `comments` keeps
|
|
131
|
+
its old gate.
|
|
132
|
+
- **The keyboard given back** (P109): a display's page could move the keyboard into its frame
|
|
133
|
+
whenever it liked (on Chromium and WebKit with no gesture) and read what the person went on
|
|
134
|
+
typing in the host's composer. When focus leaves one of the host page's text fields for a
|
|
135
|
+
display's frame without the person's press on the frame or a Tab into it, `createHost` (every
|
|
136
|
+
`PortholeView`) gives it back once the move is over, and the display hears `focusTaken`
|
|
137
|
+
(`{ typing }`; React `onFocusTaken`); it keeps watching that focus stays back. Three within
|
|
138
|
+
10 s that came while the person typed or that kept focus from staying back, or five within 2 s,
|
|
139
|
+
stop the display: a `contentError`, "The content kept taking the keyboard from the page; it was
|
|
140
|
+
stopped." Measured on Chromium, Firefox and WebKit: a page calling `focus()` every 700 ms down to
|
|
141
|
+
a busy loop, or taking focus back on its own blur, gets none or one key of a sentence before it
|
|
142
|
+
is stopped; a press on the page's own field, a Tab into it, and an assistive technology's
|
|
143
|
+
activation keep the keyboard there. Limits (THREAT_MODEL §7 "The keyboard"): on Firefox, which
|
|
144
|
+
shows the host's page no press in a frame, a page keeps the keyboard if the pointer came over its
|
|
145
|
+
frame after the person last typed and after the field got focus.
|
|
146
|
+
- **`comments.open` from the frame the person is in** (P109): its gesture gate also needs the host
|
|
147
|
+
page's focus in the calling frame, so a page no longer opens the composer, draft and all, while
|
|
148
|
+
the person types in the host's UI (the host page's activation lasts 5 s after any gesture on it;
|
|
149
|
+
0.12.0's "a click to open" was that). Refused as `no-user-activation` (`not_allowed` to the page).
|
|
150
|
+
A press in the frame, or a Tab into it, opens it as before.
|
|
151
|
+
- **Stricter draft text** (P109): refused now, before the handler: a joiner (U+200C, U+200D)
|
|
152
|
+
anywhere but between two letters or marks (first, last, doubled, beside a space or punctuation,
|
|
153
|
+
or in an emoji sequence, 👩💻; Persian's میخواهم, Hindi's क्ष and Malayalam's എന്റെ, ❤️ and 1️⃣
|
|
154
|
+
still pass), U+2028 and U+2029, blank-looking text (spaces of any kind, U+2800), more than 32
|
|
155
|
+
blanks in a row, more than two blank lines in a row. The anchor's `label` and `quote` reach the
|
|
156
|
+
handler without what a person can't see, and are refused if nothing visible is left. The manual
|
|
157
|
+
and `comments.d.ts` say so.
|
|
158
|
+
- **Docs:** THREAT_MODEL §6, §7, §8 and its status line; P108's "a click to open" corrected;
|
|
159
|
+
capabilities' `user-activation` described as it is (any gesture on the host's page in the last
|
|
160
|
+
5 s, `comments` also the person in the frame).
|
|
161
|
+
- New: `focusField`, `DisplayEvents.focusTaken`, `DisplayControls.focus()`, `onFocusTaken` (React),
|
|
162
|
+
`Surface.focused`, `Surface.onFocusTaken`, `Surface.focus` (optional, the platform seam).
|
|
163
|
+
- **From 0.10.0** (0.11.0's notes, never published on its own; all of it is in 0.12.0):
|
|
164
|
+
- **Drafts** (P107): send a person's drafts only to the frame that person views, and none to a
|
|
165
|
+
page with the runtime's `db` and `user` or with egress, or accept that its author and other
|
|
166
|
+
viewers can learn of them (THREAT_MODEL §7). Upgrade the content server's Porthole before
|
|
167
|
+
sending drafts: an older shell draws a draft as a posted mark without a marker. A `kind` other
|
|
168
|
+
than `"posted"` or `"draft"` throws from `annotations.show` (React: `onHostError`, kind
|
|
169
|
+
`"annotations"`). New: `AnnotationMarkKind`.
|
|
170
|
+
- **Lint** (P106): `LintRule` and `FileFinding["rule"]` take `"scroll-lock"` (a warning); a
|
|
171
|
+
switch over rules needs the case.
|
|
172
|
+
|
|
173
|
+
After the audit of P106's scroll-lock warning (P110): it no longer fails a show or a publish, and
|
|
174
|
+
it reads only the stylesheets it may.
|
|
175
|
+
|
|
176
|
+
- **A CSS escape past U+10FFFF no longer fails the check** (P110): one selector like `.\ffffff`
|
|
177
|
+
in a page or a linked stylesheet threw out of `lintContent`, `admitContent`, `lintFiles`,
|
|
178
|
+
`admitFiles` and `checkPage`. Such an escape (or 0, or a surrogate) is now U+FFFD, as CSS reads
|
|
179
|
+
it, and the rule fails soft: anything that throws in it is that page "not checked for scroll
|
|
180
|
+
lock" (a warning), never a failed check.
|
|
181
|
+
- **`lintFiles` decodes only the stylesheets the rule reads** (P110): a page linking many sheets
|
|
182
|
+
had every one decoded and kept for the whole call (400 sheets of 240 KB: 200 MB of heap, out of
|
|
183
|
+
memory at 64 MB), though the rule reads at most 32 sheets and 4 MiB a page. A sheet past the
|
|
184
|
+
caps is now refused before it is decoded, none is asked for once they are reached, and none is
|
|
185
|
+
kept: the same version runs under a 32 MB heap. The caps still count characters, whether the
|
|
186
|
+
host gives strings or bytes.
|
|
187
|
+
- **A fixed body is warned** (P110): `body { position: fixed; top: 0 }` with no bottom or height,
|
|
188
|
+
and `body { position: fixed; inset: 0; overflow: auto }` where html's overflow is visible, hold
|
|
189
|
+
the page on Chromium, Firefox and WebKit, and are now `scroll-lock` warnings.
|
|
190
|
+
- **`<html style="…">` is no longer warned** (P110): the shell drops html's `style` attribute, so
|
|
191
|
+
`<html style="overflow: hidden">` never held the page in Porthole's frame; the warning, and its
|
|
192
|
+
advice to edit the attribute, were wrong.
|
|
193
|
+
|
|
194
|
+
## 0.12.0
|
|
195
|
+
|
|
196
|
+
A page's button can open the host's comment composer with a draft the person reviews and posts
|
|
197
|
+
themselves (P108). 0.12.0 also carries all of 0.11.0, which was never published: read 0.11.0's
|
|
198
|
+
notes below when coming from 0.10.0. (The review of 0.12.0 tightened all of this: see Unreleased,
|
|
199
|
+
P109.)
|
|
200
|
+
|
|
201
|
+
- **A comment's draft from the page** (P108): `comments.open(anchor, { draft })` opens the host's
|
|
202
|
+
composer starting with `draft` (at most 2,000 characters), which the person edits and posts, or
|
|
203
|
+
doesn't; the handler gets `{ anchor, draft }`. The page still never posts or reads a comment. A
|
|
204
|
+
draft is visible text only (P100's `unseen`): anything else is refused before the handler.
|
|
205
|
+
- **Hosts:** show the draft whole, as the person's editable plain text; post it only on their
|
|
206
|
+
Send; arm the composer as THREAT_MODEL §6 arms a view the content brought (no press, and no
|
|
207
|
+
Enter that sends, for 500 ms; Send not focused). `defineRuntimeConformance` now sends a draft.
|
|
208
|
+
|
|
209
|
+
## 0.11.0 (not published)
|
|
210
|
+
|
|
211
|
+
Its release stopped at the CI gate (a timed-out Firefox shard) and was never tagged or published;
|
|
212
|
+
everything below shipped in 0.12.0.
|
|
213
|
+
|
|
214
|
+
The agent hears, before publishing, that its page's own styles hold it to one screen (P106), and
|
|
215
|
+
the manual says a page scrolls as a document. A host can mark a person's unposted comments,
|
|
216
|
+
drafts, apart from posted ones (P107).
|
|
217
|
+
|
|
218
|
+
- **A warning for a page held to one screen** (P106): `lintContent`, `admitContent`, `lintFiles`
|
|
219
|
+
and `admitFiles` warn (rule `scroll-lock`, never an error: a one-screen app means it) where the
|
|
220
|
+
page's own CSS stops it at its first screen in the frame: html or body with `overflow: hidden`
|
|
221
|
+
(or `clip`), or the body's one element of content (`#root`) one screen tall (100vh, dvh, svh,
|
|
222
|
+
100% of a one-screen parent, fixed at the frame's edges) with `overflow: hidden` or
|
|
223
|
+
`position: fixed`, and no element in the page's markup below body scrolls itself (by
|
|
224
|
+
`style=""`, a Tailwind class, or a rule whose selector matches it: the page may scroll there;
|
|
225
|
+
the root counts only where it is one screen tall, or, in a one-screen body, under a flex or
|
|
226
|
+
grid body or in a height it can't read). A
|
|
227
|
+
page its script draws (an empty `#root`) has nothing to match: it is warned as one that "looks
|
|
228
|
+
held", which it may ignore if a box its script draws scrolls the content. It reads `<style>`,
|
|
229
|
+
the version's linked stylesheets and their `@import`s, `style=""` on those elements, and
|
|
230
|
+
Tailwind's utilities where the page loads Tailwind, by the cascade (specificity, order,
|
|
231
|
+
`!important`, layers), so a later override is seen; each sheet once, at most 32 and 4 MiB a
|
|
232
|
+
page (its own `<style>` included), 1,024 layers, and layer names of 256 characters. The warning names what holds the page and
|
|
233
|
+
the rule that undoes it, e.g. `add html, body, #root { height: auto; overflow: visible;
|
|
234
|
+
position: static } after those rules`; only values of a known shape and plain selectors are
|
|
235
|
+
echoed (and the root's id, else `body > div`, or `body > *` for a custom element), each at most
|
|
236
|
+
60 characters with its `!important`. In `lintFiles` it reads the entry and at most 7 other
|
|
237
|
+
pages (path order), within one budget for them all (8 MiB of stylesheet, two million match
|
|
238
|
+
steps); past either, the pages left aren't checked, and one warning says how many. In `lintFiles` its `path` is the stylesheet's, where
|
|
239
|
+
the rule is there. Not read: rules under `@media` (but `all` and `screen`), `@supports`,
|
|
240
|
+
`@container`, `:is()`/`:where()`/`:not()` and sibling selectors, nested rules, `var()`, scripts.
|
|
241
|
+
- **The manual** (every kind): "It scrolls as a document: unless it's meant to fit one screen (a
|
|
242
|
+
game, a canvas), don't hold html, body or the element that holds it all to one screen …; a box that scrolls by itself takes the wheel while the
|
|
243
|
+
pointer is over it: keep those to parts of the page, never the whole of it."
|
|
244
|
+
- `LintRule` and `FileFinding["rule"]` take `"scroll-lock"`.
|
|
245
|
+
- **Drafts** (P107): `AnnotationMark.kind` is `"posted"` (the default, as absent) or `"draft"`. A
|
|
246
|
+
draft is drawn with a dashed underline (a dashed outline on an element) and a hollow marker with
|
|
247
|
+
no number, beside its words as a posted marker is; its click is `activated`, its place
|
|
248
|
+
`anchored`, and it is followed after a scroll, with or without a count. Posted marks are drawn,
|
|
249
|
+
sent and reported as before.
|
|
250
|
+
- **The page reads which marks are drafts**: send a person's drafts only to the frame that person
|
|
251
|
+
views (THREAT_MODEL §7). A draft's `count` is dropped before the frame.
|
|
252
|
+
- **Upgrade the content server's Porthole before sending drafts**: the shell is the content
|
|
253
|
+
server's. A shell before this one, given a draft by a newer host, draws it as a posted mark
|
|
254
|
+
without a marker (a solid underline, nothing to click), not apart.
|
|
255
|
+
- Any other `kind` is refused, as a bad anchor is: `annotations.show` throws; React's
|
|
256
|
+
`annotations` is refused (`onHostError`, kind `"annotations"`).
|
|
257
|
+
- New: `AnnotationMarkKind`.
|
|
258
|
+
|
|
259
|
+
## 0.10.0
|
|
260
|
+
|
|
261
|
+
After the review of P104 (P105): a host guards the view a marker's click opens, `activated` needs
|
|
262
|
+
a gesture, follow-ups share one clock, and text markers sit beside their line instead of over the
|
|
263
|
+
next word. What a host must act on comes first.
|
|
264
|
+
|
|
265
|
+
- **Act on these when upgrading:**
|
|
266
|
+
- **Guard the view a report opens or moves** (P105, THREAT_MODEL §6): a comment's bubble opened
|
|
267
|
+
on `activated`, or a composer placed by `selected` or `anchored`, takes no press of any kind
|
|
268
|
+
for 500 ms after it appears or moves, ignores a press that began before that, opens beside the
|
|
269
|
+
frame where the layout allows, takes no focus, and has no destructive action one click away.
|
|
270
|
+
The content chooses when it appears and where, and can bring it under the person's own press
|
|
271
|
+
in the content. ADOPTING.md § Annotations has the code (`guardPresses`: the view `inert` while
|
|
272
|
+
it arms); its portaled menus and popovers go in a container inside it, or are guarded too.
|
|
273
|
+
- **`activated` is taken only within a gesture** (P105): while the host's page has transient
|
|
274
|
+
user activation, as a real click or tap on a marker gives it. A custom `PlatformHost` whose
|
|
275
|
+
`userActivation()` answers `false` (rather than `undefined`, can't tell) drops every marker
|
|
276
|
+
click, as it refuses every gesture-gated call. A gesture anywhere on the page in the last 5 s
|
|
277
|
+
lets a fake through: the guard above is the defence.
|
|
278
|
+
- **`selected` comes again after a scroll only when its box moved** more than 0.5 px, and on the
|
|
279
|
+
same clock as `anchored`'s follow-ups: at most one report a second together (P105). A host's
|
|
280
|
+
button placed by the selection's box can lag a scroll by up to a second; the person's own new
|
|
281
|
+
selections are told at once, as before.
|
|
282
|
+
- **`parseAnchor` takes out of a label everything the person can't see** (P105): every format
|
|
283
|
+
character (bidi controls, zero-width ones), default-ignorable code point, variation selector,
|
|
284
|
+
tag, private-use character and control. A label stored before may come back shorter;
|
|
285
|
+
selectors are kept as they are.
|
|
286
|
+
- **Text markers beside their line** (P105, #36): centred on the anchor's last line, in the line's
|
|
287
|
+
gutter past its block; at the frame's right edge where the frame is too narrow; past the line's
|
|
288
|
+
last word where something else is beside the block (a table's cell, a card). Never over another
|
|
289
|
+
word but where two or three anchors end on one full line of a narrow screen; the number alone
|
|
290
|
+
where the bubble with its glyph doesn't fit. The pointer on a marker lights its words. A tap on a
|
|
291
|
+
marker is reported on WebKit too (it was never, since 0.9.0).
|
|
292
|
+
- **What the shell guarantees, said against what** (P105): a marker's press is unheard and can't
|
|
293
|
+
be cancelled, and the layer out of reach, against content that patches none of the built-ins.
|
|
294
|
+
The shell now reads and stops a press through the platform's own functions, so patching
|
|
295
|
+
`Event`'s or `MouseEvent`'s prototypes no longer lets content hear or suppress it; reaching the
|
|
296
|
+
layer's nodes through other built-ins still works (nothing there is secret).
|
|
297
|
+
- **A custom platform's `viewport()` that answers no size or throws** clamps every box to nothing
|
|
298
|
+
at the frame's corner, and nothing throws out of the frame's listener (it raised a TypeError).
|
|
299
|
+
- Negative controls `marker-prevent`, `marker-originals`, `marker-tap`, `marker-place`,
|
|
300
|
+
`follow-throttle`, `follow-count`, `selection-follow` and `annotation-activated-gesture`, in
|
|
301
|
+
`scripts/controls.ts`.
|
|
302
|
+
|
|
303
|
+
## 0.9.0
|
|
304
|
+
|
|
305
|
+
Annotation markers (P104): a host can show how many comments sit at each anchor, hear a click
|
|
306
|
+
on one, and follow the marks as the page scrolls. Every box a page reports is now held to the
|
|
307
|
+
frame, which changes what a host hears for a mark outside the viewport (below).
|
|
308
|
+
|
|
309
|
+
- **Annotation markers** (P104): `AnnotationMark.count` (0 to 999, `ANNOTATION_LIMITS.count`)
|
|
310
|
+
draws a small bubble with the number ("99+" above 99, the bubble alone for 0) at the end of a
|
|
311
|
+
text anchor and on an element's top right corner; that element's outline is then a thin line.
|
|
312
|
+
A click on a marker reaches none of the content's handlers and is reported as a new
|
|
313
|
+
`AnnotationReport`, `{ type: "activated", id, rect }` (`porthole/annotate.activated`), taken by
|
|
314
|
+
the host only for a mark it shows with a count. Open the host's own view of that mark with it,
|
|
315
|
+
never act on it: the content can fake it, can read every mark's count, and can tell that a
|
|
316
|
+
marker was pressed, and roughly where (it can't act on or cancel the click). Markers have no
|
|
317
|
+
tab stop; the host's own list of marks is the keyboard path.
|
|
318
|
+
- **Marks follow a scroll** (P104), while any mark has a count: once a scroll, a resize or a run of
|
|
319
|
+
content changes has settled (150 ms), `anchored` reports only the marks that moved since the
|
|
320
|
+
host was last told, at most once a second. A host that gives no counts hears exactly what 0.8
|
|
321
|
+
told it.
|
|
322
|
+
- **Reported boxes are clamped to the frame** (P104): every `rect` in `selected`, `activated`
|
|
323
|
+
and `anchored` reaches the host held to the frame's viewport as it is then; one wholly outside
|
|
324
|
+
becomes a box of no size on the nearest edge. A page can no longer make a host place its own UI
|
|
325
|
+
outside the frame. Act on this when upgrading: a mark scrolled out of the viewport is now told
|
|
326
|
+
on the edge it went past (below: `y` equals the viewport's height, `height` 0), not at its
|
|
327
|
+
place beyond it. A custom `PlatformHost` gives its surfaces `viewport()` (the new optional
|
|
328
|
+
`Surface.viewport`), or every box reaches the host as nothing at the frame's corner.
|
|
329
|
+
- **Wordless elements are named** (P104): a picked element with no text of its own (an image, an
|
|
330
|
+
icon button, a chart) is labelled by its `alt`, `aria-label` or `title`, in that order, instead
|
|
331
|
+
of its tag and classes alone.
|
|
332
|
+
- Negative controls `annotation-rect-clamp`, `annotation-activated`, `annotation-activated-count`,
|
|
333
|
+
`marker-trusted` and `marker-click`, in `scripts/controls.ts`.
|
|
334
|
+
|
|
335
|
+
## 0.8.0
|
|
336
|
+
|
|
337
|
+
The fixes from the security review of 0.7.0 (2026-10-19): P092–P095, P098–P101 and P103, each
|
|
338
|
+
with its regression; a release that waits for its commit's CI (P097); and a threat model (P102).
|
|
339
|
+
Most of it refuses more than 0.7 did. What a host must act on when it upgrades comes first.
|
|
340
|
+
|
|
341
|
+
- **Act on these when upgrading:**
|
|
342
|
+
- `callTool` defaults to a confirmation and 30 a minute; it was a confirmation alone (P103). A
|
|
343
|
+
host whose `confirm` says yes by itself, for a view that polls a tool more often than every
|
|
344
|
+
2 s, gives `callTool` its own `gates`.
|
|
345
|
+
- `setModelContext` defaults to 30 a minute and the new `show` gate (P100): the host shows the
|
|
346
|
+
person each update, whole, before it goes. Give `createHost` a `show` (`HostOptions.show`), or
|
|
347
|
+
the call is refused (`no-show`); the React provider shows updates with `ContextNotice` unless
|
|
348
|
+
`PortholeProvider.show` replaces it. A config that names its gates without `show` says so with
|
|
349
|
+
`withoutShow: true` (else it is warned of).
|
|
350
|
+
- Behind a proxy, set `rateLimit.trustedProxies` (how many proxies append to
|
|
351
|
+
`X-Forwarded-For`) or `rateLimit.key`. The issue endpoint's rate limit no longer reads
|
|
352
|
+
`X-Forwarded-For` by default: it keys an anonymous request by the socket's peer on Node and
|
|
353
|
+
`CF-Connecting-IP` on Workers, so without either setting every anonymous request through a
|
|
354
|
+
proxy shares that proxy's limit (P092).
|
|
355
|
+
- `callTool`'s arguments, `setModelContext`'s update and `downloadFile`'s contents are bounded
|
|
356
|
+
plain JSON or refused as malformed: an object reached twice, a `Date`, a `Map`, `NaN` or a
|
|
357
|
+
boxed value no longer passes (P095). A model-context update is text blocks and plain JSON, at
|
|
358
|
+
most 20,000 characters (`MAX_CONTEXT_CHARS`), with no invisible characters (P100).
|
|
359
|
+
- Under https Porthole's cookies are only its exact `__Host-porthole-` names: a `porthole-*`
|
|
360
|
+
cookie (which any sibling label can plant) is no longer read; loopback keeps its unprefixed
|
|
361
|
+
names (P101).
|
|
362
|
+
- A url-mode app answers its own origin only: a request with another `Origin`, or with
|
|
363
|
+
`Sec-Fetch-Site` `same-site` or `cross-site` that isn't a GET or HEAD navigation, is a 403, on
|
|
364
|
+
HTTP and on the socket path (`content.access`) alike (P101).
|
|
365
|
+
- Every served page carries its frame's sandbox in its CSP header and a `Permissions-Policy`
|
|
366
|
+
that denies what its frame's `allow` doesn't grant, on a tab as in a frame; on a tab the shell
|
|
367
|
+
opens no window (P099). An edge that rewrites headers keeps both.
|
|
368
|
+
- `presets.liveWidget` refuses a capability's `connect` or `resource` origins, and its config
|
|
369
|
+
is frozen (P103).
|
|
370
|
+
- New: `nodeListener(app, { scheme, onError })` (a fetch-style app as a Node listener) and
|
|
371
|
+
`onError` on `nodeHost`, `nodeServer` and `nodeListener` (P092); `tryIntersectDeclarations`,
|
|
372
|
+
which answers its problems instead of throwing (P093). The objects `intersectDeclarations`
|
|
373
|
+
returns have no prototype (P093).
|
|
374
|
+
- The declarations `declareCapabilities` and `intersectDeclarations` return hold objects with
|
|
375
|
+
no prototype (P093): an ORM or serializer that checks `constructor` (drizzle-orm does) refuses
|
|
376
|
+
them. Store a plain copy: `structuredClone` keeps every rule (a capability named `__proto__`
|
|
377
|
+
too). (Added after the release: porthole#32.)
|
|
378
|
+
- **The fixes:**
|
|
379
|
+
- **P092**: no request ends the Node process (a method fetch can't carry is a 405, anything
|
|
380
|
+
else it can't take a 400, a handler's failure a 500); the issue endpoint reads at most 64 KiB
|
|
381
|
+
of a body (`ISSUE_BODY_BYTES`); the rate limit's key is an address the client can't set.
|
|
382
|
+
- **P093**: `intersectDeclarations` reads each side as `dbAccess` does, wildcards included, so a
|
|
383
|
+
version keeps nothing the current declaration refuses; a collection named `__proto__` is a
|
|
384
|
+
rule.
|
|
385
|
+
- **P094**: a page's declared `data` names hold without a viewer; a result pushed with
|
|
386
|
+
`changed(result)` is a read, past `readData`'s gates; a `db` batch runs under its writes'
|
|
387
|
+
`methodGates` and a watch under its read's (`ConfirmRequest.askedBy` says which).
|
|
388
|
+
- **P095**: what content sends is read after its gate, into bounded text, and nothing it sends
|
|
389
|
+
throws out of an adapter; at most 10 confirmations wait per display.
|
|
390
|
+
- **P098**: a page of a file set whose notice arrives late is taken as the set's, not as a
|
|
391
|
+
navigation away (red on Chromium since 0.6.0); tests that waited a fixed time now wait for
|
|
392
|
+
what they check.
|
|
393
|
+
- **P099**: a served page on a tab of its own is sandboxed like its frame.
|
|
394
|
+
- **P100**: what content tells the model is shown to the person first, and what is shown is
|
|
395
|
+
what is sent; the manual calls it the content's unconfirmed text, never instructions.
|
|
396
|
+
- **P101**: siblings on the content domain: only `__Host-` names, an entered mark bound to its
|
|
397
|
+
label, and a url-mode app that answers its own origin.
|
|
398
|
+
- **P103**: a live widget takes no capability's origins; a trusted asset runs as code only while
|
|
399
|
+
the current config lets uploaded code run, in bearer mode too; `callTool` has a rate.
|
|
400
|
+
- **Release** (P097): a release is a commit of main whose CI passed, every job of it; the job
|
|
401
|
+
that publishes runs no project code; Actions are pinned to reviewed commits; third-party notices
|
|
402
|
+
for the vendored libraries and the leak suite's fixture.
|
|
403
|
+
- **Docs**: [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) (P102) says, use by use, what Porthole
|
|
404
|
+
guarantees, what the host must do, and what is out of scope; [SECURITY.md](SECURITY.md) says how
|
|
405
|
+
to report a vulnerability privately, which versions get fixes, and what happens next.
|
|
406
|
+
|
|
407
|
+
## 0.7.0
|
|
408
|
+
|
|
409
|
+
The capability runtime (P085–P090): a page published as an artifact is an app, and reaches its host
|
|
410
|
+
through one global, `porthole.use(name)`, under a contract pinned per artifact. Porthole provides
|
|
411
|
+
the mechanism (declarations, levels, the wire, the gates, the asset library's serving); the app
|
|
412
|
+
provides the services behind the handlers. Additive for 0.6 hosts: a config without `runtime` is
|
|
413
|
+
0.6's, frames, globals and manual alike.
|
|
414
|
+
|
|
415
|
+
- **The runtime** (P085): `config.runtime: "1"` (`presets.*({ runtime: "1" })`, inline widgets and
|
|
416
|
+
artifact pages). The shell defines `porthole`, frozen, with `use` only: `await
|
|
417
|
+
porthole.use("db")` is a frozen namespace or null (not offered, not declared, no host: the same
|
|
418
|
+
null), never a rejection. The roster comes in the handshake
|
|
419
|
+
(`hostCapabilities.experimental["porthole/runtime"]`); calls are `porthole/call { capability,
|
|
420
|
+
method, args }`, watches `porthole/event` / `porthole/unwatch`. Contract 1:
|
|
421
|
+
`clipboard`, `links`, `downloads`, `comments` (built in), `user`, `chat`, `data`, `context`,
|
|
422
|
+
`artifact`, `assets`, `db` (declared), each method served by one of the config's host functions
|
|
423
|
+
(`RUNTIME_CAPABILITIES`, the mapping in P085). New host functions: `user`, `comments`,
|
|
424
|
+
`artifact`, `assets`, `db`.
|
|
425
|
+
- **Types**: `types/runtime/v1/*.d.ts` (shipped; one per capability and the call contract), taught
|
|
426
|
+
by the manual's new `capabilities` topic with declaring, levels, errors and where state goes.
|
|
427
|
+
- **Declarations** (P086): `PageDeclaration` `{ capabilities, runtime }`; `declareCapabilities`
|
|
428
|
+
at publish (omitted carries forward with its pin, `{}` clears, an object replaces),
|
|
429
|
+
`declarationProblems`, `checkDeclaration`; `mount({ declaration })` (React: `declaration`). The
|
|
430
|
+
bridge refuses what a page didn't declare on every path, 0.6's requests included.
|
|
431
|
+
- **Levels** (P087): `view < interact < admin < owner`; each method's level (`CapabilityConfig.levels`
|
|
432
|
+
at or above its floor; a page may raise). `Grant.level` and `Grant.user` go in the issue's answer
|
|
433
|
+
(`FrameLocation.viewer`) through `httpLocator` to the bridge; `mount({ viewer })` (React:
|
|
434
|
+
`viewer`) otherwise. Refusals carry new codes: `forbidden`, `conflict`, `too_large`
|
|
435
|
+
(`REFUSAL_CODES`); handlers get `context.viewer` and `context.declared`.
|
|
436
|
+
- **State the host keeps** (P088, amending P023): `artifact.get()`/`publish({ base, files })`
|
|
437
|
+
(base-checked, admin), `db` (`get`, `query`, `onSnapshot`, `set`, `update`, `delete`, `batch`,
|
|
438
|
+
`ifVersion`, per-level `rules`, `data/users/<id>` private; `dbAccess` for the host's own API).
|
|
439
|
+
- **The asset library** (P089): `ServerOptions.assets` / `createContentHost({ assets })` serves
|
|
440
|
+
`/_blob/<id>` on the asset's own origin (its pages' loads, or a session with the host's check),
|
|
441
|
+
typed by name, never a page, inert, immutable; a page's CSP opens `<origin>/_blob/` for images,
|
|
442
|
+
media, fonts and data, and for scripts and styles only where uploads are the admins'.
|
|
443
|
+
- **Comments** (P090): `comments.open(anchor)` opens the host's composer at the page's anchor;
|
|
444
|
+
content hears only whether it opened.
|
|
445
|
+
- **Legacy**: 0.6's globals stay (`shell/legacy.ts`), untaught under a runtime, held to a declared
|
|
446
|
+
page's declaration.
|
|
447
|
+
- **Conformance**: `defineRuntimeConformance` (`/conformance`, no browser) runs an app's real
|
|
448
|
+
handlers through the bridge and past it; `leak/runtime/memory.ts` is the in-memory reference.
|
|
449
|
+
- **Leak suite**: `leak/served/runtime.spec.ts` on Chromium, WebKit and Firefox, with negative
|
|
450
|
+
controls `runtime-declaration`, `runtime-level`, `db-private`, `comments-result`, `blob-trusted`,
|
|
451
|
+
`blob-script,blob-trusted`, `blob-inert`, each required to fail exactly its probes
|
|
452
|
+
(`test:controls`, a CI job per engine).
|
|
453
|
+
- **From the security review of the first cut** (P091): assets need an access to their own artifact
|
|
454
|
+
and the host's check (`AssetStore.get(id, access)`, `StoredAsset.artifact`, `trusted`,
|
|
455
|
+
`bearer`; `assets.url(id)`; revalidated), db checks bounded and cheap ones first, gates per
|
|
456
|
+
method (`artifact.publish`, `assets.delete`: a click and a yes; `methodGates`), a batch at its
|
|
457
|
+
writes' levels and a watch at its read's, `data/users/me` in answers, no viewer refused above
|
|
458
|
+
view, own-property rules, watches ended on a new page, code-typed uploads refused where people
|
|
459
|
+
who interact upload, `MountOptions.declaration` required under a runtime (`null` for a page from
|
|
460
|
+
before 0.7), viewer ids one path segment, `intersectDeclarations`, `pseudonymFor`,
|
|
461
|
+
`defineRuntimeConformance({ api })`, `checkPage({ declaration })`, and a 0.6 config's own
|
|
462
|
+
`capabilities` topic kept.
|
|
463
|
+
|
|
464
|
+
## 0.6.0
|
|
465
|
+
|
|
466
|
+
A served page may be many files (P081–P084): a build's output, a report with its images, a
|
|
467
|
+
dashboard that reads its data, published as it was made. Additive: a store that answers `{ html }`
|
|
468
|
+
is served as in 0.5, and so is everything else.
|
|
469
|
+
|
|
470
|
+
- **The store** (`ArtifactStore.get`, the kit's `source`) may answer a `StoredFiles`: `files`
|
|
471
|
+
(`path → { size, sha256, type? }`), `entry` (default `index.html`), `spa`, and `read(path)` (a
|
|
472
|
+
`Uint8Array` or a `ReadableStream`, whole). The published type is never served.
|
|
473
|
+
- **Paths and limits** (`@botiverse/porthole`, `/server`): `checkFileSet(files, { entry, limits })`
|
|
474
|
+
for a host to call when a version is published (canonical, case-sensitive, no `..`/`.`/empty
|
|
475
|
+
segments, no leading `/`, no `\ % ? #`, control or format characters, NFC, length caps, no case-fold
|
|
476
|
+
collisions, no file that is also a directory, the entry present), `filePathProblem`,
|
|
477
|
+
`fileLimits(config.limits)`; the config's `limits.maxFiles`, `maxFileBytes`, `maxVersionBytes`
|
|
478
|
+
(1,000, 25 MiB, 100 MiB by default). `requestFilePath`, `lookupFile`, `fileTypeOf`.
|
|
479
|
+
- **Serving** (P081): every file from the manifest only (decoded once; `dir/` its `index.html`,
|
|
480
|
+
`name` its `name.html`, the nearest `404.html`, the entry for a single-page app's navigations),
|
|
481
|
+
typed by Porthole's table (unknown: `application/octet-stream`, a download), `nosniff`, a CSP
|
|
482
|
+
header on every answer (anything but a page or a script: `default-src 'none'; sandbox`), files
|
|
483
|
+
`private, max-age=31536000, immutable` with their sha256 as ETag, pages revalidated with an
|
|
484
|
+
ETag, 304s, `Range` (206, 416), `Cross-Origin-Resource-Policy: same-origin`, service workers
|
|
485
|
+
refused. Every page of a set is in the shell.
|
|
486
|
+
- **Addresses.** On a tab, `entry.at` answers a `FileAddress` (`{ instance, base, file }`) and the
|
|
487
|
+
latest's address (`/`, `/style.css`) is redeemed to the version's own (`/v/3/`, `/v/3/style.css`),
|
|
488
|
+
so a page never loads a newer version's file published while it loads; `pinned: true` makes its
|
|
489
|
+
files immutable there (only then); `versionedAddress(path)` and `versionBase(n)` read the usual
|
|
490
|
+
convention. A subresource on a clean address with no session gets a 401 (no entry, no cookie). In a frame, the ticket's answer is the entry,
|
|
491
|
+
whose files are at `/__porthole/f/<sealed access>/` (AES-GCM, so WebKit, which keeps no cookie
|
|
492
|
+
in frames, loads them too: P083). The address opens on its own for an hour, renewed by the shell;
|
|
493
|
+
reports name it `./`.
|
|
494
|
+
- **The CSP** of a page with files opens its version's own path for scripts, styles, fonts, images,
|
|
495
|
+
media, fetches and workers, never `'self'` (P082, amending P022). Opaque frames and single pages
|
|
496
|
+
are unchanged.
|
|
497
|
+
- **A set's pages open each other in the frame** (P084): the shell lets a navigation to a page of
|
|
498
|
+
its set go on and tells the host first (`porthole/navigating`, `NAVIGATING_METHOD`); the display
|
|
499
|
+
goes on. Anything else is still stopped (P079).
|
|
500
|
+
- **The agent's side:** `lintFiles(config, files)` (each page linted, every relative reference
|
|
501
|
+
looked up in the set, a page's `/`-rooted reference an error), `admitFiles`, `checkPage({ files
|
|
502
|
+
})` (the whole set served, its entry run), and the manual's Files section where a kind serves
|
|
503
|
+
files. Tool schemas are unchanged.
|
|
504
|
+
|
|
505
|
+
## 0.5.1
|
|
506
|
+
|
|
507
|
+
From Ferry's adoption of 0.5.0's live widgets (P080). Additive, except that a refused data call's
|
|
508
|
+
error message in the shell's globals is now a sentence for the person (its old text, `Refused
|
|
509
|
+
(denied)`, stays the JSON-RPC error's own message).
|
|
510
|
+
|
|
511
|
+
- **The host hears a navigation the shell stopped** (#12): `DisplayEvents.navigationBlocked`
|
|
512
|
+
(`{ url }`, the address whole; React `onNavigationBlocked`), and a `contentError` naming the
|
|
513
|
+
address without its query or fragment, so a host that passes content errors to the agent
|
|
514
|
+
(`errors: "agent"`) tells it its widget tried to leave its page. It is an error report: only
|
|
515
|
+
where the config declares `reportError`, within its reports and rate. The shell sends Porthole's
|
|
516
|
+
own `porthole/navigation-blocked` (`NAVIGATION_BLOCKED_METHOD`); both adapters carry it, MCP Apps
|
|
517
|
+
views included. Served frames only: an opaque frame's navigations get no events (the host hears
|
|
518
|
+
`navigated` when one replaces its document). `checkPage` reports it.
|
|
519
|
+
- **A host that refuses every data call needs no handlers** (#13): pass a `Refused` as `consent`
|
|
520
|
+
(`HostOptions.consent`, React's provider and frame `consent`), e.g.
|
|
521
|
+
`consent: new Refused("not_allowed", "Live data shows on the dashboard.")`: every
|
|
522
|
+
`consent`-gated call is refused with it, nothing is asked, and `readData`/`subscribeData` may be
|
|
523
|
+
declared without handlers. React compares it by value.
|
|
524
|
+
- **A refusal tells content why** (#14): a refused request's error carries
|
|
525
|
+
`data: { code, message }` (`RefusalReason`, `REFUSAL_CODES`): `consent_required`, `denied`,
|
|
526
|
+
`rate_limited`, `not_allowed` or `failed`, and a sentence to show. Hosts word their own with
|
|
527
|
+
`throw new Refused(code, message)` from a handler or a consent function (kept as the answer);
|
|
528
|
+
any other error a handler throws is `failed` in Porthole's words (its message stays the host's).
|
|
529
|
+
The shell's `readData` rejects, and `subscribeData`'s `onError` is called, with an `Error` whose
|
|
530
|
+
`code` is the code and whose `message` is the sentence. The manual teaches both. A consent
|
|
531
|
+
function that throws anything else is now `consent_required` to content (`denied` before).
|
|
532
|
+
|
|
533
|
+
## 0.5.0
|
|
534
|
+
|
|
535
|
+
Live widgets (P079): content that shows its host's data, current, read as the person viewing it,
|
|
536
|
+
with no network of its own. Additive, but every shell now cancels its served frame's own
|
|
537
|
+
navigations to another document (below).
|
|
538
|
+
|
|
539
|
+
- **`presets.liveWidget(options)`**: an inline widget whose egress stays closed (its options have
|
|
540
|
+
no `egress`; passing one throws). It declares `readData` and `subscribeData`, each behind the
|
|
541
|
+
viewer's consent and a rate (120 and 60 a minute). Served (domain isolation), it loads
|
|
542
|
+
Porthole's own libraries from its origin. `defineDisplays` takes it as a preset.
|
|
543
|
+
- **Porthole's libraries (`egress.libraries`)**: Chart.js 4.5.1 and D3 7.9.0 (`VENDORED_LIBRARIES`),
|
|
544
|
+
npm's files byte for byte with their licenses, served by `/server` on every content origin at
|
|
545
|
+
`/__porthole/lib/<name>@<version>/<file>` (no ticket, immutable). The frame's `script-src` gets
|
|
546
|
+
that path on the content origins, nothing else. Domain isolation only; the manual gives a
|
|
547
|
+
`<script>` line for each.
|
|
548
|
+
- **The `consent` gate**: `HostOptions.consent` (React: `PortholeProvider`/`PortholeFrame`
|
|
549
|
+
`consent`) is asked once per display before its first consent-gated call; a no refuses them all
|
|
550
|
+
(`denied`), none refuses them (`no-consent`). Not a default gate of `readData` (hosts that declare
|
|
551
|
+
it keep working); the live widget preset has it.
|
|
552
|
+
- **`subscribeData`** (a new capability, needs `readData`): MCP's `resources/subscribe` and
|
|
553
|
+
`resources/unsubscribe`, and `notifications/resources/updated` from the host, after which the
|
|
554
|
+
content reads again. Offered as `hostCapabilities.serverResources.subscribe`. The handler gets
|
|
555
|
+
`changed(result?)` and an `AbortSignal` (`SubscriptionContext`). Both adapters (the shell's and
|
|
556
|
+
`/mcp`'s) carry it.
|
|
557
|
+
- **The host's cache** (`HostOptions.cached`, `DataCache`; React `cached`): a read of a subscribed
|
|
558
|
+
resource is answered from it at once, marked `_meta["porthole/stale"]` (`STALE_META`), and the
|
|
559
|
+
fresh read follows as an update.
|
|
560
|
+
- **Shell globals**: `readData(uri)` (a promise of the value: JSON parsed, else text) and
|
|
561
|
+
`subscribeData(uri, onData, onError)` (onData(value, { stale, uri }) now and at every change;
|
|
562
|
+
returns a stop function). The manual teaches them, the consent and the libraries.
|
|
563
|
+
- **No frame navigates itself away**: the shell cancels every navigation its frame starts to
|
|
564
|
+
another document (the Navigation API's `navigate` event), so a served frame can't carry data in a
|
|
565
|
+
URL to another content origin, which the page's `frame-src` must allow. Reloads and
|
|
566
|
+
same-document navigations go on. Opaque frames get no navigate events; their wall stays the
|
|
567
|
+
page's `frame-src`. Negative control `navigate-guard`.
|
|
568
|
+
- A shell config that declares `readData` (inline, artifact) now gives content a `readData`
|
|
569
|
+
global, fixed in place like the others: content that defines its own `readData` must rename it.
|
|
570
|
+
- `checkPage` answers consent-gated calls as a viewer who says no; `lintContent` points live
|
|
571
|
+
widgets at the libraries served here and at `readData`.
|
|
572
|
+
|
|
573
|
+
## 0.4.1
|
|
574
|
+
|
|
575
|
+
- Annotation marks keep the words under them readable on a light page and a dark one: a lighter
|
|
576
|
+
fill (18%, 26% for the active mark) with an amber underline (text) or outline (an element), and
|
|
577
|
+
a ring around the active mark and a flash instead of more fill over its words (the 50% and 90%
|
|
578
|
+
yellow left light text yellow on dark yellow).
|
|
579
|
+
|
|
580
|
+
## 0.4.0
|
|
581
|
+
|
|
582
|
+
- `LIBRARY_CDNS` adds three libraries' own CDNs, for scripts only: Tailwind's Play CDN
|
|
583
|
+
(`https://cdn.tailwindcss.com`), jQuery (`https://code.jquery.com`) and Plotly
|
|
584
|
+
(`https://cdn.plot.ly`) (P078, #11). **Hosts that pass `LIBRARY_CDNS` get them on upgrade**;
|
|
585
|
+
write the list out to keep the old one. The manual gives each a pinned line, and tells agents
|
|
586
|
+
how Plotly's maps draw here (`topojsonURL`, the copy on jsDelivr); `lintContent` asks for a
|
|
587
|
+
version in their URLs. Verified against the real CDNs under every preset, on three engines.
|
|
588
|
+
- `checkPage`: nobody clicks in a check, on any engine: a call on load that needs a click is
|
|
589
|
+
refused and reported as a problem (Firefox counted the check's own evaluations as gestures).
|
|
590
|
+
|
|
591
|
+
## 0.3.5
|
|
592
|
+
|
|
593
|
+
- ADOPTING.md § "Choosing egress" (#7): the three levels (closed, `LIBRARY_CDNS`, passive kinds
|
|
594
|
+
from any https site) in one table, with the config for each, what it opens, the risk it
|
|
595
|
+
re-opens, who uses it, what the agent's manual says, and its decisions and tests; linked from
|
|
596
|
+
the README. The manual and the tool description word the any-https level the same way.
|
|
597
|
+
|
|
598
|
+
## 0.3.4
|
|
599
|
+
|
|
600
|
+
- A confirmation names the instance the host gave the frame in opaque frames too, not only served
|
|
601
|
+
ones (`request.display.instance`): `PortholeView` passes it either way, and an opaque frame never
|
|
602
|
+
gets it (P077).
|
|
603
|
+
|
|
604
|
+
## 0.3.3
|
|
605
|
+
|
|
606
|
+
- A confirmation names the instance a served frame shows (`request.display.instance`, in
|
|
607
|
+
`confirm` and `renderConfirm`), so a host can word its dialog from its own records (P076, #10).
|
|
608
|
+
- `ContentHost.start()` runs once; `nodeServer` starts a host made in its `listen` callback right
|
|
609
|
+
away instead of at the first request, and no longer starts again one the app started (P076,
|
|
610
|
+
#10).
|
|
611
|
+
|
|
612
|
+
## 0.3.2
|
|
613
|
+
|
|
614
|
+
- Every entry point bundles whole (P075): `/check` imports its check page's script as a module,
|
|
615
|
+
and `/conformance` its harness, instead of loading files beside the module at run time, which a
|
|
616
|
+
bundle (a single executable built by rolldown, a Worker) doesn't have. `checkPage` needs no
|
|
617
|
+
`page` option anywhere now. Each release is bundled with rolldown and esbuild, checked for loads
|
|
618
|
+
left for run time, and runs a check from its bundle before it is published (`test:bundle`).
|
|
619
|
+
|
|
620
|
+
## 0.3.1
|
|
621
|
+
|
|
622
|
+
From Ferry's and Raft Artifacts' adoptions of 0.3.0 and a second cold adoption (P074). Additive.
|
|
623
|
+
|
|
624
|
+
- `checkPage` runs a served config served: its own origin, the served CSP, shell, storage and
|
|
625
|
+
cookies, under an in-process server both drivers answer; errors name the content's own lines,
|
|
626
|
+
as the lint does. Configs that declare host functions can be checked (#8): each is answered as
|
|
627
|
+
a host that declines, and each call is reported (one hosts refuse is a problem, one a person
|
|
628
|
+
may decline a note). The manual's examples are checked under presets with every host function.
|
|
629
|
+
- React: flipping the provider's scheme, or a new themeKey, re-themes running frames in place;
|
|
630
|
+
it no longer makes every display again, losing widgets' state and reloading previews (#9).
|
|
631
|
+
- Sign-in comes back to `authorizeUrl` with the entry's state, never the request's own URL, so a
|
|
632
|
+
TLS edge or a dev proxy in front of the app no longer strands the person on the sign-in.
|
|
633
|
+
- `entryTarget(next, authorizeUrl, { app: true })` also takes the app's own pages.
|
|
634
|
+
`renderConfirm` gets `redirect()` ("redirected", not counted toward muting). `nodeServer` takes a
|
|
635
|
+
function for a host made after it listens. `entry.pathOf` may be async. A missing secret is
|
|
636
|
+
named. `portholeClient`'s functions pass bare (`this: void`). `PortholeView` renders its
|
|
637
|
+
placeholder or fallback on the server from the client's meta. `domain: null` is the documented
|
|
638
|
+
no-content-domain setup.
|
|
639
|
+
- Conformance: `@botiverse/porthole/conformance/reporter` prints why each case was skipped;
|
|
640
|
+
`contentSource` may be a function; `conformanceProjects` takes `use` and per-engine
|
|
641
|
+
`launchOptions` (a system Chromium).
|
|
642
|
+
- The examples run on `nodeServer` and `contentHostFor`, as ADOPTING recommends; ADOPTING says
|
|
643
|
+
when the other paths are right, how a page without a bundler loads Porthole's modules, and the
|
|
644
|
+
default authorize URL.
|
|
645
|
+
|
|
646
|
+
## 0.3.0
|
|
647
|
+
|
|
648
|
+
Developer experience, for the people adopting Porthole and the agents writing for it.
|
|
649
|
+
|
|
650
|
+
- The host kit's client, bootstrap and relay (P072): `defineDisplays` (one registry of display
|
|
651
|
+
kinds for the server, the page, the CSP and the manual); `content.routes(viewerOf)` (one mount
|
|
652
|
+
under `/porthole`: frames, authorize, meta, handoff; `issue` answers the clean `link`);
|
|
653
|
+
`contentHostFor` (Workers) and `nodeServer` (Node); `portholeClient`, `frameFallback`,
|
|
654
|
+
`entryTarget`; React `PortholeView`, `usePortholeLink`, `cssVariableTheme`, `useRunAgain`, and
|
|
655
|
+
provider-wide `scheme`, `theme`, `nonce: "auto"`, `handlers`, `openLink`, `notify`,
|
|
656
|
+
`renderConfirm`; the viewer handoff for token-authenticated pages; `upstreamHeaders`,
|
|
657
|
+
`statusPage`, cookie-clean `appSocket` and `content.forget()` for url-mode relays;
|
|
658
|
+
`health.onServedChange`; logger adapters.
|
|
659
|
+
- The agent's side (P073): `lintContent`, `admitContent` (the show tool refuses only what certainly
|
|
660
|
+
fails, saying what to change), `checkPage` with `playwrightDriver` and `cdpDriver` (Cloudflare
|
|
661
|
+
Browser Rendering), `showTool`, `guideTool`, `checkTool`, `answerGuide`, `guideChanges`, and an
|
|
662
|
+
MCP server example. Every example in the manual passes the check under every preset.
|
|
663
|
+
- Additive: every 0.2 import works. Apps move their old frame and authorize routes to
|
|
664
|
+
`/porthole` themselves.
|
|
665
|
+
|
|
666
|
+
## 0.2.4
|
|
667
|
+
|
|
668
|
+
- The package ships `docs/ADOPTING.md`, which 0.2.3's README links to and its build left out;
|
|
669
|
+
every doc in `docs/` is shipped from now on, and a test checks the README's links (P071).
|
|
670
|
+
|
|
671
|
+
## 0.2.3
|
|
672
|
+
|
|
673
|
+
- Adopting from the package alone (P071): a README with a quickstart, `docs/ADOPTING.md`, and
|
|
674
|
+
runnable examples (`examples/`: one app on Node and Workers, and the conformance suite against
|
|
675
|
+
it). `npx porthole secret` and `npx porthole d1-schema`. `MountOptions.fill` and
|
|
676
|
+
`<PortholeFrame fill>` are deprecated in favor of `layout.kind: "fill"`. The runner asks less of
|
|
677
|
+
an app that serves only stored pages (`instances.shell`, `entry.denied`, `atSignIn`,
|
|
678
|
+
`completeSignIn` optional; `entry.unknown: "derive"`; `conformancePage`, `conformanceProjects`,
|
|
679
|
+
`onDemand`). `14.inline-assets` reports an inherited block as inapplicable. Host errors no
|
|
680
|
+
longer quote ticket URLs. DESIGN's snippet fixed; `'unsafe-eval'` documented.
|
|
681
|
+
|
|
682
|
+
## 0.2.2
|
|
683
|
+
|
|
684
|
+
- From the host kit's first two adopters (P070, #5, #6): an address that names nothing (a label
|
|
685
|
+
the naming never makes, the bare domain, a path `entry.at` says has nothing) is a 404 on the
|
|
686
|
+
content domain, never a trip to the app's sign-in; `reserved` is only for labels the app
|
|
687
|
+
serves; the entry hooks get the address decoded (`EntryContext`) and `refusal` may return
|
|
688
|
+
nothing; `/server` exports `InstanceRef` and the other callback types; the server's pages talk
|
|
689
|
+
past a desktop scheme among the host origins (`ferry://app`), so framed url-mode apps no longer
|
|
690
|
+
hang; `nodeHost` streams with backpressure, stops with the client, and never ends a broken body
|
|
691
|
+
as whole; `health.onChange`; the runner takes async instances and entry addresses, adds
|
|
692
|
+
`served.entry.unknown`, and locates its tests in the app's spec file; the package ships the
|
|
693
|
+
docs.
|
|
694
|
+
|
|
695
|
+
## 0.2.1
|
|
696
|
+
|
|
697
|
+
- The manual, for a whole-page viewer (P069): "Call <guide tool> once" with `guideToolName`;
|
|
698
|
+
`layout.kind: "fill"` says the page fills the app's viewer (not the window), keeping
|
|
699
|
+
phone-width-first; `theme.documents: "never"` drops every theme line but "always light". The
|
|
700
|
+
`14.sound` probe reports itself inapplicable where the page's own CSP blocks its media.
|
|
701
|
+
|
|
702
|
+
## 0.2.0
|
|
703
|
+
|
|
704
|
+
- The host kit (P066): an app writes its policy (`instance`, `access`, `authorize`, `source`) and
|
|
705
|
+
its settings; Porthole does the rest. `createContentHost` (`/server`) gives the routing
|
|
706
|
+
middleware (reserved labels handed back), the issue endpoint (`{ instance }`, a proposal the
|
|
707
|
+
app maps; the client never chooses an origin), `meta`, `frameSources`, the content-domain
|
|
708
|
+
helpers (`contentDomain`, `ContentDomainError`: a clash throws at startup, or with the health
|
|
709
|
+
gate is a lasting "misconfigured", logged once) and the optional health gate with its opaque
|
|
710
|
+
fallback. New `/node` subpath: `nodeHost` (requests and WebSocket upgrades) and `nodeProbe`.
|
|
711
|
+
Client: `httpLocator`, `LocateError`, `servedOrOpaque`.
|
|
712
|
+
- Redirect entry (P068): `entry` gives every instance a clean address (`urlOf`) that opens
|
|
713
|
+
directly, through the app's authorize route (`authorize`) and its own sign-in, with a one-time
|
|
714
|
+
code bound to the address and the browser. Never the sign-in inside a frame (`FrameBlock`
|
|
715
|
+
`sign-in`); tickets stay the way frames load. `prefixedName` says a label's scope (`Naming`).
|
|
716
|
+
- The conformance runner: `defineHostConformance` / `hostConformance` run the leak suite, the
|
|
717
|
+
served cases and the redirect entry cases (`entryTests`) against an app's real page, with a
|
|
718
|
+
framework-free harness on `createHost` loaded under the page's nonce
|
|
719
|
+
(`dist/conformance/harness.js`). `served.url.ticket` uses a fresh browser.
|
|
720
|
+
- The prod-shape profile (`ops/prod-shape/run.sh`): Caddy's TLS, wildcard DNS, same-site
|
|
721
|
+
sibling origins, the kit reference app, a clash; CI on every push (checks, loopback on three
|
|
722
|
+
engines, prod shape).
|
|
723
|
+
- Compatible: every 0.1.x import works unchanged.
|
|
724
|
+
|
|
725
|
+
## 0.1.8
|
|
726
|
+
|
|
727
|
+
- The manual's silent line says where a block is reported, following `errors`: back to the agent
|
|
728
|
+
(`agent`), to the app only (`host`), to the app (unset), or nowhere (no `reportError`), so it no
|
|
729
|
+
longer contradicts the Errors line (#4, P067). `14.silent` checks the host's side too.
|
|
730
|
+
|
|
731
|
+
## 0.1.7
|
|
732
|
+
|
|
733
|
+
- The manual's "The sandbox:" list states every limit that silently changes behavior, derived
|
|
734
|
+
from the config (`manualLimits`), and each has a browser check (`LIMIT_CHECKS`, item-14 probes,
|
|
735
|
+
`served.domain.address`); a unit test fails on a line without one (P064). The forms advice is
|
|
736
|
+
now `type="button"` and a click handler: Chromium and Firefox fire no submit event in the
|
|
737
|
+
sandbox.
|
|
738
|
+
- A config can say a whole-page viewer's shape, and the manual and behavior follow (P065):
|
|
739
|
+
`layout.kind: "fill"` (every mount fills; fixed/sticky work), `theme.documents: "never"`
|
|
740
|
+
(always light, no theme changes), `storage.scope` (what one display's storage is kept for),
|
|
741
|
+
`errors: "agent" | "host" | "none"` (where content errors go); `limits.maxBytes` stated in KB
|
|
742
|
+
or MB. `LaunchSpec.heightPx` for checks that fill.
|
|
743
|
+
|
|
744
|
+
## 0.1.6
|
|
745
|
+
|
|
746
|
+
- `served.domain.egress` holds a host to its own config's egress (P062).
|
|
747
|
+
|
|
748
|
+
## 0.1.5
|
|
749
|
+
|
|
750
|
+
- Wildcards over public suffixes refused (P060); passive content from any https site by
|
|
751
|
+
`egress.anyHttps` (P059); inapplicable cases reported, not failed (P058); theme events only on
|
|
752
|
+
a change (P061).
|
|
753
|
+
|
|
754
|
+
## 0.1.4
|
|
755
|
+
|
|
756
|
+
- Content and host errors apart (P055); nonce support (P054); `/server` routing (P056); fill
|
|
757
|
+
mode, by-value React props, settled annotations, shared-storage note (P057).
|
|
758
|
+
|
|
759
|
+
## 0.1.3
|
|
760
|
+
|
|
761
|
+
- Content never writes the clipboard (P051); `copyText` (P052); annotations (P053).
|
|
762
|
+
|
|
763
|
+
## 0.1.2
|
|
764
|
+
|
|
765
|
+
- `/server` on Workers with D1 tickets (P044, P045); anonymous grants (P046); host naming
|
|
766
|
+
(P047); artifact CDN opt-in (P048); url-mode delegation (P049); the host's check (P050).
|
|
767
|
+
|
|
768
|
+
## 0.1.1 and 0.1.0
|
|
769
|
+
|
|
770
|
+
- Phase 1's milestones (M1–M5) and the first host's adoption fixes.
|