@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/dist/shell/runtime.js
CHANGED
|
@@ -1,3 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a draft holds back (P117), spliced into the runtime: a tag start the content was cut in
|
|
3
|
+
* (a trailing `<`, `</`, or `<` and a tag's name or attributes, with no `>` yet) is left out until
|
|
4
|
+
* more comes. Parsed as it is, a cut right after `<` or `</` draws them as text.
|
|
5
|
+
*/
|
|
6
|
+
export const HELD_BACK = String.raw `(html) => {
|
|
7
|
+
const at = html.lastIndexOf("<");
|
|
8
|
+
return at !== -1 && /^\/?(?:[A-Za-z][^>]*)?$/.test(html.slice(at + 1)) ? html.slice(0, at) : html;
|
|
9
|
+
}`;
|
|
1
10
|
/**
|
|
2
11
|
* The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
|
|
3
12
|
* no imports and no build step, so every engine (a browser frame now, a native web view later)
|
|
@@ -68,6 +77,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
68
77
|
}
|
|
69
78
|
};
|
|
70
79
|
|
|
80
|
+
// Whether the page touched storage, told to the host once (P111): yes, never what it keeps.
|
|
81
|
+
let storageTouched = false;
|
|
82
|
+
let tellStorage = () => {};
|
|
71
83
|
if (plan.storage === "memory") {
|
|
72
84
|
// An opaque origin has no storage: a map stands in, for as long as the frame lives.
|
|
73
85
|
const store = () => {
|
|
@@ -84,8 +96,18 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
84
96
|
};
|
|
85
97
|
};
|
|
86
98
|
for (const name of ["localStorage", "sessionStorage"]) {
|
|
99
|
+
const kept = store();
|
|
87
100
|
try {
|
|
88
|
-
Object.defineProperty(window, name, {
|
|
101
|
+
Object.defineProperty(window, name, {
|
|
102
|
+
configurable: true,
|
|
103
|
+
get() {
|
|
104
|
+
if (!storageTouched) {
|
|
105
|
+
storageTouched = true;
|
|
106
|
+
tellStorage();
|
|
107
|
+
}
|
|
108
|
+
return kept;
|
|
109
|
+
},
|
|
110
|
+
});
|
|
89
111
|
} catch (_) {}
|
|
90
112
|
}
|
|
91
113
|
}
|
|
@@ -115,6 +137,8 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
115
137
|
// takes the next load for that page, not for content that left). Anything else stays stopped:
|
|
116
138
|
// another path of the origin, a file that isn't a page, another origin.
|
|
117
139
|
let navigating = (_url) => {};
|
|
140
|
+
// A nested page's files' address renewed by its shell (P111), which the shell's message gives.
|
|
141
|
+
let adoptFiles = (_base) => false;
|
|
118
142
|
let filesBase = plan.files && typeof plan.files.base === "string" ? plan.files.base : null;
|
|
119
143
|
// Every address the page's files had (P083: a sealed one is renewed): what reports say as "./".
|
|
120
144
|
const filesBases = filesBase === null ? [] : [filesBase];
|
|
@@ -880,6 +904,11 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
880
904
|
const filesSet = plan.files && plan.files.set && typeof plan.files.set === "object" ? { id: String(plan.files.set.id), version: String(plan.files.set.version) } : null;
|
|
881
905
|
const notice = (url, more) => post({ method: "porthole/navigating", params: Object.assign({ url: ownAddresses(url).slice(0, 4096) }, filesSet === null ? {} : { set: filesSet }, more) });
|
|
882
906
|
navigating = (url) => notice(url, {});
|
|
907
|
+
// The page used storage (P111): said once, as soon as the shell can speak; never keys or values.
|
|
908
|
+
tellStorage = () => post({ method: "porthole/storage-used", params: {} });
|
|
909
|
+
if (storageTouched) {
|
|
910
|
+
tellStorage();
|
|
911
|
+
}
|
|
883
912
|
if (arrived) {
|
|
884
913
|
notice(location.href, { arrived: true });
|
|
885
914
|
}
|
|
@@ -887,28 +916,38 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
887
916
|
// it ends, the page moved to the new one in place (the same page, the same history entry). Its
|
|
888
917
|
// modules keep the address they loaded from; the server serves their own loads till the session
|
|
889
918
|
// ends.
|
|
919
|
+
const replace = History.prototype.replaceState;
|
|
920
|
+
// The files' origin, read from the address itself: a nested page's own origin is opaque (P111).
|
|
921
|
+
const filesOrigin = filesBase === null ? null : new NativeURL(filesBase).origin;
|
|
922
|
+
// A renewed sealed address (P083): one segment under the same origin's sealed prefix, checked
|
|
923
|
+
// through the platform's own functions (content may have replaced a prototype's, and the base
|
|
924
|
+
// decides where this page may go, ownPage); the page moves there in place.
|
|
925
|
+
const adopt = (base) => {
|
|
926
|
+
const prefix = filesOrigin + "/__porthole/f/";
|
|
927
|
+
if (filesBase === null || typeof base !== "string" || callOf(indexIn, base, [prefix]) !== 0 || callOf(indexIn, callOf(sliceOf, base, [prefix.length, -1]), ["/"]) !== -1 || callOf(sliceOf, base, [-1]) !== "/") {
|
|
928
|
+
return false;
|
|
929
|
+
}
|
|
930
|
+
const here = location.href;
|
|
931
|
+
if (here.indexOf(filesBase) === 0) {
|
|
932
|
+
try {
|
|
933
|
+
applyOf(replace, history, [history.state, "", base + here.slice(filesBase.length)]);
|
|
934
|
+
} catch (_) {}
|
|
935
|
+
}
|
|
936
|
+
filesBase = base;
|
|
937
|
+
filesBases.push(base);
|
|
938
|
+
return true;
|
|
939
|
+
};
|
|
940
|
+
adoptFiles = adopt;
|
|
890
941
|
if (filesBase !== null && typeof plan.files.expires === "number") {
|
|
891
942
|
const nativeFetch = window.fetch.bind(window);
|
|
892
|
-
const replace = History.prototype.replaceState;
|
|
893
943
|
const renewIn = (expires) => Math.max(30000, expires - Date.now() - 300000);
|
|
894
944
|
const renew = () => {
|
|
895
945
|
nativeFetch(filesBase + "__porthole/renew", { credentials: "omit", cache: "no-store" })
|
|
896
946
|
.then((answer) => (answer.ok ? answer.json() : null))
|
|
897
947
|
.then((renewed) => {
|
|
898
|
-
|
|
899
|
-
// and the base decides where this page may go (ownPage).
|
|
900
|
-
const prefix = location.origin + "/__porthole/f/";
|
|
901
|
-
if (!renewed || typeof renewed.base !== "string" || typeof renewed.expires !== "number" || callOf(indexIn, renewed.base, [prefix]) !== 0 || callOf(indexIn, callOf(sliceOf, renewed.base, [prefix.length, -1]), ["/"]) !== -1 || callOf(sliceOf, renewed.base, [-1]) !== "/") {
|
|
948
|
+
if (!renewed || typeof renewed.expires !== "number" || !adopt(renewed.base)) {
|
|
902
949
|
return;
|
|
903
950
|
}
|
|
904
|
-
const here = location.href;
|
|
905
|
-
if (here.indexOf(filesBase) === 0) {
|
|
906
|
-
try {
|
|
907
|
-
applyOf(replace, history, [history.state, "", renewed.base + here.slice(filesBase.length)]);
|
|
908
|
-
} catch (_) {}
|
|
909
|
-
}
|
|
910
|
-
filesBase = renewed.base;
|
|
911
|
-
filesBases.push(renewed.base);
|
|
912
951
|
setTimeout(renew, renewIn(renewed.expires));
|
|
913
952
|
})
|
|
914
953
|
.catch(() => setTimeout(renew, 60000));
|
|
@@ -1393,11 +1432,12 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
1393
1432
|
}
|
|
1394
1433
|
};
|
|
1395
1434
|
let drafted = false;
|
|
1435
|
+
const heldBack = ${HELD_BACK};
|
|
1396
1436
|
const draft = (input) => {
|
|
1397
1437
|
if (rendered || root === null || input === null || typeof input !== "object" || plan.content === "document") {
|
|
1398
1438
|
return;
|
|
1399
1439
|
}
|
|
1400
|
-
morph(root, inert(parseInert(input.html || "")));
|
|
1440
|
+
morph(root, inert(parseInert(heldBack(String(input.html || "")))));
|
|
1401
1441
|
drafted = true;
|
|
1402
1442
|
drawn = true;
|
|
1403
1443
|
schedule();
|
|
@@ -1465,6 +1505,11 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
1465
1505
|
case "ui/notifications/tool-input":
|
|
1466
1506
|
void render(params.arguments);
|
|
1467
1507
|
break;
|
|
1508
|
+
case "porthole/files-renewed":
|
|
1509
|
+
// From the page's parent only (the listener's check): a nested page's shell renewed its
|
|
1510
|
+
// files' sealed address, which this page can't (its loads aren't its origin's own, P111).
|
|
1511
|
+
adoptFiles(params.base);
|
|
1512
|
+
break;
|
|
1468
1513
|
case "ui/notifications/host-context-changed":
|
|
1469
1514
|
applyTheme(params);
|
|
1470
1515
|
break;
|
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
|
|
@@ -286,7 +297,11 @@ display.on("annotation", (report) => {
|
|
|
286
297
|
to its author after; origins its config declares for egress (an MCP App's `connectDomains`, an
|
|
287
298
|
`egress` you opened) can carry the same out. Send
|
|
288
299
|
drafts only to pages without such a channel (annotations, `copyText`, `openLink` and the like),
|
|
289
|
-
or accept that the page's author and other viewers can learn of them (THREAT_MODEL §7).
|
|
300
|
+
or accept that the page's author and other viewers can learn of them (THREAT_MODEL §7). Ask
|
|
301
|
+
`host.mayPassOn(declaration)` (or `mayPassOn(config, declaration)`, P112): true for a page that
|
|
302
|
+
can reach `db`, `artifact`, `assets`, `openLink`, `sendPrompt`, `setModelContext`, `callTool`,
|
|
303
|
+
`readData` or `subscribeData` (or `reportError` with errors to the agent), or egress beyond the
|
|
304
|
+
library CDNs (whose paths only their operators read); show such a page no draft marks.
|
|
290
305
|
- **The content chooses when your view opens and where** (it can post `activated` for a mark you
|
|
291
306
|
show on the person's own press in the content, under their pointer, P105), so a view that a
|
|
292
307
|
report opens or moves takes no press of any kind for 500 ms after it appears or moves (no
|
|
@@ -359,7 +374,10 @@ display.on("focusTaken", ({ typing }) => toast(typing ? "This page tried to take
|
|
|
359
374
|
display.on("contentError", ({ message }) => log(message)); // "The content kept taking the keyboard from the page; it was stopped."
|
|
360
375
|
// Moving focus into a display yourself (a "focus the page" shortcut): use the display's own move.
|
|
361
376
|
display.focus(); // not frame.focus(): from a text field, that one is taken for the page's and undone
|
|
362
|
-
// Opening your composer focused
|
|
377
|
+
// Opening your composer focused: only in a comment mode the person started, for a composer that can
|
|
378
|
+
// only save a draft (Enter adds it to the batch; submitting is only your own "Submit N"), and that
|
|
379
|
+
// shows plainly it is a draft (THREAT_MODEL §6, P112); any other view a report opens takes no focus. Then
|
|
380
|
+
// Porthole's move, not textarea.focus().
|
|
363
381
|
import { focusField } from "@botiverse/porthole";
|
|
364
382
|
focusField(composer.textarea); // Firefox ignores a plain focus() while a fighting frame holds focus
|
|
365
383
|
```
|
|
@@ -375,6 +393,12 @@ focusField(composer.textarea); // Firefox ignores a plain focus() while a fighti
|
|
|
375
393
|
the limits (THREAT_MODEL §7 "The keyboard": on Firefox, which shows your page no press
|
|
376
394
|
in a frame, a page keeps the keyboard if the pointer came over its frame after the person last
|
|
377
395
|
typed and after the field got focus; moves between two frames aren't judged).
|
|
396
|
+
- **Served pages in full Chromium:** nest them ("Nested pages" below, P111). A served page's
|
|
397
|
+
frame there is out of process: your page sees no press in it, so a person's click into the
|
|
398
|
+
page's field is taken back. A nested page's shell sees it: a move into the frame is the
|
|
399
|
+
person's if the shell's activation turned on within the last second and you saw no press or key
|
|
400
|
+
of your own since. A second press in the page within 5 s of the last turns nothing on: after the
|
|
401
|
+
person went back to your composer, their next move in is taken back until then, or a Tab.
|
|
378
402
|
|
|
379
403
|
## 4. Served pages: the host kit
|
|
380
404
|
|
|
@@ -528,6 +552,65 @@ entry: {
|
|
|
528
552
|
})` to run it, and the manual's Files section where a kind serves files. Show a set served: an
|
|
529
553
|
opaque frame has no origin to serve its files from.
|
|
530
554
|
|
|
555
|
+
### Nested pages: the page below Porthole's shell
|
|
556
|
+
|
|
557
|
+
`nested: true` (P111) on an artifact kind served by the host kit puts the page in a frame of its
|
|
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
|
|
562
|
+
type beside your displays: in full Chromium (a person's browser, not Playwright's headless shell) a
|
|
563
|
+
served page's frame is out of process, and your page can't see a press in it, so without nesting a
|
|
564
|
+
real click into the page's field is taken back and `comments.open` from a real click is refused
|
|
565
|
+
within 5 s of any input on your page (porthole#53). The page's shell sees it, and tells your page.
|
|
566
|
+
|
|
567
|
+
```ts
|
|
568
|
+
const displays = defineDisplays({
|
|
569
|
+
page: {
|
|
570
|
+
preset: "artifact",
|
|
571
|
+
// No `served.storage`: a nested page keeps no storage of its own (localStorage lasts the load).
|
|
572
|
+
options: { runtime: "1", capabilities: { annotate: {}, comments: {} }, nested: true },
|
|
573
|
+
},
|
|
574
|
+
});
|
|
575
|
+
```
|
|
576
|
+
|
|
577
|
+
Nothing else changes on your page: the same `createHost` (or `PortholeFrame`), the same handlers
|
|
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
|
|
587
|
+
run: whether the page touched `localStorage` or `sessionStorage`, never what it kept), for you to
|
|
588
|
+
count the pages that would need storage. A nested page's workers come from Blob URLs (a worker from
|
|
589
|
+
a script of its own set is refused: its origin is opaque), which may `importScripts` the set's
|
|
590
|
+
scripts; Chromium refuses a Blob module worker there. Not yet with a nested page: the asset library (`assets`)
|
|
591
|
+
and Porthole's libraries (`egress.libraries`); the config refuses them.
|
|
592
|
+
|
|
593
|
+
What a content origin serves for a nested page (`/server` does all of it; a content Worker of your
|
|
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.
|
|
605
|
+
|
|
606
|
+
| Request | Answer |
|
|
607
|
+
| --- | --- |
|
|
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. |
|
|
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`). |
|
|
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. |
|
|
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. |
|
|
612
|
+
| A token that ended, under the prefix | Porthole's status page (`401`, reason `session`), `frame-ancestors <origin> <host origins>`: it tells the shell, which tells your page (`outcome` blocked). |
|
|
613
|
+
|
|
531
614
|
### The capability runtime: pages that are apps
|
|
532
615
|
|
|
533
616
|
0.7 (P085–P090). A page reaches your services through one global, `porthole.use(name)`, for what
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -201,6 +201,21 @@ 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
|
+
```
|
|
218
|
+
|
|
204
219
|
### URL frame
|
|
205
220
|
|
|
206
221
|
```
|
|
@@ -265,6 +280,19 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
|
|
|
265
280
|
itself (its size, its errors, an annotation's anchor and where it is) is the
|
|
266
281
|
content's word even when the shell says it, since they share a realm: the host
|
|
267
282
|
bounds it and uses it as a UI hint, never as a permission (P053).
|
|
283
|
+
A nested page (P111) is the one place they don't: the shell is a document of its
|
|
284
|
+
own, the page's parent, on another origin than the page's (opaque), so the page
|
|
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
|
|
290
|
+
`event.source` alone and passes them on unchanged, never in its own namespace
|
|
291
|
+
(`porthole/shell/`); what it says in that namespace is the shell's own word (its
|
|
292
|
+
transient activation, which only a press or key in the page turns on, and whether
|
|
293
|
+
focus is in it), and the host, which knows the frame is nested from its config
|
|
294
|
+
only, uses it to tell the person's gesture from the page's (the focus guard,
|
|
295
|
+
`comments.open`). Everything else the page says is still the content's word.
|
|
268
296
|
|
|
269
297
|
5. **Host's decision ↔ content domain.** Authentication and authorization
|
|
270
298
|
*policy* are the host's; carrying the host's decision safely onto the content
|