@botiverse/porthole 0.14.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 +4 -1
- package/dist/annotate/types.js +2 -0
- package/dist/annotate/validate.d.ts +2 -1
- package/dist/annotate/validate.js +11 -4
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.js +2 -2
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +5 -0
- package/dist/host/types.d.ts +7 -0
- package/dist/react/frame.d.ts +4 -3
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +4 -3
- package/dist/server/naming.js +4 -0
- package/dist/server/nested.d.ts +24 -2
- package/dist/server/nested.js +28 -2
- package/dist/server/server.js +145 -25
- package/dist/server/types.d.ts +5 -0
- package/dist/shell/annotate.d.ts +3 -2
- package/dist/shell/annotate.js +22 -2
- package/dist/shell/runtime.d.ts +6 -0
- package/dist/shell/runtime.js +11 -1
- package/docs/ADOPTING.md +36 -7
- package/docs/ARCHITECTURE.md +10 -5
- package/docs/DECISIONS.md +207 -1
- package/docs/DESIGN.md +12 -4
- package/docs/THREAT_MODEL.md +30 -3
- package/package.json +6 -5
- package/src/annotate/types.ts +4 -1
- package/src/annotate/validate.ts +11 -6
- package/src/compile/policy.ts +2 -2
- package/src/host/create-host.ts +5 -0
- package/src/host/types.ts +7 -0
- package/src/react/frame.tsx +4 -3
- package/src/server/index.ts +6 -2
- package/src/server/naming.ts +4 -0
- package/src/server/nested.ts +32 -2
- package/src/server/server.ts +168 -24
- package/src/server/types.ts +5 -0
- package/src/shell/annotate.ts +22 -2
- package/src/shell/runtime.ts +12 -1
package/docs/ADOPTING.md
CHANGED
|
@@ -267,8 +267,19 @@ display.on("annotation", (report) => {
|
|
|
267
267
|
if (report.type === "activated") bubble.openBeside(frame, report.rect, report.id);
|
|
268
268
|
if (report.type === "anchored") bubble.follow(report.results);
|
|
269
269
|
});
|
|
270
|
+
// The selection was used (a comment posted, a draft added): take it, and its highlight, away.
|
|
271
|
+
composer.onDone(() => display.annotations.clearSelection());
|
|
270
272
|
```
|
|
271
273
|
|
|
274
|
+
- **Clear the selection once you used it** (`annotations.clearSelection()`, P115): the page's text
|
|
275
|
+
selection, and the highlight the browser leaves on it (gray while focus is in your composer),
|
|
276
|
+
stay until something clears them; the person's next click in the page would, and this does it
|
|
277
|
+
when your composer is done with it. No `unselected` follows it (you know), and nothing else
|
|
278
|
+
changes: your marks and drafts, the mode (`start`) and a followed mark stay. With nothing
|
|
279
|
+
selected it does nothing; it is never sent to a frame that runs later (a reload has no selection
|
|
280
|
+
to clear). Like `start` and `show`, only where the config declares `annotate`. The shell is your
|
|
281
|
+
content server's: an older one ignores it.
|
|
282
|
+
|
|
272
283
|
- **Ids say nothing, and a count only where the page may know it**: the content reads every
|
|
273
284
|
`show`. Who wrote what stays in your view, outside the frame.
|
|
274
285
|
- **Drafts only to their author's frame**: the page reads which marks are drafts (that its viewer
|
|
@@ -544,7 +555,10 @@ entry: {
|
|
|
544
555
|
### Nested pages: the page below Porthole's shell
|
|
545
556
|
|
|
546
557
|
`nested: true` (P111) on an artifact kind served by the host kit puts the page in a frame of its
|
|
547
|
-
own below Porthole's shell,
|
|
558
|
+
own below Porthole's shell, with an opaque origin of its own. The shell, the page and its files are
|
|
559
|
+
served on a label of the scope's own, `porthole-<24 base32>.<content domain>` (P114), not on the
|
|
560
|
+
scope's label: the scope's other displays run content there with `allow-same-origin`, which would
|
|
561
|
+
reach the shell (porthole#56). Do it where people
|
|
548
562
|
type beside your displays: in full Chromium (a person's browser, not Playwright's headless shell) a
|
|
549
563
|
served page's frame is out of process, and your page can't see a press in it, so without nesting a
|
|
550
564
|
real click into the page's field is taken back and `comments.open` from a real click is refused
|
|
@@ -561,7 +575,15 @@ const displays = defineDisplays({
|
|
|
561
575
|
```
|
|
562
576
|
|
|
563
577
|
Nothing else changes on your page: the same `createHost` (or `PortholeFrame`), the same handlers
|
|
564
|
-
and events, the same `frame-src
|
|
578
|
+
and events, the same `frame-src` (the content domain's wildcard covers the shell's label). Your
|
|
579
|
+
frames route answers the shell's origin (`issue`'s location); a clean address stays on the scope's
|
|
580
|
+
label and sends the browser on to the shell's with a one-time ticket.
|
|
581
|
+
|
|
582
|
+
**Route the shell's label.** `porthole-<…>.<content domain>` must reach the content server as
|
|
583
|
+
your other labels do. Wildcard DNS and a wildcard certificate (`*.<content domain>`) already cover
|
|
584
|
+
it; a route, an edge rule or a firewall that matches labels by a pattern of yours (`a-*`) must let
|
|
585
|
+
`porthole-*` through too. Every `porthole-` label is Porthole's: your naming may not make one
|
|
586
|
+
(`content.name` giving one throws), and `reserved` may not hold one a shell would be on. The display has one more event, `storage` (`{ used }`, once per
|
|
565
587
|
run: whether the page touched `localStorage` or `sessionStorage`, never what it kept), for you to
|
|
566
588
|
count the pages that would need storage. A nested page's workers come from Blob URLs (a worker from
|
|
567
589
|
a script of its own set is refused: its origin is opaque), which may `importScripts` the set's
|
|
@@ -569,14 +591,21 @@ scripts; Chromium refuses a Blob module worker there. Not yet with a nested page
|
|
|
569
591
|
and Porthole's libraries (`egress.libraries`); the config refuses them.
|
|
570
592
|
|
|
571
593
|
What a content origin serves for a nested page (`/server` does all of it; a content Worker of your
|
|
572
|
-
own answers the same, with the helpers `/server` exports: `nestedShellResponse`,
|
|
573
|
-
`NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the
|
|
574
|
-
`https://<label>.<content domain
|
|
575
|
-
|
|
594
|
+
own answers the same, with the helpers `/server` exports: `nestedLabelOf`, `nestedShellResponse`,
|
|
595
|
+
`NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the shell's own,
|
|
596
|
+
`https://<nestedLabelOf(label)>.<content domain>`, where `label` is the scope's label (the one its
|
|
597
|
+
other displays are served on); `<token>` is the access in the path (Porthole's sealed session, or a
|
|
598
|
+
signed token of your own: the shell only needs addresses under the prefix). Your frame location
|
|
599
|
+
for a nested page is on `<origin>`.
|
|
600
|
+
|
|
601
|
+
**The rule** (P114): `<origin>` answers the four rows below and Porthole's status pages, nothing
|
|
602
|
+
else (no other display, no clean address, no asset, no app), and the scope's label never answers a
|
|
603
|
+
nested page's shell, page or files. That is what keeps the shell's realm (its word to your page,
|
|
604
|
+
the page's sealed address) out of every other display's reach.
|
|
576
605
|
|
|
577
606
|
| Request | Answer |
|
|
578
607
|
| --- | --- |
|
|
579
|
-
|
|
|
608
|
+
| `<origin>/__porthole/d/<key>`, the framed address (a ticket's, a cookie's reload; an entered clean address on the scope's label answers a `303` here with a one-time ticket), a navigation | 200, `text/html`: Porthole's shell, `nestedShellResponse(compiled, { origin, origins: hostOrigins, page: "<origin>/__porthole/f/<token>/<entry>", renew: { url: "<origin>/__porthole/f/<token>/__porthole/renew", expires } })`. Headers: `Content-Security-Policy: default-src 'none'; script-src 'sha256-<its script>'; frame-src <origin>/__porthole/f/; connect-src <origin>/__porthole/f/; base-uri 'none'; form-action 'none'; frame-ancestors <host origins>`; `Cache-Control: no-store`; `Referrer-Policy: no-referrer`; `X-Content-Type-Options: nosniff`; the served `Permissions-Policy`. No content in it. Any other request there: 404. |
|
|
580
609
|
| `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy: <the page's directives, its files' prefix opened>; sandbox allow-scripts; frame-ancestors <origin> <host origins>` (never `allow-same-origin`). Access from `<token>` alone: no cookie is sent (the page's origin is opaque), and never decide by `Origin` (it is `null`) or `Sec-Fetch-Site` (`cross-site`). |
|
|
581
610
|
| `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin`: a non-page file `default-src 'none'; sandbox`, a script its directives plus `sandbox`, so none opened on a tab of its own (an SVG, an XML file) runs on the shell's origin. |
|
|
582
611
|
| `<origin>/__porthole/f/<token>/__porthole/renew` | Only the shell's own fetch (`Sec-Fetch-Site: same-origin`, not a navigation): `{ "base": "<origin>/__porthole/f/<new token>/", "expires": <epoch ms> }`, `no-store`; anything else 403. The shell renews 5 minutes before `expires` and moves the page to the new base. |
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -202,13 +202,14 @@ holds the page and needs no stable origin, the shell writes it into an opaque
|
|
|
202
202
|
frame instead.
|
|
203
203
|
|
|
204
204
|
A **nested** page (P111) splits the shell from the page. The address the host frames
|
|
205
|
-
serves Porthole's shell alone: a document with no content, on
|
|
205
|
+
serves Porthole's shell alone: a document with no content, on an origin of its own (a
|
|
206
|
+
label of the scope's, `porthole-<…>`, on which nothing else is ever served, P114). It
|
|
206
207
|
frames the page in a child sandboxed without `allow-same-origin` (an opaque origin) at
|
|
207
|
-
the page's sealed files' address, fetched without a cookie, and passes
|
|
208
|
-
the host and the page:
|
|
208
|
+
the page's sealed files' address on that origin, fetched without a cookie, and passes
|
|
209
|
+
messages between the host and the page:
|
|
209
210
|
|
|
210
211
|
```
|
|
211
|
-
Host app Shell (
|
|
212
|
+
Host app Shell (its own origin) Page (opaque child)
|
|
212
213
|
│ frame src = ticketed URL ──►│ frames the sealed address ───►│ runtime + page
|
|
213
214
|
│◄── the page's messages ──────│◄── postMessage (by source) ───│
|
|
214
215
|
│── the host's messages ──────►│── postMessage ───────────────►│
|
|
@@ -281,7 +282,11 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
|
|
|
281
282
|
bounds it and uses it as a UI hint, never as a permission (P053).
|
|
282
283
|
A nested page (P111) is the one place they don't: the shell is a document of its
|
|
283
284
|
own, the page's parent, on another origin than the page's (opaque), so the page
|
|
284
|
-
reaches nothing of the shell's realm.
|
|
285
|
+
reaches nothing of the shell's realm. Nor does any other content: the shell's
|
|
286
|
+
origin is a label of its own that hosts nothing but nested pages' shells, their
|
|
287
|
+
opaque pages, those pages' files and status pages (P114), never the scope's
|
|
288
|
+
origin, where the scope's other displays run content with `allow-same-origin`
|
|
289
|
+
(porthole#56). The server holds that rule, not the host's layout. The shell trusts the page's messages by
|
|
285
290
|
`event.source` alone and passes them on unchanged, never in its own namespace
|
|
286
291
|
(`porthole/shell/`); what it says in that namespace is the shell's own word (its
|
|
287
292
|
transient activation, which only a press or key in the page turns on, and whether
|
package/docs/DECISIONS.md
CHANGED
|
@@ -4595,7 +4595,7 @@ second wall on a tab); a host needs a served page to open windows from a tab (th
|
|
|
4595
4595
|
`'self'` default (it joins `FRAME_DENIED_FEATURES`); or WebKit and Firefox apply
|
|
4596
4596
|
`Permissions-Policy` to these features (the shell's device locks become the second wall there too).
|
|
4597
4597
|
|
|
4598
|
-
## P104 · 2026-10-20 · Annotation markers: a number at an anchor, a click the host hears, marks that follow a scroll · Accepted; amended by P105, P107
|
|
4598
|
+
## P104 · 2026-10-20 · Annotation markers: a number at an anchor, a click the host hears, marks that follow a scroll · Accepted; amended by P105, P107, P116
|
|
4599
4599
|
|
|
4600
4600
|
A host that shows its comments beside an artifact page wants, at each comment's anchor in the page,
|
|
4601
4601
|
a small marker (a bubble and how many comments are there) that scrolls with the content; a click on
|
|
@@ -6052,3 +6052,209 @@ takes it only while it asked for it. Each item below landed on its own, with its
|
|
|
6052
6052
|
`comments` (the host's own UI; the composer is the person's, under the host's duties), and `user`
|
|
6053
6053
|
(it only reads). Tested: `test/pass-on.test.ts`, each channel alone.
|
|
6054
6054
|
|
|
6055
|
+
## P115 · 2026-10-28 · The host clears the page's selection: `annotations.clearSelection()` · Accepted
|
|
6056
|
+
|
|
6057
|
+
**Context.** In a comment mode (Raft's web app, Kirby) the person selects words, the host's
|
|
6058
|
+
composer opens beside them, and they post a comment or add a draft. The selection stays: the
|
|
6059
|
+
browser keeps drawing it (gray, since focus is in the host's composer) over words that now carry
|
|
6060
|
+
a mark, until the person clicks in the page. 0.13 and 0.14 give the host no way to clear it;
|
|
6061
|
+
Kirby asked for one (`selection.clear()`) to call once the selection is used.
|
|
6062
|
+
|
|
6063
|
+
**Decision.** `display.annotations.clearSelection()`, beside `start`, `stop`, `show`, `focus`,
|
|
6064
|
+
`track` and `clear` (a control of the display's annotations, named for what it clears: `clear`
|
|
6065
|
+
already means every mark). It sends `porthole/annotate.clearSelection` (no params) to the frame,
|
|
6066
|
+
only where the config declares `annotate` (else it throws, as the others do), and to no frame that
|
|
6067
|
+
runs later (nothing is kept: a new frame has no selection). The shell then:
|
|
6068
|
+
|
|
6069
|
+
- removes the page's selection with `Selection.prototype.removeAllRanges` as it was before content
|
|
6070
|
+
ran (taken with the DOM's other functions), on `Document.prototype.getSelection`'s answer, so a
|
|
6071
|
+
page that replaced either keeps nothing the host cleared;
|
|
6072
|
+
- forgets what it held of it: the report waiting for the selection to settle (250 ms), the one it
|
|
6073
|
+
last told and its box, and a scroll's follow-up of it. So nothing is told back: the
|
|
6074
|
+
`selectionchange` the clear makes finds nothing to report (no `unselected`: the host knows), and
|
|
6075
|
+
the same words selected again are a new selection, told as any is;
|
|
6076
|
+
- changes nothing else: marks (posted and drafts), the active and the followed mark, the mode,
|
|
6077
|
+
and an element picked. With nothing selected it is a no-op; it clears in any mode, text
|
|
6078
|
+
selection on or not (the host is trusted with the page's view, as it is with `focus`, which
|
|
6079
|
+
scrolls it).
|
|
6080
|
+
|
|
6081
|
+
There is no highlight of Porthole's own to remove: a settled selection is drawn by the browser
|
|
6082
|
+
(the shell draws marks, and an outline only while picking).
|
|
6083
|
+
|
|
6084
|
+
**Trust.** Host to frame only. The host takes no `clearSelection` from a frame (it is no report);
|
|
6085
|
+
the shell takes it only from its frame's parent and the host's origins, as every host message
|
|
6086
|
+
(a page that posts it to its own window is dropped). It gives the page nothing it hasn't: a page
|
|
6087
|
+
can clear or select its own text at any time, and can select the words again right after (the
|
|
6088
|
+
host hears that as a selection, while it asked for text). A report the shell posted just before
|
|
6089
|
+
the clear arrived (a selection that settled in the same moment) still reaches the host after its
|
|
6090
|
+
call; a host that cares drops a `selected` it gets right after clearing, as it would one it
|
|
6091
|
+
didn't ask for.
|
|
6092
|
+
|
|
6093
|
+
**Rejected.** A `selection` namespace (`display.selection.clear()`, as Kirby wrote it): the
|
|
6094
|
+
selection is the annotation runtime's (only `annotate` reports it), and one namespace for
|
|
6095
|
+
annotations is what hosts already hold. Clearing the selection inside `stop()` or `clear()`: a
|
|
6096
|
+
host stops the mode or redraws its marks for other reasons, with a selection the person still
|
|
6097
|
+
means to use. Telling the host `unselected` after a clear: it would arrive after the host's own
|
|
6098
|
+
call, as if the person did it, and a host that opens or closes UI on it would act twice.
|
|
6099
|
+
Clearing through the page's own `getSelection().removeAllRanges()`: a page (or a library it
|
|
6100
|
+
loads) that patched it would keep the highlight.
|
|
6101
|
+
|
|
6102
|
+
Tested: `test/annotate.test.ts` (sent as it is, after the handshake only, never replayed, throws
|
|
6103
|
+
without `annotate`; the shell uses the function it took); `leak/annotate.spec.ts` "clearSelection
|
|
6104
|
+
takes the page's selection away and tells nothing back; marks and drafts stay, the next selection
|
|
6105
|
+
is told (P115)", on a page that replaced `removeAllRanges`, with no selection, in text mode and with
|
|
6106
|
+
the mode stopped; `leak/served/nested.spec.ts` "the host's clearSelection reaches the nested page
|
|
6107
|
+
through its shell (P115)"; negative control `clear-selection` (the page's own `removeAllRanges`, and the
|
|
6108
|
+
told selection kept: each alone fails the probe, measured on Chromium).
|
|
6109
|
+
|
|
6110
|
+
**Revisit when** a host needs the element picked (`elements: true`) or a held block cleared too
|
|
6111
|
+
(they leave no highlight now), or the MCP Apps spec gains a host-to-view way to clear a selection.
|
|
6112
|
+
|
|
6113
|
+
## P114 · 2026-10-28 · A nested page's shell on a label of its own, where nothing else is ever served · Accepted
|
|
6114
|
+
|
|
6115
|
+
**Context.** porthole#56 (Ferry's audit of what merged after 0.13.0). P111 rests on the shell
|
|
6116
|
+
being a realm content can't reach (ARCHITECTURE "Trust boundaries" 4): the host trusts the shell's
|
|
6117
|
+
word (`porthole/shell/state`: the keyboard rule, `comments.open`), and the shell holds the page's
|
|
6118
|
+
sealed files' address, a bearer credential (P083). The opaque page can't reach it. But the shell
|
|
6119
|
+
was served on its scope's content origin, where every other domain-mode display of the scope (an
|
|
6120
|
+
inline widget, a live widget, an MCP app, an artifact that isn't nested) runs agent-made content
|
|
6121
|
+
with `allow-same-origin`. Such a display on the host's page is same-origin with the shell: from a
|
|
6122
|
+
plain artifact or an inline widget of the same scope, `parent.frames[0].document` was the shell,
|
|
6123
|
+
its page's frame inside it (measured by Ferry on the headless shell, full Chromium and Firefox). So
|
|
6124
|
+
it could make the shell's word say "the person pressed" (P109's threat back for nested pages) and
|
|
6125
|
+
take the sealed address. P0 for a host that maps several artifacts to one scope. Nothing refused
|
|
6126
|
+
the mix: `nested` can't have `storage`, `assets` or `egress.libraries`, so a nested kind beside
|
|
6127
|
+
other kinds of one scope is the expected layout. The nested suite missed it because each of its
|
|
6128
|
+
cases had a scope of its own.
|
|
6129
|
+
|
|
6130
|
+
**Decision.** The shell's origin hosts nothing but nested pages' shells, their opaque pages, those
|
|
6131
|
+
pages' files and Porthole's status pages. `/server` holds the rule; it isn't left to how a host
|
|
6132
|
+
lays out `defineDisplays` or names its scopes.
|
|
6133
|
+
|
|
6134
|
+
- **The label.** A nested page is served on `nestedLabelOf(label)`: `porthole-` and 24 base32
|
|
6135
|
+
characters (120 bits) of the SHA-256 of `porthole/nested/<the scope's label>`. One per scope:
|
|
6136
|
+
every nested page of the scope shares it, as they shared the scope's origin before (only
|
|
6137
|
+
Porthole's shell runs there with that origin, and each page is opaque and opens only with its
|
|
6138
|
+
own sealed address). Not keyed and not secret: it says nothing the scope's label doesn't, and a
|
|
6139
|
+
content Worker of a host's own works it out from the label alone. It is one label under the
|
|
6140
|
+
content domain, so its wildcard DNS name, its wildcard certificate and the hosts'
|
|
6141
|
+
`frame-src https://*.<domain>` already cover it.
|
|
6142
|
+
- **What it answers.** The frame's address (`/__porthole/d/<key>`: the shell), the sealed
|
|
6143
|
+
prefix (`/__porthole/f/<token>/…`: the page, its files, the renewal, each with a CSP sandbox
|
|
6144
|
+
without `allow-same-origin`, P111), and Porthole's status pages and their script. Anything else
|
|
6145
|
+
is a 404 there: no clean address, entry, asset (`/_blob/`), library, session check or url-mode
|
|
6146
|
+
app. A ticket, cookie or sealed address is good there only for a nested page whose shell's label
|
|
6147
|
+
it is; and on the scope's label never for a nested page (its ticket, cookie or sealed address is
|
|
6148
|
+
refused there: a 401).
|
|
6149
|
+
- **No content label is ever one.** The keyed default has no hyphen; every `porthole-` label is
|
|
6150
|
+
Porthole's own: `content.name` giving one throws (as a reserved label does), and
|
|
6151
|
+
`prefixedName("porthole-")` throws. A shell's label the host reserved (`content.reserved`)
|
|
6152
|
+
makes `issue` throw: the request would go to the host's routes.
|
|
6153
|
+
- **Where the frame is.** `issue` answers the shell's origin for a nested page
|
|
6154
|
+
(`FrameLocation.origin`, and its `url`); the host page's checks take it as they take any served
|
|
6155
|
+
origin (it matches the content source, it isn't the host's site). `originFor(scope)` and
|
|
6156
|
+
`urlOf(scope, path)` stay the scope's: they are where its other displays and its clean addresses
|
|
6157
|
+
are.
|
|
6158
|
+
- **A clean address** (P068) stays on the scope's label: the entry, its code and its session are
|
|
6159
|
+
there, as before. Opened for a nested page, the scope's label answers it with a `303` to the
|
|
6160
|
+
shell's label (`/__porthole/d/<key>?ticket=<one-time>`): a ticket of its own for the same access
|
|
6161
|
+
(viewer, subject, anonymous), good for 60 s, buying what is left of the session, with the path
|
|
6162
|
+
below the file set's base the address asked for (`TicketRecord.page`, checked: a relative path,
|
|
6163
|
+
no dot segment, no query). The shell's label sets its own session there, so a reload rides on
|
|
6164
|
+
it; the scope's label never answers the shell.
|
|
6165
|
+
- **An entry code is no ticket.** A document's address takes a ticket from `issue` (or a hop)
|
|
6166
|
+
only, never an entry code (`TicketRecord.entry`), which opens its entry alone with its own
|
|
6167
|
+
browser's nonce. Before, a code could stand in for a ticket at the scope's label's
|
|
6168
|
+
`/__porthole/d/`; at the shell's it would have skipped the nonce (an attacker's session planted
|
|
6169
|
+
in a victim's frame).
|
|
6170
|
+
- `configFor` checks that a nested config's `contentOrigins` match a shell's sample origin too.
|
|
6171
|
+
|
|
6172
|
+
**Threat it closes.** A same-scope display reading or driving the shell: the shell's word to the
|
|
6173
|
+
host, its focus and activation, the page's sealed address. A content display is now never
|
|
6174
|
+
same-origin with any shell (its label is never a `porthole-` one), whatever the host's scopes.
|
|
6175
|
+
|
|
6176
|
+
**Limits.** On a tab, a nested page's clean address ends at the shell's document address (with its
|
|
6177
|
+
spent ticket), not the clean one; a reload rides the shell's session, and after it ends that
|
|
6178
|
+
address says "This link has been used" where the clean one would sign in again. The hop's ticket is
|
|
6179
|
+
in a `Location`, as exposed as `issue`'s frame address (P020): one use, a minute. A host that frames
|
|
6180
|
+
a clean address itself (not `issue`'s location) gets the shell's origin after the hop; with
|
|
6181
|
+
`createHost` the frame's origin is the location's, so such a host frames `issue`'s location.
|
|
6182
|
+
|
|
6183
|
+
**Rejected.**
|
|
6184
|
+
- A label in the form IDNA reserves (`??--`), which no host's naming can make today (P047): ACME
|
|
6185
|
+
CAs (Let's Encrypt) refuse certificates for such names, so a host with a certificate per name
|
|
6186
|
+
couldn't serve it. The `porthole-` prefix narrows what a host may name instead (the kit's health
|
|
6187
|
+
gate already reserved `porthole-health`).
|
|
6188
|
+
- A deeper name (`<x>.n.<domain>`): a second wildcard certificate and DNS name for every host.
|
|
6189
|
+
- A keyed label: a host's own content Worker couldn't work it out without the server's secret, and
|
|
6190
|
+
it would hide nothing the scope's label shows.
|
|
6191
|
+
- A label per page instead of per scope: nothing runs on the shell's origin but the shell, so
|
|
6192
|
+
per scope is enough, and its sessions stay per scope as before.
|
|
6193
|
+
- Refusing other kinds of a nested kind's scope (in `defineDisplays`, or at `issue`): the layout is
|
|
6194
|
+
the expected one, and scopes are the host's, not the registry's.
|
|
6195
|
+
- The shell on the scope's label on a tab only (a clean address): a same-scope page could open it
|
|
6196
|
+
in a window it names and reach its realm.
|
|
6197
|
+
|
|
6198
|
+
**Adopters.** Every host on `/server` or the host kit: the shell's label is under the content
|
|
6199
|
+
domain's wildcard, so wildcard DNS and a wildcard certificate need nothing; an edge, a route or a
|
|
6200
|
+
firewall that matches labels by pattern (`a-*.<domain>`) must let `porthole-*` through to the
|
|
6201
|
+
content server too. A host whose naming makes `porthole-` labels must change it. A content Worker
|
|
6202
|
+
of a host's own (Raft's, on 0.13 today) that adopts nested pages serves the shell, the page and
|
|
6203
|
+
its files on `nestedLabelOf(label)` (`nestedAncestors(<that origin>, <host origins>)`, the shell's
|
|
6204
|
+
`origin` that origin), answers the frame location with it, serves nothing else there, and never
|
|
6205
|
+
answers a nested page on the scope's label (ADOPTING "Nested pages").
|
|
6206
|
+
|
|
6207
|
+
**Tested.** `test/nested.test.ts` "a nested page's shell on a label of its own (P114)" (the
|
|
6208
|
+
label, one per scope, under host naming and the keyed default; the scope's label answers no
|
|
6209
|
+
nested page; the shell's answers nothing else, another display's ticket or sealed address
|
|
6210
|
+
included; naming and reserved labels); `test/entry.test.ts` "a nested page's clean address
|
|
6211
|
+
(P114)" (the hop, the page it was entered at, the shell's own session; an attacker's entry code
|
|
6212
|
+
at the shell's document address opens nothing); `leak/served/nested-siblings.spec.ts`
|
|
6213
|
+
`[nested-siblings]`: a nested page beside an inline widget and a plain artifact of its scope, which
|
|
6214
|
+
read each other (the positive control) and nothing of the shell (not its document, no sealed
|
|
6215
|
+
address, not its page's address); `leak/served/nested.spec.ts`'s first case beside a widget of its
|
|
6216
|
+
scope; `leak/kit.spec.ts` (through `nodeHost`) and the prod-shape profile (through Caddy's TLS and
|
|
6217
|
+
CoreDNS): framed by `issue`'s location, and from a clean address. Negative control `shell-label`:
|
|
6218
|
+
the harness answers the shell's frame address and sealed files on the scope's label (from the
|
|
6219
|
+
shell's, every mention of its origin made the scope's), and `[nested-siblings]` fails, nothing
|
|
6220
|
+
else. Measured on the headless shell, full Chromium, WebKit and Firefox (the last two in the
|
|
6221
|
+
prod-shape profile's browser image).
|
|
6222
|
+
|
|
6223
|
+
**Revisit when** a nested page gets storage, assets or libraries (they would be served on the
|
|
6224
|
+
shell's label: the rule must say what may run there), or a host needs a nested page's shell per
|
|
6225
|
+
page.
|
|
6226
|
+
|
|
6227
|
+
## P116 · 2026-10-28 · A mark's count above the limit is clamped, not refused · Accepted
|
|
6228
|
+
|
|
6229
|
+
**Context.** P104 had `checkMarks` throw on a `count` above `ANNOTATION_LIMITS.count` (999), as on
|
|
6230
|
+
a bad anchor, so one mark refused the whole `show`. The count is a host's data that anyone can
|
|
6231
|
+
grow: in Ferry, one comment with 999 replies made `annotations.show` throw, the host got
|
|
6232
|
+
`onHostError({ kind: "annotations" })`, and treated it as fatal (porthole#40).
|
|
6233
|
+
|
|
6234
|
+
**Decision.** A whole number above the limit is clamped to it before the mark goes to the frame.
|
|
6235
|
+
The marker reads "99+" above 99 either way, so nothing a person sees changes, and the page is told
|
|
6236
|
+
no more than 999, as before. Anything that isn't a whole number from 0 (negative, a fraction,
|
|
6237
|
+
NaN, Infinity, not a number) still throws: that is a host's bug, not data that grew.
|
|
6238
|
+
|
|
6239
|
+
**Rejected (for now).** Dropping only a bad mark rather than refusing the list, and running
|
|
6240
|
+
`focus`/`start` after a refused `show` (porthole#40's other suggestions): they change what a host
|
|
6241
|
+
hears about its own bugs; left for their own decision.
|
|
6242
|
+
|
|
6243
|
+
Tested: `test/annotate.test.ts` (counts above the limit clamped, the rest refused as before).
|
|
6244
|
+
|
|
6245
|
+
## P117 · 2026-10-28 · A draft holds back a tag start it was cut in · Accepted
|
|
6246
|
+
|
|
6247
|
+
**Context.** While content streams, the shell draws each partial (`tool-input-partial`) inert as
|
|
6248
|
+
it has come so far. Cut right after `<` or `</`, the HTML tokenizer emits them as text, so the
|
|
6249
|
+
draft shows a stray `<` until the next fragment (porthole#16: Ferry's screenshot, a lone `<` under
|
|
6250
|
+
eight drawn rows, cut just before `<script>`). Agents cut their arguments at arbitrary points.
|
|
6251
|
+
|
|
6252
|
+
**Decision.** Before parsing a draft, the shell leaves out a trailing tag start: from the last
|
|
6253
|
+
`<`, if what follows is empty, `/`, or a letter and no `>` (a tag's name or attributes, which the
|
|
6254
|
+
tokenizer drops anyway). A `<` that starts no tag (`1 < 2`), a comment, and a `<` with a `>` after
|
|
6255
|
+
it are drawn as they are. The whole content (`tool-input`) is never trimmed; nothing runs
|
|
6256
|
+
differently, since a draft runs nothing.
|
|
6257
|
+
|
|
6258
|
+
Tested: `test/shell.test.ts` (`<`, `</`, `</di`, inside an attribute, and whole content
|
|
6259
|
+
unchanged); `leak/react.spec.ts` "content streams through props…" (a draft cut after `</` and
|
|
6260
|
+
after `<` draws neither).
|
package/docs/DESIGN.md
CHANGED
|
@@ -996,6 +996,7 @@ for that to lapse and click with raw input.
|
|
|
996
996
|
| The keyboard: the focus guard (P109) | a move of the keyboard from one of the host page's text fields into a display's frame that the person didn't make (no press on the frame, `:active` on Chromium and WebKit, the pointer coming over it on Firefox; no Tab; no gesture the page's own events don't explain) is undone once the move is over; three while typing within 10 s, or five within 2 s, stop the display | `test/focus-guard.test.ts`; `leak/served/runtime.spec.ts`: "a page that takes the keyboard while the person types in the host's composer…", "a page that takes the keyboard back on its own blur keeps none of it…" (GK-1), "a composer the host focuses with focusField…", "the person's own moves into the frame keep the keyboard…" | `focus-guard` → the first (all three) and the next two (Firefox); `focus-guard-watch` (the watch after a take-back, the look at every frame) → those two (Firefox) |
|
|
997
997
|
| The runtime: `comments.open` from the frame the person is in (P109) | its `user-activation` gate also needs the host page's focus in the calling frame (`CapabilitySpec.inFrame`, `Surface.focused`), after the focus guard | `leak/served/runtime.spec.ts`: "comments.open while the person types in the host's composer reaches no handler…" | `comments-in-frame` → that case (all three) |
|
|
998
998
|
| A nested page: Porthole's shell above an opaque page (P111) | the framed address answers the shell alone (its own script by hash, framing and fetching only the sealed prefix); the page is its child, `sandbox="allow-scripts"` in the attribute and its CSP (never `allow-same-origin`: a static check over every sandbox Porthole writes), loaded without a cookie; the shell passes messages by `event.source`, never in its own namespace; the host takes a move into the frame, or a `comments.open`, for the person's only if the shell's activation turned on within the last second with no trusted press or key on the host's page since (or a Tab, the host's move, a press the engine shows) | `test/nested.test.ts`; `leak/served/nested.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `shell-namespace` → "the shell's words are the shell's alone…" (all three); `shell-host-input` → "a page's focus() just after the person pressed it and went back…" (all three) |
|
|
999
|
+
| A nested page's shell on a label of its own (P114, porthole#56) | the shell, its page and that page's files are served on `nestedLabelOf(<scope's label>)` (`porthole-<24 base32>`, one per scope), never on the scope's label, where the scope's other displays run content with `allow-same-origin`; that label answers only frame addresses of nested pages, their sealed prefix and status pages (no clean address, entry, asset, library, app, nor another instance's ticket, cookie or sealed address), the scope's label no nested page (a clean address goes on with a one-time ticket); no host's naming makes a `porthole-` label; an entry code is no document's ticket | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell) on full Chromium, the headless shell, WebKit and Firefox; `leak/kit.spec.ts` and the prod-shape profile (the label through `nodeHost`, and through a TLS edge and DNS) | `shell-label` (the shell on the scope's label) → `[nested-siblings]` (all three) |
|
|
999
1000
|
| The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
|
|
1000
1001
|
| Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
|
|
1001
1002
|
|
|
@@ -1035,9 +1036,10 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1035
1036
|
|-----------|---------|--------|
|
|
1036
1037
|
| host → frame | `porthole/annotate.start` | `{ elements, text }`: picking elements (the one under the pointer or finger outlined with its name; a click or tap picks it, never reaching the content; Escape cancels; one pick), selecting text (each settled selection), or both (a click picks, a drag selects) |
|
|
1037
1038
|
| host → frame | `porthole/annotate.stop` | — |
|
|
1038
|
-
| host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count?, kind? }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes; a mark with a `count` (0 to 999) also gets a marker (P104); `kind: "draft"` (absent: posted) is drawn apart, with a marker and never a count (P107) |
|
|
1039
|
+
| host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count?, kind? }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes; a mark with a `count` (0 to 999; the host clamps a larger one, P116) also gets a marker (P104); `kind: "draft"` (absent: posted) is drawn apart, with a marker and never a count (P107) |
|
|
1039
1040
|
| host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
|
|
1040
1041
|
| host → frame | `porthole/annotate.clear` | — |
|
|
1042
|
+
| host → frame | `porthole/annotate.clearSelection` | —: the page's text selection is taken away (the DOM's own `removeAllRanges`, taken before content runs) with what the shell held of it, and nothing is reported back; marks, drafts and the mode stay (P115) |
|
|
1041
1043
|
| frame → host | `porthole/annotate.selected` | `{ anchor, rect }`; after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105) |
|
|
1042
1044
|
| frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
|
|
1043
1045
|
| frame → host | `porthole/annotate.cancelled` | — (Escape) |
|
|
@@ -1117,8 +1119,9 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1117
1119
|
see or do anything. A view a report opens or moves guards its presses
|
|
1118
1120
|
(THREAT_MODEL §6).
|
|
1119
1121
|
- **Host API.** `display.annotations.start(mode?)`, `stop()`, `show(marks)`,
|
|
1120
|
-
`focus(id)`, `clear()`,
|
|
1121
|
-
is given to every frame the display runs
|
|
1122
|
+
`focus(id)`, `track(id)`, `clear()`, `clearSelection()` (P115), and the `annotation`
|
|
1123
|
+
event (`AnnotationReport`); the state is given to every frame the display runs (not a
|
|
1124
|
+
`clearSelection`: a new frame has no selection). `parseAnchor` checks an anchor a host
|
|
1122
1125
|
stores (its server, before saving a comment).
|
|
1123
1126
|
|
|
1124
1127
|
Tests (`leak/annotate.spec.ts`, all three engines): a pick outlines and picks
|
|
@@ -1159,7 +1162,10 @@ page reading a draft's kind and never its count (`draft-count`), a raw `show` pa
|
|
|
1159
1162
|
an unknown kind (`draft-shell-checks`), and drafts alone followed after a scroll; and ADOPTING.md's `guardPresses`, as written
|
|
1160
1163
|
there, taking no press within 500 ms of its view opening (a release on a menu item,
|
|
1161
1164
|
a double click's second press on a button or a trigger, a press held past the
|
|
1162
|
-
arming) and the person's own press or key after.
|
|
1165
|
+
arming) and the person's own press or key after. The host's `clearSelection` (P115) takes
|
|
1166
|
+
a selection away from a page that patched `Selection.prototype.removeAllRanges`, tells
|
|
1167
|
+
nothing back, leaves marks and drafts found, and the same words selected again are told
|
|
1168
|
+
(`clear-selection`).
|
|
1163
1169
|
|
|
1164
1170
|
## The shell runtime
|
|
1165
1171
|
|
|
@@ -1471,7 +1477,9 @@ control the tables above name to the registry):
|
|
|
1471
1477
|
| `track-checks` | `annotate.spec.ts` | `a followed mark's box comes as it moves, for that mark only, at most 60 a second, clamped to the frame, until the host stops (P112)` | — | — |
|
|
1472
1478
|
| `order-check` | `annotate.spec.ts` | `every found mark's place in the document comes with its box, offscreen ones too; a place that isn't one is no report (P112)` | — | — |
|
|
1473
1479
|
| `hold-click` | `annotate.spec.ts` | `holding a block 500 ms selects it and its release's click never reaches the page; a tap, a moving finger and a mouse are the page's (P112)` | — | — |
|
|
1480
|
+
| `clear-selection` | `annotate.spec.ts` | `clearSelection takes the page's selection away and tells nothing back; marks and drafts stay, the next selection is told (P115)` | — | — |
|
|
1474
1481
|
| `shell-namespace` | `served/nested.spec.ts` | `the shell's words are the shell's alone: a page that says them, to its parent or to the host's window, moves nothing` | — | — |
|
|
1482
|
+
| `shell-label` | `served/nested-siblings.spec.ts` | `[nested-siblings]` | — | — |
|
|
1475
1483
|
| `file-sandbox` | `served/nested.spec.ts` | `a page's SVG or XML file opened on a tab of its own is an opaque origin, and its script touches nothing of the shell's (P111, after its review)` | — | — |
|
|
1476
1484
|
| `shell-stall` | `served/nested.spec.ts` | `a shell's activation seen after a stall is no one's gesture until it goes off (P111, after its review)` | — | — |
|
|
1477
1485
|
| `shell-host-input` | `served/nested.spec.ts` | `a page's focus() just after the person pressed it and went back to the host's composer is taken back` | — | — |
|
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.14.
|
|
8
|
+
**Status.** This describes Porthole 0.14.1 (2026-10-28). A review on 2026-10-19 found gaps, and every decision it led to
|
|
9
9
|
has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
|
|
10
10
|
and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
11
|
annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
|
|
@@ -19,7 +19,10 @@ on (§7). 0.13.0 also makes P106's lint fail soft and read only what it may (P11
|
|
|
19
19
|
isolation). 0.14.0 adds a nested page (P111, `nested: true`, S3): the framed address is Porthole's
|
|
20
20
|
shell alone and the page its opaque child, so a realm the page can't reach tells the host when the
|
|
21
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).
|
|
22
|
+
additions for a host's comment modes (hints, as every report is, §7). 0.14.1: P114
|
|
23
|
+
(porthole#56) serves a nested page's shell on a label of its own, on which nothing but nested
|
|
24
|
+
pages' shells, their pages, those pages' files and status pages is ever served, so no other
|
|
25
|
+
display of the scope is same-origin with the shell (S3).
|
|
23
26
|
|
|
24
27
|
## 1. Two layers
|
|
25
28
|
|
|
@@ -336,6 +339,16 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
|
|
|
336
339
|
403 that says `denied`.
|
|
337
340
|
- A nested page (`nested: true`, P111): the framed address answers Porthole's shell alone, its
|
|
338
341
|
script the only one its CSP runs, framing and fetching only the origin's sealed files' prefix.
|
|
342
|
+
**The shell's origin hosts nothing but the shell, its opaque page, the sealed files and status
|
|
343
|
+
pages** (P114, porthole#56): the shell, the page and its files are served on a label of the
|
|
344
|
+
scope's own, `porthole-<24 base32>` (`nestedLabelOf`), never on the scope's label, where its
|
|
345
|
+
other displays (inline and live widgets, MCP apps, artifacts that aren't nested) run agent-made
|
|
346
|
+
content with `allow-same-origin`. `/server` holds it: that label answers no clean address,
|
|
347
|
+
entry, asset, library, app or other display, and takes no other instance's ticket, cookie or
|
|
348
|
+
sealed address; the scope's label answers no nested page (its clean address goes on to the
|
|
349
|
+
shell's label with a one-time ticket); no host's naming makes a `porthole-` label. So no
|
|
350
|
+
content, of any scope, can read the shell's realm (its word to the host, the page's sealed
|
|
351
|
+
address) or drive it (`leak/served/nested-siblings.spec.ts`, negative control `shell-label`).
|
|
339
352
|
The page is the shell's child, `sandbox="allow-scripts"` (never `allow-same-origin`, held by a
|
|
340
353
|
static check over every sandbox Porthole writes) and the same sandbox in its own CSP, so it is an
|
|
341
354
|
opaque origin in its frame and on a tab; it is loaded, and loads its files, at its sealed address
|
|
@@ -371,6 +384,10 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
|
|
|
371
384
|
uncached (the default; `authorizeTtlSeconds` in the host kit) or call `content.forget(…)` when
|
|
372
385
|
revoking, or a cached answer holds for up to that long.
|
|
373
386
|
- Send the page's `frame-src`.
|
|
387
|
+
- With nested pages, route the shell's label (`porthole-<…>.<domain>`) to the content server as
|
|
388
|
+
every content label is (a wildcard needs nothing; a pattern of the host's own, `a-*`, must add
|
|
389
|
+
it). A content Worker of the host's own serves nested pages on that label alone, and nothing
|
|
390
|
+
else there (P114).
|
|
374
391
|
|
|
375
392
|
**Not guaranteed**
|
|
376
393
|
|
|
@@ -671,6 +688,15 @@ own frame, below the shell, P111), so:
|
|
|
671
688
|
`Element.prototype.matches` on them), so content can reach the closed shadow root that way,
|
|
672
689
|
read the markers and rewrite them (the review of P104, on all three engines). Nothing in the
|
|
673
690
|
layer is secret: it holds only what `show` sent, which the content can read anyway.
|
|
691
|
+
- *Clearing the selection* (P115). `annotations.clearSelection()` is the host's word to the frame
|
|
692
|
+
(`porthole/annotate.clearSelection`), with nothing back: the shell takes the page's selection
|
|
693
|
+
away through `Selection.prototype.removeAllRanges` as it was before content ran (control
|
|
694
|
+
`clear-selection`: a page that replaced it keeps its selection otherwise) and forgets the one it
|
|
695
|
+
told, so the clear makes no `unselected` or `selected`. It goes host to frame only: the host
|
|
696
|
+
takes no such message from a frame, and the shell takes it only from its frame's parent (a page
|
|
697
|
+
that posts it to its own window is dropped). It gives the page nothing new: a page can clear or
|
|
698
|
+
select its own text at any time, and can select the words again right after a clear (the host
|
|
699
|
+
hears that as any selection, while it asked for text).
|
|
674
700
|
- *What content can always do.* Hide, shrink, move or cover the layer (its scripts can rewrite the
|
|
675
701
|
layer's style, lay elements over it, or transform the page it sits in), change its words so a
|
|
676
702
|
mark is orphaned, or flood the shared rate so real reports are refused. It can also make the
|
|
@@ -866,7 +892,8 @@ section.
|
|
|
866
892
|
The decisions below come from the 2026-10-19 review, and all of them have merged. Each row says
|
|
867
893
|
what was wrong, what holds now, and the limit its decision accepts, if any. Later reviews' decisions
|
|
868
894
|
are in the status line and in DECISIONS.md: P105 (after the review of P104), P109 (after the review
|
|
869
|
-
of 0.12.0's drafts), P111 (a nested page, S3; in 0.14.0)
|
|
895
|
+
of 0.12.0's drafts), P111 (a nested page, S3; in 0.14.0), P114 (a nested page's shell on a label of
|
|
896
|
+
its own, after porthole#56; in 0.14.1).
|
|
870
897
|
|
|
871
898
|
| Decision | State | What it closes | Sections |
|
|
872
899
|
| --- | --- | --- | --- |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.1",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -22,6 +22,7 @@
|
|
|
22
22
|
"docs",
|
|
23
23
|
"examples",
|
|
24
24
|
"README.md",
|
|
25
|
+
"CHANGELOG.md",
|
|
25
26
|
"THIRD_PARTY_NOTICES.md"
|
|
26
27
|
],
|
|
27
28
|
"type": "module",
|
|
@@ -65,10 +66,10 @@
|
|
|
65
66
|
}
|
|
66
67
|
},
|
|
67
68
|
"devDependencies": {
|
|
68
|
-
"@modelcontextprotocol/ext-apps": "2.0.
|
|
69
|
-
"@modelcontextprotocol/server-basic-react": "2.0.
|
|
70
|
-
"@modelcontextprotocol/server-basic-vanillajs": "2.0.
|
|
71
|
-
"@modelcontextprotocol/server-threejs": "2.0.
|
|
69
|
+
"@modelcontextprotocol/ext-apps": "2.0.4",
|
|
70
|
+
"@modelcontextprotocol/server-basic-react": "2.0.4",
|
|
71
|
+
"@modelcontextprotocol/server-basic-vanillajs": "2.0.4",
|
|
72
|
+
"@modelcontextprotocol/server-threejs": "2.0.4",
|
|
72
73
|
"@playwright/test": "1.63.0",
|
|
73
74
|
"@types/node": "26.6.3",
|
|
74
75
|
"@types/react": "19.3.0",
|
package/src/annotate/types.ts
CHANGED
|
@@ -84,7 +84,8 @@ export interface AnnotationMark {
|
|
|
84
84
|
readonly anchor: AnnotationAnchor;
|
|
85
85
|
/**
|
|
86
86
|
* A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
|
|
87
|
-
* `ANNOTATION_LIMITS.count
|
|
87
|
+
* `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0 draws
|
|
88
|
+
* the bubble alone) at the end of a
|
|
88
89
|
* text anchor and the top right of an element. The person can click it: the frame reports
|
|
89
90
|
* `activated`. The content can read the number; give one only where the page may know it. A
|
|
90
91
|
* draft's is dropped (P107): its marker has no number.
|
|
@@ -180,6 +181,8 @@ export const ANNOTATE_METHODS = {
|
|
|
180
181
|
track: "porthole/annotate.track",
|
|
181
182
|
/** Frame → host: the followed mark's box, as it moves (P112). */
|
|
182
183
|
tracked: "porthole/annotate.tracked",
|
|
184
|
+
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
185
|
+
clearSelection: "porthole/annotate.clearSelection",
|
|
183
186
|
} as const;
|
|
184
187
|
|
|
185
188
|
/** The most of each part of an anchor or report the host takes. */
|
package/src/annotate/validate.ts
CHANGED
|
@@ -227,7 +227,8 @@ export const hasMarker = (mark: AnnotationMark): boolean =>
|
|
|
227
227
|
mark.count !== undefined || mark.kind === "draft";
|
|
228
228
|
|
|
229
229
|
/**
|
|
230
|
-
* The host's marks, checked before they go to the frame; throws on the first bad one
|
|
230
|
+
* The host's marks, checked before they go to the frame; throws on the first bad one (a count above
|
|
231
|
+
* `ANNOTATION_LIMITS.count` isn't bad: it is clamped to it, P116). Each is
|
|
231
232
|
* rebuilt as the frame gets it: a posted mark as 0.10.0 sent it (no `kind`), a draft with
|
|
232
233
|
* `kind: "draft"` and without its count (P107: a draft's marker shows no number, so the page isn't
|
|
233
234
|
* told one).
|
|
@@ -244,10 +245,10 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
|
244
245
|
`annotations.show: mark ${index} needs a unique id (1 to ${LIMITS.id} characters) and a valid anchor`,
|
|
245
246
|
);
|
|
246
247
|
}
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
);
|
|
248
|
+
// A count above the limit is clamped to it (P116): the marker reads "99+" either way, and a
|
|
249
|
+
// count is data anyone can grow (a thread's replies), so it mustn't reject the whole list.
|
|
250
|
+
if (mark.count !== undefined && !count(mark.count, Infinity)) {
|
|
251
|
+
throw new TypeError(`annotations.show: mark ${index}'s count is a whole number, 0 or more`);
|
|
251
252
|
}
|
|
252
253
|
const kind: unknown = mark.kind;
|
|
253
254
|
if (kind !== undefined && kind !== "posted" && kind !== "draft") {
|
|
@@ -257,6 +258,10 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
|
257
258
|
if (kind === "draft") {
|
|
258
259
|
return { id: mark.id, anchor, kind };
|
|
259
260
|
}
|
|
260
|
-
return {
|
|
261
|
+
return {
|
|
262
|
+
id: mark.id,
|
|
263
|
+
anchor,
|
|
264
|
+
...(mark.count === undefined ? {} : { count: Math.min(mark.count, LIMITS.count) }),
|
|
265
|
+
};
|
|
261
266
|
});
|
|
262
267
|
}
|
package/src/compile/policy.ts
CHANGED
|
@@ -217,8 +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
|
|
221
|
-
// the shell's child (`PAGE_SANDBOX_TOKENS`).
|
|
220
|
+
// Nested (P111), this frame holds Porthole's shell, on a label of its own where no content
|
|
221
|
+
// runs with this origin (P114), and the page is the shell's child (`PAGE_SANDBOX_TOKENS`).
|
|
222
222
|
return ["allow-scripts", "allow-same-origin"];
|
|
223
223
|
case "external":
|
|
224
224
|
// The host may add a documented few (popups, modals, downloads), never top navigation.
|
package/src/host/create-host.ts
CHANGED
|
@@ -425,6 +425,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
425
425
|
tracking = null;
|
|
426
426
|
toFrame(ANNOTATE_METHODS.clear, {});
|
|
427
427
|
},
|
|
428
|
+
clearSelection() {
|
|
429
|
+
// Host → frame only, and kept for no later frame (P115).
|
|
430
|
+
needsAnnotate("clearSelection");
|
|
431
|
+
toFrame(ANNOTATE_METHODS.clearSelection, {});
|
|
432
|
+
},
|
|
428
433
|
};
|
|
429
434
|
|
|
430
435
|
const hostContext = (): HostContext => {
|
package/src/host/types.ts
CHANGED
|
@@ -245,6 +245,13 @@ export interface AnnotationControls {
|
|
|
245
245
|
track(id: string | null): void;
|
|
246
246
|
/** Removes every mark. */
|
|
247
247
|
clear(): void;
|
|
248
|
+
/**
|
|
249
|
+
* Takes the page's text selection away (P115), its highlight with it: for when the host has
|
|
250
|
+
* used it (a comment posted, a draft added). No `unselected` follows; marks (posted and drafts),
|
|
251
|
+
* the mode and a followed mark stay as they are. Nothing selected: nothing happens. Not kept for
|
|
252
|
+
* a frame that runs later (it has no selection to clear).
|
|
253
|
+
*/
|
|
254
|
+
clearSelection(): void;
|
|
248
255
|
}
|
|
249
256
|
|
|
250
257
|
export interface DisplayControls {
|
package/src/react/frame.tsx
CHANGED
|
@@ -500,10 +500,11 @@ export interface PortholeFrameProps {
|
|
|
500
500
|
readonly instance?: InstanceRef;
|
|
501
501
|
/**
|
|
502
502
|
* What the page declared (P086), as the host stored it with the artifact: the capabilities it
|
|
503
|
-
* reaches through `porthole.use`, and its pinned runtime.
|
|
504
|
-
*
|
|
503
|
+
* reaches through `porthole.use`, and its pinned runtime. Under `config.runtime`, `null` says
|
|
504
|
+
* the page was published before 0.7 and has 0.6's surface (`MountOptions.declaration`). By
|
|
505
|
+
* value: a change makes the display again.
|
|
505
506
|
*/
|
|
506
|
-
readonly declaration?: PageDeclaration;
|
|
507
|
+
readonly declaration?: PageDeclaration | null;
|
|
507
508
|
/**
|
|
508
509
|
* Who is viewing (P087), for an opaque frame or one whose issue gave none. By value: a change
|
|
509
510
|
* makes the display again.
|