@botiverse/porthole 0.14.0 → 0.14.2
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 +782 -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 +30 -4
- package/dist/react/frame.js +69 -5
- package/dist/react/index.d.ts +1 -1
- package/dist/react/view.js +10 -4
- 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 +55 -7
- package/docs/ARCHITECTURE.md +10 -5
- package/docs/DECISIONS.md +248 -1
- package/docs/DESIGN.md +18 -7
- 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 +114 -6
- package/src/react/index.ts +1 -0
- package/src/react/view.tsx +20 -2
- 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/dist/host/create-host.js
CHANGED
|
@@ -359,6 +359,11 @@ export function createHost(config, options = {}) {
|
|
|
359
359
|
tracking = null;
|
|
360
360
|
toFrame(ANNOTATE_METHODS.clear, {});
|
|
361
361
|
},
|
|
362
|
+
clearSelection() {
|
|
363
|
+
// Host → frame only, and kept for no later frame (P115).
|
|
364
|
+
needsAnnotate("clearSelection");
|
|
365
|
+
toFrame(ANNOTATE_METHODS.clearSelection, {});
|
|
366
|
+
},
|
|
362
367
|
};
|
|
363
368
|
const hostContext = () => {
|
|
364
369
|
const width = container.getBoundingClientRect().width;
|
package/dist/host/types.d.ts
CHANGED
|
@@ -252,6 +252,13 @@ export interface AnnotationControls {
|
|
|
252
252
|
track(id: string | null): void;
|
|
253
253
|
/** Removes every mark. */
|
|
254
254
|
clear(): void;
|
|
255
|
+
/**
|
|
256
|
+
* Takes the page's text selection away (P115), its highlight with it: for when the host has
|
|
257
|
+
* used it (a comment posted, a draft added). No `unselected` follows; marks (posted and drafts),
|
|
258
|
+
* the mode and a followed mark stay as they are. Nothing selected: nothing happens. Not kept for
|
|
259
|
+
* a frame that runs later (it has no selection to clear).
|
|
260
|
+
*/
|
|
261
|
+
clearSelection(): void;
|
|
255
262
|
}
|
|
256
263
|
export interface DisplayControls {
|
|
257
264
|
readonly displayId: string;
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { PageDeclaration } from "../runtime/declaration.ts";
|
|
2
2
|
import type { ViewerInfo } from "../runtime/levels.ts";
|
|
3
|
-
import { type CSSProperties, type ReactElement, type ReactNode } from "react";
|
|
3
|
+
import { type CSSProperties, type ReactElement, type ReactNode, type Ref } from "react";
|
|
4
4
|
import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
|
|
5
5
|
import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal, Show } from "../bridge/types.ts";
|
|
6
6
|
import { Refused, type RefusalReason } from "../bridge/refusal.ts";
|
|
@@ -140,6 +140,20 @@ export interface PlaceholderProps {
|
|
|
140
140
|
/** Runs the display again (a stopped one), stopping another if the page is at its most. */
|
|
141
141
|
readonly run: () => void;
|
|
142
142
|
}
|
|
143
|
+
/**
|
|
144
|
+
* What a `ref` on `PortholeFrame` or `PortholeView` holds (P118): the display's few imperative
|
|
145
|
+
* calls, never the display itself. The same handle for the frame's whole life: its calls do
|
|
146
|
+
* nothing while no display runs (waiting to near the screen, stopped, a fallback drawn).
|
|
147
|
+
*/
|
|
148
|
+
export interface PortholeFrameHandle {
|
|
149
|
+
/**
|
|
150
|
+
* Takes the page's text selection away, and its highlight (`annotations.clearSelection()`,
|
|
151
|
+
* P115), once the host has used it (a comment posted, a draft added). No `unselected` follows.
|
|
152
|
+
* Nothing runs: nothing happens. A config without `annotate`: `onHostError`, kind
|
|
153
|
+
* `"annotations"` (the core's call throws; this never does).
|
|
154
|
+
*/
|
|
155
|
+
clearSelection(): void;
|
|
156
|
+
}
|
|
143
157
|
export interface PortholeFrameProps {
|
|
144
158
|
/** A preset's config. Keep it stable (module scope or memoized): a new one remounts the frame. */
|
|
145
159
|
readonly config: PortholeConfig;
|
|
@@ -160,10 +174,11 @@ export interface PortholeFrameProps {
|
|
|
160
174
|
readonly instance?: InstanceRef;
|
|
161
175
|
/**
|
|
162
176
|
* What the page declared (P086), as the host stored it with the artifact: the capabilities it
|
|
163
|
-
* reaches through `porthole.use`, and its pinned runtime.
|
|
164
|
-
*
|
|
177
|
+
* reaches through `porthole.use`, and its pinned runtime. Under `config.runtime`, `null` says
|
|
178
|
+
* the page was published before 0.7 and has 0.6's surface (`MountOptions.declaration`). By
|
|
179
|
+
* value: a change makes the display again.
|
|
165
180
|
*/
|
|
166
|
-
readonly declaration?: PageDeclaration;
|
|
181
|
+
readonly declaration?: PageDeclaration | null;
|
|
167
182
|
/**
|
|
168
183
|
* Who is viewing (P087), for an opaque frame or one whose issue gave none. By value: a change
|
|
169
184
|
* makes the display again.
|
|
@@ -272,6 +287,17 @@ export interface PortholeFrameProps {
|
|
|
272
287
|
readonly id: string;
|
|
273
288
|
readonly key: string | number;
|
|
274
289
|
} | null;
|
|
290
|
+
/**
|
|
291
|
+
* The mark to follow (`annotations.track`, P112, P118): while it moves, `onAnnotation` gets
|
|
292
|
+
* `{ type: "tracked", id, rect }` at most once per animation frame, for it alone. `null` (or
|
|
293
|
+
* leaving it out once set) stops. By value: given when it changes, and when the display is made.
|
|
294
|
+
* Only a shown mark (`annotations`) is followed: another id, or a config without `annotate`, is
|
|
295
|
+
* `onHostError` (kind `"annotations"`), as the core's call throws. `annotations` without it
|
|
296
|
+
* stop the following, as the core's `show` does; it starts again once they have it back.
|
|
297
|
+
*/
|
|
298
|
+
readonly trackedAnnotation?: string | null;
|
|
299
|
+
/** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
|
|
300
|
+
readonly ref?: Ref<PortholeFrameHandle>;
|
|
275
301
|
/**
|
|
276
302
|
* What the frame reported: a selection (an anchor and where it is), its clearing, a cancelled
|
|
277
303
|
* pick, where marks are (again once a scroll settles: those that moved), a marker clicked
|
package/dist/react/frame.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
2
|
-
import { createContext, useCallback, useContext, useEffect, useEffectEvent, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
|
|
2
|
+
import { createContext, useCallback, useContext, useEffect, useEffectEvent, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
|
|
3
3
|
import { isRefused, reasonOf, Refused } from "../bridge/refusal.js";
|
|
4
4
|
import { writeClipboard } from "../host/clipboard.js";
|
|
5
5
|
import { createHost } from "../host/create-host.js";
|
|
@@ -292,7 +292,25 @@ export function PortholeFrame(props) {
|
|
|
292
292
|
const box = useRef(null);
|
|
293
293
|
const max = props.config.limits.maxLiveFrames;
|
|
294
294
|
const state = useSyncExternalStore((listener) => live.subscribe(listener), () => live.state(key), () => "waiting");
|
|
295
|
-
const { eager } = props;
|
|
295
|
+
const { eager, ref: handleRef } = props;
|
|
296
|
+
// The running display (the Mount's), for the handle's calls; null while none runs.
|
|
297
|
+
const display = useRef(null);
|
|
298
|
+
const running = useCallback((each) => {
|
|
299
|
+
display.current = each;
|
|
300
|
+
}, []);
|
|
301
|
+
// The props as of the last render, read when the handle is called (never during render).
|
|
302
|
+
const own = useRef(props);
|
|
303
|
+
useLayoutEffect(() => {
|
|
304
|
+
own.current = props;
|
|
305
|
+
});
|
|
306
|
+
useImperativeHandle(handleRef, () => ({
|
|
307
|
+
clearSelection() {
|
|
308
|
+
const now = display.current;
|
|
309
|
+
if (now !== null) {
|
|
310
|
+
attempt(() => now.annotations.clearSelection(), own.current);
|
|
311
|
+
}
|
|
312
|
+
},
|
|
313
|
+
}), []);
|
|
296
314
|
useEffect(() => {
|
|
297
315
|
const element = box.current;
|
|
298
316
|
if (element === null) {
|
|
@@ -343,12 +361,15 @@ export function PortholeFrame(props) {
|
|
|
343
361
|
: {}),
|
|
344
362
|
...(state === "running" ? {} : { minHeight: Math.max(height, PLACEHOLDER_HEIGHT_PX) }),
|
|
345
363
|
...props.style,
|
|
346
|
-
}, children: state === "running" ? (_jsx(Mount, { frame: props, page: page, initialHeightPx: height, placeholder: placeholder, run: run }, String(props.generation ?? 0))) : (placeholder({ state, title: props.title, run })) }));
|
|
364
|
+
}, children: state === "running" ? (_jsx(Mount, { frame: props, page: page, running: running, initialHeightPx: height, placeholder: placeholder, run: run }, String(props.generation ?? 0))) : (placeholder({ state, title: props.title, run })) }));
|
|
347
365
|
}
|
|
348
366
|
/** One running display: created when mounted, torn down when unmounted, fed as props change. */
|
|
349
|
-
function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
367
|
+
function Mount({ frame, page, running, initialHeightPx, placeholder, run, }) {
|
|
350
368
|
const holder = useRef(null);
|
|
351
369
|
const handle = useRef(null);
|
|
370
|
+
// The mark the display follows now, as the core keeps it (P118), and the prop as last seen.
|
|
371
|
+
const following = useRef(null);
|
|
372
|
+
const asked = useRef(null);
|
|
352
373
|
const [ready, setReady] = useState(false);
|
|
353
374
|
// The height this display started at: later reports don't make it start again.
|
|
354
375
|
const [startHeight] = useState(initialHeightPx);
|
|
@@ -527,6 +548,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
527
548
|
return;
|
|
528
549
|
}
|
|
529
550
|
handle.current = display;
|
|
551
|
+
running(display);
|
|
530
552
|
const events = [
|
|
531
553
|
"initialized",
|
|
532
554
|
"resize",
|
|
@@ -547,12 +569,24 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
547
569
|
if (config.capabilities.annotate !== undefined) {
|
|
548
570
|
applyAnnotations(display, first);
|
|
549
571
|
}
|
|
572
|
+
// The followed mark, once the marks are shown; without `annotate`, the core's error.
|
|
573
|
+
following.current = null;
|
|
574
|
+
const wanted = first.trackedAnnotation ?? null;
|
|
575
|
+
asked.current = wanted;
|
|
576
|
+
if (wanted !== null) {
|
|
577
|
+
attempt(() => {
|
|
578
|
+
display.annotations.track(wanted);
|
|
579
|
+
following.current = wanted;
|
|
580
|
+
}, first);
|
|
581
|
+
}
|
|
550
582
|
if (first.content !== undefined) {
|
|
551
583
|
display.setContent(first.content, { partial: first.partial === true });
|
|
552
584
|
}
|
|
553
585
|
return () => {
|
|
554
586
|
display.destroy();
|
|
555
587
|
handle.current = null;
|
|
588
|
+
running(null);
|
|
589
|
+
following.current = null;
|
|
556
590
|
};
|
|
557
591
|
// A new display only for a new config, document or instance, or what the provider makes
|
|
558
592
|
// displays with (its nonce, hostInfo by value, whether it locates or confirms; generation, by
|
|
@@ -575,6 +609,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
575
609
|
hostInfo,
|
|
576
610
|
locate,
|
|
577
611
|
nonce,
|
|
612
|
+
running,
|
|
578
613
|
]);
|
|
579
614
|
useEffect(() => {
|
|
580
615
|
if (content !== undefined) {
|
|
@@ -608,9 +643,34 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
608
643
|
useEffect(() => {
|
|
609
644
|
const display = handle.current;
|
|
610
645
|
if (annotates && display !== null) {
|
|
611
|
-
attempt(() =>
|
|
646
|
+
attempt(() => {
|
|
647
|
+
display.annotations.show(annotations ?? []);
|
|
648
|
+
// A show without the followed mark stops the following (the core's own).
|
|
649
|
+
if (following.current !== null && !shown(annotations, following.current)) {
|
|
650
|
+
following.current = null;
|
|
651
|
+
}
|
|
652
|
+
}, latest());
|
|
612
653
|
}
|
|
613
654
|
}, [annotates, annotations]);
|
|
655
|
+
// The followed mark follows its prop (after the marks above, so the two can change together).
|
|
656
|
+
const trackedAnnotation = frame.trackedAnnotation ?? null;
|
|
657
|
+
useEffect(() => {
|
|
658
|
+
const display = handle.current;
|
|
659
|
+
const changed = trackedAnnotation !== asked.current;
|
|
660
|
+
asked.current = trackedAnnotation;
|
|
661
|
+
if (display === null || trackedAnnotation === following.current) {
|
|
662
|
+
return;
|
|
663
|
+
}
|
|
664
|
+
// Its mark was taken off (the error, if any, was told when the prop said it): followed again
|
|
665
|
+
// once the marks have it back.
|
|
666
|
+
if (!changed && trackedAnnotation !== null && !shown(annotations, trackedAnnotation)) {
|
|
667
|
+
return;
|
|
668
|
+
}
|
|
669
|
+
attempt(() => {
|
|
670
|
+
display.annotations.track(trackedAnnotation);
|
|
671
|
+
following.current = trackedAnnotation;
|
|
672
|
+
}, latest());
|
|
673
|
+
}, [trackedAnnotation, annotations]);
|
|
614
674
|
useEffect(() => {
|
|
615
675
|
const display = handle.current;
|
|
616
676
|
const id = focusOf(latest().focusedAnnotation);
|
|
@@ -695,6 +755,10 @@ function useByValue(value) {
|
|
|
695
755
|
const key = value === undefined ? "" : JSON.stringify(value);
|
|
696
756
|
return useMemo(() => (key === "" ? undefined : JSON.parse(key)), [key]);
|
|
697
757
|
}
|
|
758
|
+
/** Whether `marks` has a mark `id`. */
|
|
759
|
+
function shown(marks, id) {
|
|
760
|
+
return (marks ?? []).some((mark) => mark.id === id);
|
|
761
|
+
}
|
|
698
762
|
/** The id `focusedAnnotation` names, if any. */
|
|
699
763
|
function focusOf(value) {
|
|
700
764
|
return typeof value === "string"
|
package/dist/react/index.d.ts
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* theme={tokensFor} onError={report} />
|
|
9
9
|
* </PortholeProvider>
|
|
10
10
|
*/
|
|
11
|
-
export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, type PlaceholderProps, type PortholeFrameProps, type ConfirmActions, type PortholeProviderProps, } from "./frame.tsx";
|
|
11
|
+
export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, type PlaceholderProps, type PortholeFrameHandle, type PortholeFrameProps, type ConfirmActions, type PortholeProviderProps, } from "./frame.tsx";
|
|
12
12
|
export { ARM_DELAY_MS, ConfirmDialog, type ConfirmDialogProps } from "./dialog.tsx";
|
|
13
13
|
export { ContextNotice, contextSize, contextText, type ContextNoticeProps, type ContextUpdate, } from "./context-notice.tsx";
|
|
14
14
|
export { cssVariableTheme, PortholeView, usePortholeLink, useRunAgain, type PortholeFallbackProps, type PortholeViewProps, } from "./view.tsx";
|
package/dist/react/view.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
2
|
-
import { useCallback, useContext, useEffect, useState, useSyncExternalStore, } from "react";
|
|
2
|
+
import { useCallback, useContext, useEffect, useImperativeHandle, useRef, useState, useSyncExternalStore, } from "react";
|
|
3
3
|
import { frameFallback } from "../host/client.js";
|
|
4
|
-
import { PortholeFrame, PortholeContext } from "./frame.js";
|
|
4
|
+
import { PortholeFrame, PortholeContext, } from "./frame.js";
|
|
5
5
|
function useClient() {
|
|
6
6
|
const client = useContext(PortholeContext).client;
|
|
7
7
|
if (client === undefined) {
|
|
@@ -24,7 +24,13 @@ function DefaultFallback({ title, message, link }) {
|
|
|
24
24
|
export function PortholeView(props) {
|
|
25
25
|
const client = useClient();
|
|
26
26
|
const meta = useMeta(client);
|
|
27
|
-
const { display, instance, content, fallback, pending, onOutcome, ...frame } = props;
|
|
27
|
+
const { display, instance, content, fallback, pending, onOutcome, ref, ...frame } = props;
|
|
28
|
+
// The view's handle (P118) is there while the view is, a fallback drawn or not: its calls reach
|
|
29
|
+
// the frame's display when one runs, and do nothing otherwise.
|
|
30
|
+
const shown = useRef(null);
|
|
31
|
+
useImperativeHandle(ref, () => ({
|
|
32
|
+
clearSelection: () => shown.current?.clearSelection(),
|
|
33
|
+
}), []);
|
|
28
34
|
const [failed, setFailed] = useState(null);
|
|
29
35
|
const [generation, setGeneration] = useState(0);
|
|
30
36
|
const [link, setLink] = useState(null);
|
|
@@ -73,7 +79,7 @@ export function PortholeView(props) {
|
|
|
73
79
|
if (failed !== null) {
|
|
74
80
|
return _jsx(_Fragment, { children: (fallback ?? DefaultFallback)({ ...failed, link, retry }) });
|
|
75
81
|
}
|
|
76
|
-
return (_jsx(PortholeFrame, { ...frame, config: config, generation: (frame.generation ?? 0) + generation, ...(instance === undefined ? {} : { instance }), ...(content === undefined ? {} : { content }), onOutcome: (outcome) => {
|
|
82
|
+
return (_jsx(PortholeFrame, { ...frame, ref: shown, config: config, generation: (frame.generation ?? 0) + generation, ...(instance === undefined ? {} : { instance }), ...(content === undefined ? {} : { content }), onOutcome: (outcome) => {
|
|
77
83
|
onOutcome?.(outcome);
|
|
78
84
|
const said = frameFallback(outcome, { url });
|
|
79
85
|
if (said !== null) {
|
package/dist/server/index.d.ts
CHANGED
|
@@ -37,7 +37,7 @@ export { createContentHost, HEALTH_PATH, ISSUE_BODY_BYTES, type ContentHealthVie
|
|
|
37
37
|
export { clashOf, contentDomain, ContentDomainError, hostnameOf, type ContentDomainInfo, type ContentDomainProblem, } from "./domain.ts";
|
|
38
38
|
export { d1TicketSchema, d1TicketStore, memoryTicketStore, type D1Like, type D1StatementLike, } from "./tickets.ts";
|
|
39
39
|
export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
|
|
40
|
-
export { NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedShellCsp, nestedShellResponse, } from "./nested.ts";
|
|
40
|
+
export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.ts";
|
|
41
41
|
export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
|
|
42
42
|
export { conformancePage } from "../conformance/page.ts";
|
|
43
43
|
export type { PortholeConfig } from "../config/schema.ts";
|
package/dist/server/index.js
CHANGED
|
@@ -38,9 +38,10 @@ export { clashOf, contentDomain, ContentDomainError, hostnameOf, } from "./domai
|
|
|
38
38
|
export { d1TicketSchema, d1TicketStore, memoryTicketStore, } from "./tickets.js";
|
|
39
39
|
export { FRAME_STATUS_METHOD } from "../isolation/types.js";
|
|
40
40
|
// A nested page (P111): Porthole's shell at the framed address, the page and its files below the
|
|
41
|
-
// sealed prefix
|
|
42
|
-
// answers the same (docs/ADOPTING.md, "Nested
|
|
43
|
-
|
|
41
|
+
// sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
|
|
42
|
+
// config with `nested`; a content Worker of its own answers the same (docs/ADOPTING.md, "Nested
|
|
43
|
+
// pages").
|
|
44
|
+
export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
|
|
44
45
|
export { isHostLabel, prefixedName } from "./naming.js";
|
|
45
46
|
// The page an app serves in conformance test mode (P071).
|
|
46
47
|
export { conformancePage } from "../conformance/page.js";
|
package/dist/server/naming.js
CHANGED
|
@@ -17,6 +17,10 @@ export function prefixedName(prefix) {
|
|
|
17
17
|
if (!PREFIX.test(prefix)) {
|
|
18
18
|
throw new TypeError("A name prefix is a lowercase letter, then letters or digits, then '-' (a-)");
|
|
19
19
|
}
|
|
20
|
+
// Porthole's own labels (a nested page's shell's, P114) are never a scope's.
|
|
21
|
+
if (prefix === "porthole-") {
|
|
22
|
+
throw new TypeError("The name prefix porthole- is Porthole's own: choose another (a-)");
|
|
23
|
+
}
|
|
20
24
|
const name = (scope) => {
|
|
21
25
|
const label = `${prefix}${scope}`;
|
|
22
26
|
if (!ID.test(scope) || !isHostLabel(label)) {
|
package/dist/server/nested.d.ts
CHANGED
|
@@ -5,7 +5,29 @@ import { type FrameShellOptions } from "../shell/frame.ts";
|
|
|
5
5
|
* `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
|
|
6
6
|
* (`nestedAncestors`, `NESTED_FILE_HEADERS`). `/server` serves both for a config with `nested`;
|
|
7
7
|
* a host serving its own content origin (its own Worker) answers the same.
|
|
8
|
+
*
|
|
9
|
+
* All of it is served on the shell's own label (P114, `nestedLabelOf`), never on the scope's: every
|
|
10
|
+
* other display of the scope runs agent-made content on the scope's origin with
|
|
11
|
+
* `allow-same-origin`, which would be same-origin with the shell, its realm and the page's sealed
|
|
12
|
+
* address.
|
|
8
13
|
*/
|
|
14
|
+
/**
|
|
15
|
+
* The start of every label Porthole serves for itself on a content domain (P114): no host's naming
|
|
16
|
+
* may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
|
|
17
|
+
*/
|
|
18
|
+
export declare const PORTHOLE_LABEL_PREFIX = "porthole-";
|
|
19
|
+
/**
|
|
20
|
+
* The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
|
|
21
|
+
* base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
|
|
22
|
+
* content label is ever one (a keyed label has no hyphen, a host's is refused the prefix), so
|
|
23
|
+
* nothing but a nested page's shell, its opaque page, that page's files and Porthole's status pages
|
|
24
|
+
* is ever served on it: no other display's content runs there with `allow-same-origin`. Not a
|
|
25
|
+
* secret: anyone who knows the scope's label may work it out. A content Worker of a host's own
|
|
26
|
+
* serves its nested pages on it too.
|
|
27
|
+
*/
|
|
28
|
+
export declare function nestedLabelOf(label: string): string;
|
|
29
|
+
/** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
|
|
30
|
+
export declare const isNestedLabel: (label: string) => boolean;
|
|
9
31
|
/** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
|
|
10
32
|
export declare const NESTED_FILES_PREFIX = "/__porthole/f/";
|
|
11
33
|
/**
|
|
@@ -24,8 +46,8 @@ export declare function nestedShellResponse(compiled: CompiledConfig, options: F
|
|
|
24
46
|
readonly method?: string;
|
|
25
47
|
}): Response;
|
|
26
48
|
/**
|
|
27
|
-
* Who may frame a nested page and its files' answers: its shell (the
|
|
28
|
-
* it, the host origins (`frame-ancestors` names every ancestor).
|
|
49
|
+
* Who may frame a nested page and its files' answers: its shell (the shell's own origin, P114) and,
|
|
50
|
+
* above it, the host origins (`frame-ancestors` names every ancestor).
|
|
29
51
|
*/
|
|
30
52
|
export declare const nestedAncestors: (origin: string, frameAncestors: string) => string;
|
|
31
53
|
/**
|
package/dist/server/nested.js
CHANGED
|
@@ -1,12 +1,38 @@
|
|
|
1
1
|
import { servedPermissionsPolicy, serializeCsp } from "../compile/policy.js";
|
|
2
2
|
import { frameShellDocument, frameShellScript } from "../shell/frame.js";
|
|
3
3
|
import { sha256, utf8 } from "./crypto.js";
|
|
4
|
+
import { base32 } from "./keys.js";
|
|
4
5
|
/**
|
|
5
6
|
* A nested page's serving (P111): what the address the host frames answers (Porthole's shell,
|
|
6
7
|
* `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
|
|
7
8
|
* (`nestedAncestors`, `NESTED_FILE_HEADERS`). `/server` serves both for a config with `nested`;
|
|
8
9
|
* a host serving its own content origin (its own Worker) answers the same.
|
|
10
|
+
*
|
|
11
|
+
* All of it is served on the shell's own label (P114, `nestedLabelOf`), never on the scope's: every
|
|
12
|
+
* other display of the scope runs agent-made content on the scope's origin with
|
|
13
|
+
* `allow-same-origin`, which would be same-origin with the shell, its realm and the page's sealed
|
|
14
|
+
* address.
|
|
9
15
|
*/
|
|
16
|
+
/**
|
|
17
|
+
* The start of every label Porthole serves for itself on a content domain (P114): no host's naming
|
|
18
|
+
* may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
|
|
19
|
+
*/
|
|
20
|
+
export const PORTHOLE_LABEL_PREFIX = "porthole-";
|
|
21
|
+
const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
|
|
22
|
+
/**
|
|
23
|
+
* The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
|
|
24
|
+
* base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
|
|
25
|
+
* content label is ever one (a keyed label has no hyphen, a host's is refused the prefix), so
|
|
26
|
+
* nothing but a nested page's shell, its opaque page, that page's files and Porthole's status pages
|
|
27
|
+
* is ever served on it: no other display's content runs there with `allow-same-origin`. Not a
|
|
28
|
+
* secret: anyone who knows the scope's label may work it out. A content Worker of a host's own
|
|
29
|
+
* serves its nested pages on it too.
|
|
30
|
+
*/
|
|
31
|
+
export function nestedLabelOf(label) {
|
|
32
|
+
return `${PORTHOLE_LABEL_PREFIX}${base32(sha256(utf8(`porthole/nested/${label}`)).subarray(0, 15))}`;
|
|
33
|
+
}
|
|
34
|
+
/** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
|
|
35
|
+
export const isNestedLabel = (label) => NESTED_LABEL.test(label);
|
|
10
36
|
/** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
|
|
11
37
|
export const NESTED_FILES_PREFIX = "/__porthole/f/";
|
|
12
38
|
const base64 = (bytes) => btoa(String.fromCharCode(...bytes));
|
|
@@ -54,8 +80,8 @@ export function nestedShellResponse(compiled, options) {
|
|
|
54
80
|
});
|
|
55
81
|
}
|
|
56
82
|
/**
|
|
57
|
-
* Who may frame a nested page and its files' answers: its shell (the
|
|
58
|
-
* it, the host origins (`frame-ancestors` names every ancestor).
|
|
83
|
+
* Who may frame a nested page and its files' answers: its shell (the shell's own origin, P114) and,
|
|
84
|
+
* above it, the host origins (`frame-ancestors` names every ancestor).
|
|
59
85
|
*/
|
|
60
86
|
export const nestedAncestors = (origin, frameAncestors) => `${origin} ${frameAncestors}`;
|
|
61
87
|
/**
|