@botiverse/porthole 0.15.2 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +89 -0
- package/dist/bridge/bridge.d.ts +1 -8
- package/dist/bridge/bridge.js +0 -7
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +1 -1
- package/dist/compile/policy.d.ts +0 -7
- package/dist/compile/policy.js +1 -10
- package/dist/config/capabilities.d.ts +8 -14
- package/dist/config/capabilities.js +4 -5
- package/dist/config/schema.d.ts +2 -13
- package/dist/config/validate.js +0 -24
- package/dist/conformance/behavior.js +26 -37
- package/dist/conformance/clipboard.js +47 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +1 -3
- package/dist/guide/limits.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.d.ts +1 -1
- package/dist/host/create-host.js +6 -51
- package/dist/host/door.d.ts +1 -1
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- package/dist/host/outcome.d.ts +5 -12
- package/dist/host/outcome.js +8 -16
- package/dist/host/types.d.ts +6 -22
- package/dist/index.d.ts +2 -4
- package/dist/index.js +2 -4
- package/dist/isolation/served.d.ts +9 -14
- package/dist/isolation/served.js +17 -31
- package/dist/isolation/types.d.ts +2 -19
- package/dist/isolation/types.js +0 -17
- package/dist/platform/focus-field.d.ts +11 -0
- package/dist/platform/focus-field.js +18 -0
- package/dist/platform/types.d.ts +6 -22
- package/dist/platform/web.js +8 -98
- package/dist/presets/presets.d.ts +0 -2
- package/dist/presets/presets.js +0 -1
- package/dist/react/frame.d.ts +0 -8
- package/dist/react/frame.js +0 -4
- package/dist/runtime/contract.d.ts +2 -2
- package/dist/runtime/contract.js +2 -2
- package/dist/runtime/types.generated.js +6 -6
- package/dist/server/files.js +7 -23
- package/dist/server/host.d.ts +1 -1
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +4 -6
- package/dist/server/naming.js +1 -1
- package/dist/server/pages.d.ts +9 -2
- package/dist/server/pages.js +28 -8
- package/dist/server/server.js +28 -166
- package/dist/server/types.d.ts +7 -7
- package/dist/shell/plan.js +2 -2
- package/dist/shell/runtime.js +1 -9
- package/docs/ADOPTING.md +42 -135
- package/docs/ARCHITECTURE.md +0 -33
- package/docs/DECISIONS.md +296 -9
- package/docs/DESIGN.md +27 -50
- package/docs/THREAT_MODEL.md +140 -242
- package/package.json +1 -1
- package/src/bridge/bridge.ts +1 -17
- package/src/check/page.ts +1 -1
- package/src/compile/policy.ts +1 -11
- package/src/config/capabilities.ts +8 -14
- package/src/config/schema.ts +2 -13
- package/src/config/validate.ts +0 -28
- package/src/conformance/behavior.ts +50 -52
- package/src/conformance/clipboard.ts +56 -1
- package/src/displays/displays.ts +1 -3
- package/src/guide/limits.ts +1 -1
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +6 -52
- package/src/host/door.ts +1 -1
- package/src/host/locate.ts +2 -2
- package/src/host/outcome.ts +8 -21
- package/src/host/types.ts +6 -20
- package/src/index.ts +2 -4
- package/src/isolation/served.ts +18 -37
- package/src/isolation/types.ts +2 -24
- package/src/platform/focus-field.ts +18 -0
- package/src/platform/types.ts +6 -21
- package/src/platform/web.ts +8 -116
- package/src/presets/presets.ts +0 -3
- package/src/react/frame.tsx +0 -10
- package/src/runtime/contract.ts +4 -4
- package/src/runtime/types.generated.ts +6 -6
- package/src/server/files.ts +4 -19
- package/src/server/host.ts +1 -1
- package/src/server/index.ts +4 -16
- package/src/server/naming.ts +1 -1
- package/src/server/pages.ts +38 -12
- package/src/server/server.ts +29 -189
- package/src/server/types.ts +7 -7
- package/src/shell/plan.ts +2 -2
- package/src/shell/runtime.ts +1 -9
- package/types/runtime/v1/artifact.d.ts +2 -3
- package/types/runtime/v1/assets.d.ts +1 -1
- package/types/runtime/v1/chat.d.ts +2 -2
- package/types/runtime/v1/comments.d.ts +1 -1
- package/types/runtime/v1/downloads.d.ts +2 -2
- package/types/runtime/v1/links.d.ts +2 -2
- package/dist/platform/focus-guard.d.ts +0 -252
- package/dist/platform/focus-guard.js +0 -764
- package/dist/server/nested.d.ts +0 -66
- package/dist/server/nested.js +0 -120
- package/dist/shell/frame.d.ts +0 -28
- package/dist/shell/frame.js +0 -338
- package/src/platform/focus-guard.ts +0 -999
- package/src/server/nested.ts +0 -156
- package/src/shell/frame.ts +0 -371
package/docs/ADOPTING.md
CHANGED
|
@@ -319,8 +319,8 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
319
319
|
`"draft"` throws, as a bad anchor does (React: `onHostError`, kind `"annotations"`). The shell
|
|
320
320
|
is your content server's: upgrade its Porthole first, or an older shell draws a draft as a
|
|
321
321
|
posted mark without a marker. The view a draft's `activated` opens is guarded like any (below)
|
|
322
|
-
and puts no "Post", "Submit review" or "Discard" one click away: a page can
|
|
323
|
-
|
|
322
|
+
and puts no "Post", "Submit review" or "Discard" one click away: a page can say that click
|
|
323
|
+
itself, at a moment it picks (P107; no gesture is asked of it since 0.16.0, P149).
|
|
324
324
|
- **No drafts to a page that can pass them on**, or accept that it does: a page with the runtime's
|
|
325
325
|
`db` writes and `user` can store who is drafting where (`user.get()` and the marks it is shown)
|
|
326
326
|
for its author and other viewers to read before the draft is posted, and tie the posted comment
|
|
@@ -489,7 +489,7 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
489
489
|
stops, in reading order, named for what it is (`3 comments on "the words"`, from the `count` and
|
|
490
490
|
the anchor's words, without an element's tag, P134; in English, whatever your UI's language). The
|
|
491
491
|
`label` you store keeps its tag. Enter or Space on it is `activated`,
|
|
492
|
-
through the same path
|
|
492
|
+
through the same path as a click: nothing to handle apart. It is the
|
|
493
493
|
page's focus order, which a page can steal from or hide a marker from, and it is one more
|
|
494
494
|
`activated` the content can time: keep your own list of marks as the way a keyboard can rely on,
|
|
495
495
|
with `annotations.focus(id)` to bring one into view, and leave your view's guard as it is (it
|
|
@@ -513,9 +513,7 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
513
513
|
`display.annotations.focusMark(id)` (React: `focusMark(id)` on the `ref`) to put the keyboard back
|
|
514
514
|
on the marker. It carries no content and reports nothing; an id with no marker, or a marker the
|
|
515
515
|
page has moved away, does nothing and throws nothing; the page can take the focus straight back.
|
|
516
|
-
|
|
517
|
-
the move for the page's, undoes it and counts it (`focusTaken`). Keep your own list of marks as
|
|
518
|
-
the way that holds.
|
|
516
|
+
Keep your own list of marks as the way that holds.
|
|
519
517
|
On a calm page that lands at once, from your `<body>`. While the frame is finding its marks (a
|
|
520
518
|
`show` just sent, which many hosts send as a card closes, or content that just changed) the word
|
|
521
519
|
waits, up to a second, and is then dropped unless the focus is in the frame by then. A word the
|
|
@@ -541,17 +539,8 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
541
539
|
|
|
542
540
|
Keep the check: on a button of yours, the person has moved on, and `display.focus()` would take the
|
|
543
541
|
keyboard from them. With React, whose `ref` has no `focus()`, call the frame's own `focus()` for
|
|
544
|
-
that step
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
**Nested pages (P136).** `display.focus()` reaches a nested page on every engine, whether or not
|
|
548
|
-
it had the focus. Two ways don't:
|
|
549
|
-
- The frame's own `focus()`, which the React step above is: it stops at the page's shell (Chromium
|
|
550
|
-
and WebKit from anywhere, Firefox from a focused element of yours), so a `focusMark` that waits
|
|
551
|
-
is dropped even after it, and nothing tells you. On a calm page the second call doesn't wait and
|
|
552
|
-
lands. On a page that is changing, keep your own list of marks as the way back.
|
|
553
|
-
- `display.focus()` inside a key's own handler, on Firefox (measured on a nested page): it moves
|
|
554
|
-
nothing. Call it from a task, as the timer above does.
|
|
542
|
+
that step. An id with no marker then leaves the focus in the frame, with the keys going to the
|
|
543
|
+
page.
|
|
555
544
|
|
|
556
545
|
Without the second call, nothing changes on a calm page. On a busy one, a word that the frame
|
|
557
546
|
finishes with before your own move is lost where it used to land, so the person gets the frame and
|
|
@@ -645,51 +634,33 @@ display.on("navigated", () => bar.reset());
|
|
|
645
634
|
const result = await frame.current?.find(query, { direction: "next" });
|
|
646
635
|
```
|
|
647
636
|
|
|
648
|
-
### The keyboard:
|
|
637
|
+
### The keyboard: a display can take it
|
|
649
638
|
|
|
650
639
|
Any display can move the keyboard into its frame (`element.focus()` in the page, with no gesture
|
|
651
640
|
on Chromium and WebKit), and what the person goes on typing in your composer or chat box then goes
|
|
652
|
-
to the page
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
641
|
+
to the page, until they see it and click back. Porthole doesn't stop that. From 0.13 to 0.15 a
|
|
642
|
+
guard took such a move back when it judged the move to be the page's; it could only guess whose
|
|
643
|
+
move it was (your page sees no press inside a cross-site frame), and a wrong guess refused a
|
|
644
|
+
person's own click. 0.16.0 removed it ([P149](DECISIONS.md)): no `focusTaken` event, no
|
|
645
|
+
`onFocusTaken`, and a display is never stopped for taking the keyboard.
|
|
656
646
|
|
|
657
647
|
```js
|
|
658
|
-
|
|
659
|
-
display.
|
|
660
|
-
// Moving
|
|
661
|
-
|
|
662
|
-
//
|
|
663
|
-
// only save a draft (Enter adds it to the batch; submitting is only your own "Submit N"), and that
|
|
664
|
-
// shows plainly it is a draft (THREAT_MODEL §6, P112); any other view a report opens takes no focus (P134's
|
|
665
|
-
// exception, §6, is a container only, and its own conditions). Then
|
|
666
|
-
// Porthole's move, not textarea.focus().
|
|
648
|
+
// Moving focus into a display yourself (a "focus the page" shortcut):
|
|
649
|
+
display.focus();
|
|
650
|
+
// Moving it to a field of yours (opening your composer focused): Porthole's move, which lands on
|
|
651
|
+
// every engine. Firefox ignores a plain focus() while a frame that takes focus back on its blur
|
|
652
|
+
// holds it.
|
|
667
653
|
import { focusField } from "@botiverse/porthole";
|
|
668
|
-
focusField(composer.textarea);
|
|
654
|
+
focusField(composer.textarea);
|
|
669
655
|
```
|
|
670
656
|
|
|
671
|
-
- **
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
`onFocusTaken` and `focus` on its surface, or a display can read what is typed beside it; know
|
|
679
|
-
the limits (THREAT_MODEL §7 "The keyboard": on Firefox, which shows your page no press
|
|
680
|
-
in a frame, a page keeps the keyboard if the pointer came over its frame after the person last
|
|
681
|
-
typed and after the field got focus; moves between two frames aren't judged).
|
|
682
|
-
- **Served pages in full Chromium:** nest them ("Nested pages" below, P111). A served page's
|
|
683
|
-
frame there is out of process: your page sees no press in it, so a person's click into the
|
|
684
|
-
page's field is taken back. A nested page's shell sees it: a move into the frame is the
|
|
685
|
-
person's if the shell's activation turned on within the last second and you saw no press or key
|
|
686
|
-
of your own since. A second press in the page within 5 s of the last turns nothing on: after the
|
|
687
|
-
person went back to your composer, their next move in is taken back until then, or a Tab. A
|
|
688
|
-
nested page that takes the keyboard back as the guard returns it is fought as any page is, and
|
|
689
|
-
stopped (P120). A move into the page within 250 ms of the person's key on your page is taken
|
|
690
|
-
back on every engine (no hand presses that fast after typing, P122); on full Chromium a key the
|
|
691
|
-
person types into the page just as it takes the keyboard, slower than that, can still pass for a
|
|
692
|
-
press (THREAT_MODEL §7).
|
|
657
|
+
- **Yours:** where a field must never lose a key to a page (a password, a payment field), don't
|
|
658
|
+
show a display you don't trust beside it. A view a display's report opens still takes no focus
|
|
659
|
+
and no press for its first 500 ms (THREAT_MODEL §6); that is your view's own guard, and it
|
|
660
|
+
doesn't depend on this.
|
|
661
|
+
- **A platform of your own** (a native web view): `focus` on its surface is what `display.focus()`
|
|
662
|
+
calls; `focused`, if you give it, says whether the keyboard is in the display, which the find
|
|
663
|
+
shortcut reads (P131). `onFocusTaken` is no longer read.
|
|
693
664
|
|
|
694
665
|
## 4. Served pages: the host kit
|
|
695
666
|
|
|
@@ -752,16 +723,15 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
|
|
|
752
723
|
or tells it, it isn't in `data-porthole-hosts`, and redirect entry and the handoff stay
|
|
753
724
|
`appOrigins`' alone. Exact https origins (`http://` on loopback), none an app origin. Your own
|
|
754
725
|
page between them is still the frame's parent, and its `frame-ancestors` is yours to set. A
|
|
755
|
-
content Worker of your own passes the same list to `statusPage`, `doorResponse
|
|
756
|
-
`doorStatusResponse`
|
|
757
|
-
rows below (`<framedBy>`). The outer page is then an ancestor of content: a content page can
|
|
726
|
+
content Worker of your own passes the same list to `statusPage`, `doorResponse` and
|
|
727
|
+
`doorStatusResponse` (`framedBy`). The outer page is then an ancestor of content: a content page can
|
|
758
728
|
`postMessage` it and every frame in its tree, and learn its origin, so the outer page's authors
|
|
759
729
|
must check `event.source` and `event.origin` in every message listener
|
|
760
730
|
([THREAT_MODEL.md §6 "What every host must do"](THREAT_MODEL.md#what-every-host-must-do)).
|
|
761
731
|
- **`embeds`** (P143): to let any site embed a public artifact page, set `embeds: true` and, from
|
|
762
732
|
one route of your own that decides the page is public (never your reader's issue endpoint),
|
|
763
|
-
issue it with `{ anonymous: true, embed: true }` (no `level`, no `user`; an artifact's page
|
|
764
|
-
|
|
733
|
+
issue it with `{ anonymous: true, embed: true }` (no `level`, no `user`; an artifact's page):
|
|
734
|
+
`host.server.issue(instance, { anonymous: true, embed: true })`. Never answer
|
|
765
735
|
`embed` from `access`: it answers your readers, and the kit refuses it there (409 from the issue
|
|
766
736
|
endpoint and a clean address's resolve, its 409 page at a clean address's tab; P145). That
|
|
767
737
|
session's answers say `frame-ancestors *`, and nothing else's do. It has no
|
|
@@ -890,70 +860,8 @@ artifact: { preset: "artifact", options: { layout: { kind: "fill" }, nestedFrame
|
|
|
890
860
|
|
|
891
861
|
It is a weakening: a nested frame is a realm of its own where the shell's defenses never ran, so
|
|
892
862
|
content there has WebRTC (a way out past `connect-src`) and can put text on the clipboard from a
|
|
893
|
-
click, with no notice. The CSP still governs every frame's loads and navigations. Not for url mode
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
### Nested pages: the page below Porthole's shell
|
|
897
|
-
|
|
898
|
-
`nested: true` (P111) on an artifact kind served by the host kit puts the page in a frame of its
|
|
899
|
-
own below Porthole's shell, with an opaque origin of its own. The shell, the page and its files are
|
|
900
|
-
served on a label of the scope's own, `porthole-<24 base32>.<content domain>` (P114), not on the
|
|
901
|
-
scope's label: the scope's other displays run content there with `allow-same-origin`, which would
|
|
902
|
-
reach the shell (porthole#56). Do it where people
|
|
903
|
-
type beside your displays: in full Chromium (a person's browser, not Playwright's headless shell) a
|
|
904
|
-
served page's frame is out of process, and your page can't see a press in it, so without nesting a
|
|
905
|
-
real click into the page's field is taken back and `comments.open` from a real click is refused
|
|
906
|
-
within 5 s of any input on your page (porthole#53). The page's shell sees it, and tells your page.
|
|
907
|
-
|
|
908
|
-
```ts
|
|
909
|
-
const displays = defineDisplays({
|
|
910
|
-
page: {
|
|
911
|
-
preset: "artifact",
|
|
912
|
-
// No `served.storage`: a nested page keeps no storage of its own (localStorage lasts the load).
|
|
913
|
-
options: { runtime: "1", capabilities: { annotate: {}, comments: {} }, nested: true },
|
|
914
|
-
},
|
|
915
|
-
});
|
|
916
|
-
```
|
|
917
|
-
|
|
918
|
-
Nothing else changes on your page: the same `createHost` (or `PortholeFrame`), the same handlers
|
|
919
|
-
and events, the same `frame-src` (the content domain's wildcard covers the shell's label). Your
|
|
920
|
-
frames route answers the shell's origin (`issue`'s location); a clean address stays on the scope's
|
|
921
|
-
label and sends the browser on to the shell's with a one-time ticket.
|
|
922
|
-
|
|
923
|
-
**Route the shell's label.** `porthole-<…>.<content domain>` must reach the content server as
|
|
924
|
-
your other labels do. Wildcard DNS and a wildcard certificate (`*.<content domain>`) already cover
|
|
925
|
-
it; a route, an edge rule or a firewall that matches labels by a pattern of yours (`a-*`) must let
|
|
926
|
-
`porthole-*` through too. Every `porthole-` label is Porthole's: your naming may not make one
|
|
927
|
-
(`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
|
|
928
|
-
run: whether the page touched `localStorage` or `sessionStorage`, never what it kept), for you to
|
|
929
|
-
count the pages that would need storage. A nested page's workers come from Blob URLs (a worker from
|
|
930
|
-
a script of its own set is refused: its origin is opaque), which may `importScripts` the set's
|
|
931
|
-
scripts; Chromium refuses a Blob module worker there. Not yet with a nested page: the asset library (`assets`)
|
|
932
|
-
and Porthole's libraries (`egress.libraries`); the config refuses them.
|
|
933
|
-
|
|
934
|
-
What a content origin serves for a nested page (`/server` does all of it; a content Worker of your
|
|
935
|
-
own answers the same, with the helpers `/server` exports: `nestedLabelOf`, `nestedShellResponse`,
|
|
936
|
-
`nestedFileCsp`, `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the shell's own,
|
|
937
|
-
`https://<nestedLabelOf(label)>.<content domain>`, where `label` is the scope's label (the one its
|
|
938
|
-
other displays are served on); `<token>` is the access in the path (Porthole's sealed session, or a
|
|
939
|
-
signed token of your own: the shell only needs addresses under the prefix). Your frame location
|
|
940
|
-
for a nested page is on `<origin>`.
|
|
941
|
-
|
|
942
|
-
**The rule** (P114): `<origin>` answers the four rows below and Porthole's status pages, nothing
|
|
943
|
-
else (no other display, no clean address, no asset, no app), and the scope's label never answers a
|
|
944
|
-
nested page's shell, page or files. That is what keeps the shell's realm (its word to your page,
|
|
945
|
-
the page's sealed address) out of every other display's reach. Porthole holds the shell to that
|
|
946
|
-
label (P121): `createHost` refuses a nested page located anywhere else (a host error, `locate`, and
|
|
947
|
-
no frame), `nestedShellResponse` throws for another origin, and the shell runs nowhere else. That
|
|
948
|
-
`<origin>` answers nothing but these is yours to hold: Porthole can't see your Worker's routes.
|
|
949
|
-
|
|
950
|
-
| Request | Answer |
|
|
951
|
-
| --- | --- |
|
|
952
|
-
| `<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, framedBy, 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> <framedBy>`; `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. |
|
|
953
|
-
| `<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`: `nestedFileCsp("page", fileSetCspDirectives(compiled.cspDirectives, "<origin>/__porthole/f/"))` then `; frame-ancestors ` and `nestedAncestors("<origin>", "<host origins> <framedBy>")`: the page's directives, its files' prefix opened, and `sandbox allow-scripts` (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`). |
|
|
954
|
-
| `<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` (`nestedFileCsp(fileTypeOf(path).role, directives)`, then the `frame-ancestors` above, `<origin> <host origins> <framedBy>`): 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. |
|
|
955
|
-
| `<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. |
|
|
956
|
-
| A token that ended, under the prefix | Porthole's status page (`401`, reason `session`), `frame-ancestors <origin> <host origins> <framedBy>`: it tells the shell, which tells your page (`outcome` blocked). |
|
|
863
|
+
click, with no notice. The CSP still governs every frame's loads and navigations. Not for url mode
|
|
864
|
+
or live widgets (refused). Turn it on only where your product accepts that.
|
|
957
865
|
|
|
958
866
|
### The capability runtime: pages that are apps
|
|
959
867
|
|
|
@@ -1001,10 +909,11 @@ if (shown && !shown.ok) return <VersionError problems={shown.problems} />; //
|
|
|
1001
909
|
<PortholeView display="page" instance={instance} declaration={shown ? shown.declaration : null} />
|
|
1002
910
|
```
|
|
1003
911
|
|
|
1004
|
-
- **A page's draft in your composer** (P108
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
912
|
+
- **A page's draft in your composer** (P108): `comments.open` reaches your handler whenever the
|
|
913
|
+
page calls it, within its rate (30 a minute by default). No proof of a click is asked since
|
|
914
|
+
0.16.0 ([P149](DECISIONS.md)): the page picks the moment, and may call with no one pressing
|
|
915
|
+
anything. So the composer it fills is the person's to act on, and whether it opens at all is
|
|
916
|
+
yours to say (return false while the person is writing, or after they closed several unused):
|
|
1008
917
|
|
|
1009
918
|
```js
|
|
1010
919
|
// A composer the page filled: its words are the page's until the person acts in it.
|
|
@@ -1129,7 +1038,7 @@ hears those as a `hostError` of kind `"frame-status"` (log it, show nothing for
|
|
|
1129
1038
|
fallback from `outcome` only. A url-mode app is the exception: it can say any outcome (THREAT_MODEL
|
|
1130
1039
|
S6).
|
|
1131
1040
|
|
|
1132
|
-
**The door (P125).** A served display
|
|
1041
|
+
**The door (P125).** A served display (a served shell, a page, a view through the
|
|
1133
1042
|
sandbox proxy) is framed on its scope's origin, where the scope's other displays run content: its
|
|
1134
1043
|
own frame can't be trusted for how loading went (a same-scope sibling could speak for it). So
|
|
1135
1044
|
`createHost` first frames a **door** — a page of Porthole's on the display's origin, in a hidden
|
|
@@ -1139,14 +1048,14 @@ for those kinds). The content frame's own frame status is then never taken, and
|
|
|
1139
1048
|
requirements:
|
|
1140
1049
|
|
|
1141
1050
|
- **Deploy the server (or your content Worker) before the host.** The door is minted and served by
|
|
1142
|
-
the server; a host given a served
|
|
1051
|
+
the server; a host given a served location with no door (from a server that doesn't
|
|
1143
1052
|
yet mint one) builds no frame for it: `blocked: locate`, and a `hostError` of kind `"door"`
|
|
1144
1053
|
naming the fix. Upgrade the server/Worker first, then the host. This is a hard requirement, not a
|
|
1145
1054
|
preference.
|
|
1146
1055
|
- **A custom locator must pass `door` through, and issue anew for every run.** If you rebuild
|
|
1147
1056
|
`FrameLocation` yourself (a locator of your own rather than `httpLocator`), carry `door` from your
|
|
1148
1057
|
issue endpoint unchanged; `httpLocator` and the host kit's client already do. Dropping it refuses
|
|
1149
|
-
every served
|
|
1058
|
+
every served display, as above. And `locate` is called again on every run (a reload,
|
|
1150
1059
|
a restart after the content navigated its frame away): answer each call with a fresh issue (a new
|
|
1151
1060
|
ticket, a new door ticket). A location reused from an earlier run carries tickets already taken,
|
|
1152
1061
|
so its door says `blocked: session` ("this link has been used"), and `createHost` tells you
|
|
@@ -1154,8 +1063,7 @@ requirements:
|
|
|
1154
1063
|
display.)
|
|
1155
1064
|
- **A platform of your own makes the web's doors.** A `PlatformHost` that wraps
|
|
1156
1065
|
`webPlatform.createSurface` must also give `createDoor` (delegate to `webPlatform.createDoor`):
|
|
1157
|
-
a platform without doors frames no served display
|
|
1158
|
-
host error).
|
|
1066
|
+
a platform without doors frames no served display (`blocked: locate`, a `door` host error).
|
|
1159
1067
|
- **The door sits in the display's container while it decides**, a hidden 0×0 frame
|
|
1160
1068
|
(`data-porthole-door`), removed once it says its word. Code that grabs
|
|
1161
1069
|
`container.querySelector("iframe")` just after mounting may get the door: select
|
|
@@ -1177,8 +1085,7 @@ Worker routes `DOOR_PATH + <key>` (`/__porthole/door/<key>`) on every label —
|
|
|
1177
1085
|
(`TicketRecord.door === true`, bound to the label and key), run the same access, document and entry
|
|
1178
1086
|
checks the content route runs for that grant, then answer `doorResponse({ hostOrigins, framedBy })` (open) or
|
|
1179
1087
|
`doorStatusResponse({ status, reason, code?, hostOrigins, framedBy })` (401 `session` / 403 `denied` / 404
|
|
1180
|
-
`not-found` / 500 `error`). Refuse a door ticket at `/__porthole/d
|
|
1181
|
-
page's shell label. `DOOR_PATH`, `doorResponse` and `doorStatusResponse` are exported from
|
|
1088
|
+
`not-found` / 500 `error`). Refuse a door ticket at `/__porthole/d/`. `DOOR_PATH`, `doorResponse` and `doorStatusResponse` are exported from
|
|
1182
1089
|
`@botiverse/porthole/server`.
|
|
1183
1090
|
|
|
1184
1091
|
**A host that signs its own tickets** (P126) — its server mints its own ticket for a display and its
|
|
@@ -1194,7 +1101,7 @@ document and version, a file set's entry being a page (`not-found`), `doorRespon
|
|
|
1194
1101
|
about the request but its method: **you must have authenticated the request and established the
|
|
1195
1102
|
grant yourself**, as before `issue`. Pass the request so `authorize.check` sees it, and `{ page }`
|
|
1196
1103
|
as the fourth argument for a frame that opens at a file set's page below its version. It throws for
|
|
1197
|
-
an instance with no door (a
|
|
1104
|
+
an instance with no door (a url-mode app) and for an instance or grant `issue` would
|
|
1198
1105
|
refuse. The content route still takes its own ticket and checks again (P050).
|
|
1199
1106
|
|
|
1200
1107
|
`porthole.config(kind)` is the served config while frames are served, the opaque one while they
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -201,23 +201,6 @@ Access is gated by a one-time ticket exchanged for a scoped cookie. Where the ho
|
|
|
201
201
|
holds the page and needs no stable origin, the shell writes it into an opaque
|
|
202
202
|
frame instead.
|
|
203
203
|
|
|
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 an origin of its own (a
|
|
206
|
-
label of the scope's, `porthole-<…>`, on which nothing else is ever served, P114). It
|
|
207
|
-
frames the page in a child sandboxed without `allow-same-origin` (an opaque origin) at
|
|
208
|
-
the page's sealed files' address on that origin, fetched without a cookie, and passes
|
|
209
|
-
messages between the host and the page:
|
|
210
|
-
|
|
211
|
-
```
|
|
212
|
-
Host app Shell (its own origin) Page (opaque child)
|
|
213
|
-
│ frame src = ticketed URL ──►│ frames the sealed address ───►│ runtime + page
|
|
214
|
-
│◄── the page's messages ──────│◄── postMessage (by source) ───│
|
|
215
|
-
│── the host's messages ──────►│── postMessage ───────────────►│
|
|
216
|
-
│◄── porthole/shell/state ─────│ its own activation, its focus │
|
|
217
|
-
│── porthole/shell/look ──────►│ look now (as a move is heard) │
|
|
218
|
-
│── porthole/shell/focus ─────►│ display.focus(): on to the ──►│ the page's window
|
|
219
|
-
```
|
|
220
|
-
|
|
221
204
|
### URL frame
|
|
222
205
|
|
|
223
206
|
```
|
|
@@ -283,22 +266,6 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
|
|
|
283
266
|
matches find found) is the content's word even when the shell says it, since they
|
|
284
267
|
share a realm: the host bounds it and uses it as a UI hint, never as a permission
|
|
285
268
|
(P053, P131). What the host sends in (a mark, a find query) the content can read.
|
|
286
|
-
A nested page (P111) is the one place they don't: the shell is a document of its
|
|
287
|
-
own, the page's parent, on another origin than the page's (opaque), so the page
|
|
288
|
-
reaches nothing of the shell's realm. Nor does any other content: the shell's
|
|
289
|
-
origin is a label of its own that hosts nothing but nested pages' shells, their
|
|
290
|
-
opaque pages, those pages' files and status pages (P114), never the scope's
|
|
291
|
-
origin, where the scope's other displays run content with `allow-same-origin`
|
|
292
|
-
(porthole#56). The server holds that rule, not the host's layout. The shell trusts the page's messages by
|
|
293
|
-
`event.source` alone and passes them on unchanged, never in its own namespace
|
|
294
|
-
(`porthole/shell/`); what it says in that namespace is the shell's own word (its
|
|
295
|
-
transient activation, which only a press or key in the page turns on, and whether
|
|
296
|
-
focus is in it), and the host, which knows the frame is nested from its config
|
|
297
|
-
only, uses it to tell the person's gesture from the page's (the focus guard,
|
|
298
|
-
`comments.open`). The host's own words in that namespace (its ask to look, P120)
|
|
299
|
-
go to the shell alone. A key and a press look the same in that word, so the host
|
|
300
|
-
doesn't ask it while it fights a frame for the keyboard (P120). Everything else
|
|
301
|
-
the page says is still the content's word.
|
|
302
269
|
|
|
303
270
|
5. **Host's decision ↔ content domain.** Authentication and authorization
|
|
304
271
|
*policy* are the host's; carrying the host's decision safely onto the content
|