@botiverse/porthole 0.3.0 → 0.3.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/README.md +3 -2
- package/dist/check/check.d.ts +18 -1
- package/dist/check/check.js +84 -6
- package/dist/check/drivers.d.ts +25 -6
- package/dist/check/drivers.js +99 -28
- package/dist/check/index.d.ts +2 -2
- package/dist/check/index.js +1 -1
- package/dist/check/instrument.d.ts +71 -0
- package/dist/check/instrument.js +84 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.d.ts +2 -40
- package/dist/check/page.js +63 -43
- package/dist/conformance/host-kit.d.ts +18 -5
- package/dist/conformance/host-kit.js +38 -21
- package/dist/conformance/index.d.ts +1 -1
- package/dist/conformance/reporter.d.ts +14 -0
- package/dist/conformance/reporter.js +28 -0
- package/dist/host/client.d.ts +33 -15
- package/dist/host/client.js +39 -24
- package/dist/node/index.d.ts +6 -2
- package/dist/node/index.js +53 -8
- package/dist/react/frame.d.ts +13 -5
- package/dist/react/frame.js +67 -27
- package/dist/react/index.d.ts +1 -1
- package/dist/react/view.js +6 -1
- package/dist/server/host.d.ts +5 -3
- package/dist/server/host.js +41 -12
- package/docs/ADOPTING.md +108 -25
- package/docs/DECISIONS.md +134 -0
- package/docs/DESIGN.md +36 -12
- package/examples/app.mjs +23 -17
- package/examples/conformance/playwright.config.mjs +2 -1
- package/examples/conformance/porthole.spec.mjs +2 -1
- package/examples/displays.mjs +2 -0
- package/examples/node/server.mjs +16 -34
- package/examples/workers/worker.mjs +19 -7
- package/package.json +5 -1
- package/src/check/check.ts +116 -8
- package/src/check/drivers.ts +137 -39
- package/src/check/index.ts +8 -1
- package/src/check/instrument.ts +138 -0
- package/src/check/page.ts +94 -68
- package/src/conformance/host-kit.ts +65 -19
- package/src/conformance/index.ts +1 -0
- package/src/conformance/reporter.ts +38 -0
- package/src/host/client.ts +65 -34
- package/src/node/index.ts +56 -10
- package/src/react/frame.tsx +89 -33
- package/src/react/index.ts +1 -0
- package/src/react/view.tsx +6 -1
- package/src/server/host.ts +53 -15
package/src/host/client.ts
CHANGED
|
@@ -44,36 +44,45 @@ export interface PortholeClientOptions<N extends string> {
|
|
|
44
44
|
readonly fetch?: typeof fetch;
|
|
45
45
|
}
|
|
46
46
|
|
|
47
|
+
/**
|
|
48
|
+
* Every function is declared `this: void` (P074): each may be passed bare
|
|
49
|
+
* (`useSyncExternalStore(porthole.subscribe, porthole.meta)`), and none reads `this`.
|
|
50
|
+
*/
|
|
47
51
|
export interface PortholeClient<N extends string = string> extends InstanceLocator {
|
|
48
52
|
readonly displays: Displays<N>;
|
|
53
|
+
/** Locates an instance's frame through `POST <base>/frames` (`InstanceLocator`). */
|
|
54
|
+
locate(this: void, instance: InstanceRef, signal?: AbortSignal): Promise<FrameLocation>;
|
|
49
55
|
/** The meta as last fetched, or null before it is known. */
|
|
50
|
-
meta(): ContentClientMeta | null;
|
|
56
|
+
meta(this: void): ContentClientMeta | null;
|
|
51
57
|
/** Called when the meta changes (frames served or not). */
|
|
52
|
-
subscribe(listener: () => void): () => void;
|
|
58
|
+
subscribe(this: void, listener: () => void): () => void;
|
|
53
59
|
/** Fetches the meta again. */
|
|
54
|
-
refresh(): Promise<ContentClientMeta | null>;
|
|
60
|
+
refresh(this: void): Promise<ContentClientMeta | null>;
|
|
55
61
|
/**
|
|
56
62
|
* The config a kind shows under now: served while frames are served, else opaque (a url kind:
|
|
57
63
|
* null). Null until the meta is known, so a frame never starts opaque and then restarts served.
|
|
58
64
|
*/
|
|
59
|
-
config(kind: N): PortholeConfig | null;
|
|
65
|
+
config(this: void, kind: N): PortholeConfig | null;
|
|
60
66
|
/** The same, for an instance's kind. */
|
|
61
|
-
configFor(instance: InstanceRef): PortholeConfig | null;
|
|
67
|
+
configFor(this: void, instance: InstanceRef): PortholeConfig | null;
|
|
62
68
|
/** An instance's clean address (`entry.pathOf` on the server), or null. */
|
|
63
|
-
link(instance: InstanceRef): Promise<string | null>;
|
|
69
|
+
link(this: void, instance: InstanceRef): Promise<string | null>;
|
|
64
70
|
/** The clean address if already known (from locating the instance), for rendering. */
|
|
65
|
-
knownLink(instance: InstanceRef): string | null;
|
|
71
|
+
knownLink(this: void, instance: InstanceRef): string | null;
|
|
66
72
|
/**
|
|
67
73
|
* Opens an instance's clean address in a new tab: call it in the click (the tab opens at once,
|
|
68
74
|
* then goes to the address).
|
|
69
75
|
*/
|
|
70
|
-
openInTab(instance: InstanceRef): void;
|
|
76
|
+
openInTab(this: void, instance: InstanceRef): void;
|
|
71
77
|
/** Hands the signed-in viewer to the authorize route (`entry.handoff`); true if it took. */
|
|
72
|
-
handoff(): Promise<boolean>;
|
|
73
|
-
/**
|
|
74
|
-
|
|
78
|
+
handoff(this: void): Promise<boolean>;
|
|
79
|
+
/**
|
|
80
|
+
* `next` if it is this server's authorize route (after a sign-in), or with `{ app: true }` any
|
|
81
|
+
* address on the app's own origin; else null (`entryTarget`).
|
|
82
|
+
*/
|
|
83
|
+
entryTarget(this: void, next: unknown, options?: { readonly app?: boolean }): string | null;
|
|
75
84
|
/** Stops refreshing the handoff. */
|
|
76
|
-
close(): void;
|
|
85
|
+
close(this: void): void;
|
|
77
86
|
}
|
|
78
87
|
|
|
79
88
|
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
@@ -81,9 +90,18 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
|
81
90
|
|
|
82
91
|
/**
|
|
83
92
|
* Whether a sign-in's `next` is the app's authorize route (P072): the open-redirect guard a
|
|
84
|
-
* single-page app runs before going on to it. Null for anything else
|
|
93
|
+
* single-page app runs before going on to it. Null for anything else; with `{ app: true }`, also
|
|
94
|
+
* any path or address on the app's own origin (P074), so one check serves a sign-in that comes
|
|
95
|
+
* back to redirect entry or to the app's own pages. Never another origin.
|
|
96
|
+
*
|
|
97
|
+
* The authorize route is `<first app origin><prefix>/authorize` unless the server names another
|
|
98
|
+
* (`entry.authorizeUrl`): `https://app.example.com/porthole/authorize` by default.
|
|
85
99
|
*/
|
|
86
|
-
export function entryTarget(
|
|
100
|
+
export function entryTarget(
|
|
101
|
+
next: unknown,
|
|
102
|
+
authorizeUrl: string,
|
|
103
|
+
options: { readonly app?: boolean } = {},
|
|
104
|
+
): string | null {
|
|
87
105
|
if (typeof next !== "string" || next.length > 8_192) {
|
|
88
106
|
return null;
|
|
89
107
|
}
|
|
@@ -95,10 +113,19 @@ export function entryTarget(next: unknown, authorizeUrl: string): string | null
|
|
|
95
113
|
} catch {
|
|
96
114
|
return null;
|
|
97
115
|
}
|
|
98
|
-
|
|
116
|
+
if (
|
|
117
|
+
target.origin === route.origin &&
|
|
99
118
|
target.pathname === route.pathname &&
|
|
100
119
|
target.hash === "" &&
|
|
101
120
|
target.searchParams.has("state")
|
|
121
|
+
) {
|
|
122
|
+
return target.href;
|
|
123
|
+
}
|
|
124
|
+
// An app path: one leading slash, no backslash (`//evil.example` and `/\evil.example` are
|
|
125
|
+
// other sites to a browser), and still the app's origin once resolved.
|
|
126
|
+
const path = /^\/(?![/\\])/u.test(next) && !next.includes("\\");
|
|
127
|
+
const absolute = /^https?:\/\//iu.test(next);
|
|
128
|
+
return options.app === true && (path || absolute) && target.origin === route.origin
|
|
102
129
|
? target.href
|
|
103
130
|
: null;
|
|
104
131
|
}
|
|
@@ -245,30 +272,34 @@ export function portholeClient<N extends string>(
|
|
|
245
272
|
document.addEventListener("visibilitychange", fresh);
|
|
246
273
|
}
|
|
247
274
|
|
|
275
|
+
const link = async (instance: InstanceRef): Promise<string | null> => {
|
|
276
|
+
const key = keyOf(instance);
|
|
277
|
+
if (!links.has(key)) {
|
|
278
|
+
try {
|
|
279
|
+
await issue(instance);
|
|
280
|
+
} catch {
|
|
281
|
+
return null;
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
return links.get(key) ?? null;
|
|
285
|
+
};
|
|
286
|
+
|
|
248
287
|
return {
|
|
249
288
|
displays: options.displays,
|
|
250
289
|
meta: () => meta,
|
|
251
|
-
subscribe(listener) {
|
|
290
|
+
subscribe: (listener) => {
|
|
252
291
|
listeners.add(listener);
|
|
253
|
-
return () =>
|
|
292
|
+
return () => {
|
|
293
|
+
listeners.delete(listener);
|
|
294
|
+
};
|
|
254
295
|
},
|
|
255
296
|
refresh,
|
|
256
297
|
config: (kind) => configOf(kind),
|
|
257
298
|
configFor: (instance) => configOf(options.displays.kindOf(instance)),
|
|
258
299
|
locate: issue,
|
|
259
|
-
|
|
260
|
-
const key = keyOf(instance);
|
|
261
|
-
if (!links.has(key)) {
|
|
262
|
-
try {
|
|
263
|
-
await issue(instance);
|
|
264
|
-
} catch {
|
|
265
|
-
return null;
|
|
266
|
-
}
|
|
267
|
-
}
|
|
268
|
-
return links.get(key) ?? null;
|
|
269
|
-
},
|
|
300
|
+
link,
|
|
270
301
|
knownLink: (instance) => links.get(keyOf(instance)) ?? null,
|
|
271
|
-
openInTab(instance) {
|
|
302
|
+
openInTab: (instance) => {
|
|
272
303
|
// Opened inside the click (a popup blocker lets it), then sent to the address.
|
|
273
304
|
const tab = typeof window === "undefined" ? null : window.open("about:blank", "_blank");
|
|
274
305
|
if (tab === null) {
|
|
@@ -276,17 +307,17 @@ export function portholeClient<N extends string>(
|
|
|
276
307
|
}
|
|
277
308
|
tab.opener = null;
|
|
278
309
|
void (async () => {
|
|
279
|
-
const
|
|
280
|
-
if (
|
|
310
|
+
const found = await link(instance);
|
|
311
|
+
if (found === null) {
|
|
281
312
|
tab.close();
|
|
282
313
|
} else {
|
|
283
|
-
tab.location.href =
|
|
314
|
+
tab.location.href = found;
|
|
284
315
|
}
|
|
285
316
|
})();
|
|
286
317
|
},
|
|
287
318
|
handoff,
|
|
288
|
-
entryTarget: (next) => entryTarget(next, url("/authorize")),
|
|
289
|
-
close() {
|
|
319
|
+
entryTarget: (next, given) => entryTarget(next, url("/authorize"), given),
|
|
320
|
+
close: () => {
|
|
290
321
|
if (watching) {
|
|
291
322
|
window.removeEventListener("focus", fresh);
|
|
292
323
|
document.removeEventListener("visibilitychange", fresh);
|
package/src/node/index.ts
CHANGED
|
@@ -292,8 +292,12 @@ export function nodeProbe(): HealthProbe {
|
|
|
292
292
|
}
|
|
293
293
|
|
|
294
294
|
export interface NodeServerOptions {
|
|
295
|
-
/**
|
|
296
|
-
|
|
295
|
+
/**
|
|
296
|
+
* The content host, or a function giving it when it exists: a host made after the server listens
|
|
297
|
+
* (its content domain names the port `listen(0)` chose, P074). Until it gives one, every request
|
|
298
|
+
* is the app's; the health gate starts when it first does.
|
|
299
|
+
*/
|
|
300
|
+
readonly content: ContentHost<unknown> | (() => ContentHost<unknown> | null);
|
|
297
301
|
/**
|
|
298
302
|
* The app, fetch-style (Hono's `app.fetch`, or the app's own handler): every request that
|
|
299
303
|
* isn't the content domain's. Or `request`, a Node listener (Express).
|
|
@@ -335,14 +339,56 @@ export function nodeServer(options: NodeServerOptions): Server {
|
|
|
335
339
|
if (request === undefined) {
|
|
336
340
|
throw new TypeError("nodeServer needs the app: app (fetch-style) or request (a Node listener)");
|
|
337
341
|
}
|
|
338
|
-
const
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
+
const adapters = new WeakMap<ContentHost<unknown>, NodeHost>();
|
|
343
|
+
const started = new WeakSet<ContentHost<unknown>>();
|
|
344
|
+
let listening = false;
|
|
345
|
+
const given = options.content;
|
|
346
|
+
/** The host now (made once, adapted once), started once the server listens. */
|
|
347
|
+
const current = (): NodeHost | null => {
|
|
348
|
+
const host = typeof given === "function" ? given() : given;
|
|
349
|
+
if (host === null) {
|
|
350
|
+
return null;
|
|
351
|
+
}
|
|
352
|
+
let adapter = adapters.get(host);
|
|
353
|
+
if (adapter === undefined) {
|
|
354
|
+
adapter = nodeHost(host, {
|
|
355
|
+
request,
|
|
356
|
+
...(options.upgrade === undefined ? {} : { upgrade: options.upgrade }),
|
|
357
|
+
...(options.appSocket === undefined ? {} : { appSocket: options.appSocket }),
|
|
358
|
+
});
|
|
359
|
+
adapters.set(host, adapter);
|
|
360
|
+
}
|
|
361
|
+
if (listening && !started.has(host)) {
|
|
362
|
+
started.add(host);
|
|
363
|
+
host.start();
|
|
364
|
+
}
|
|
365
|
+
return adapter;
|
|
366
|
+
};
|
|
367
|
+
const server = createHttpServer((incoming, response) => {
|
|
368
|
+
const adapter = current();
|
|
369
|
+
if (adapter === null) {
|
|
370
|
+
request(incoming, response);
|
|
371
|
+
} else {
|
|
372
|
+
adapter.request(incoming, response);
|
|
373
|
+
}
|
|
374
|
+
});
|
|
375
|
+
server.on("upgrade", (incoming: IncomingMessage, socket: Duplex, head: Buffer) => {
|
|
376
|
+
const adapter = current();
|
|
377
|
+
if (adapter !== null) {
|
|
378
|
+
adapter.upgrade(incoming, socket, head);
|
|
379
|
+
} else if (options.upgrade !== undefined) {
|
|
380
|
+
options.upgrade(incoming, socket, head);
|
|
381
|
+
} else {
|
|
382
|
+
refuseSocket(socket);
|
|
383
|
+
}
|
|
384
|
+
});
|
|
385
|
+
server.on("listening", () => {
|
|
386
|
+
listening = true;
|
|
387
|
+
current();
|
|
388
|
+
});
|
|
389
|
+
server.on("close", () => {
|
|
390
|
+
const host = typeof given === "function" ? given() : given;
|
|
391
|
+
host?.close();
|
|
342
392
|
});
|
|
343
|
-
const server = createHttpServer(porthole.request);
|
|
344
|
-
server.on("upgrade", porthole.upgrade);
|
|
345
|
-
server.on("listening", () => options.content.start());
|
|
346
|
-
server.on("close", () => options.content.close());
|
|
347
393
|
return server;
|
|
348
394
|
}
|
package/src/react/frame.tsx
CHANGED
|
@@ -110,12 +110,11 @@ export interface PortholeProviderProps {
|
|
|
110
110
|
/**
|
|
111
111
|
* Draws the confirmation in the app's own dialog, for the request at the head of the queue:
|
|
112
112
|
* Porthole keeps the queue (one question at a time), runs `accept` inside the click, and counts
|
|
113
|
-
* declines.
|
|
113
|
+
* declines. `redirect`: the person took it elsewhere (edited a prompt first, P074): the call
|
|
114
|
+
* doesn't go, and it neither counts toward muting the display nor resets the count. Omitted:
|
|
115
|
+
* Porthole's `ConfirmDialog`. (`confirm` replaces the whole mechanism.)
|
|
114
116
|
*/
|
|
115
|
-
readonly renderConfirm?: (
|
|
116
|
-
request: ConfirmRequest,
|
|
117
|
-
answer: { readonly accept: () => void; readonly decline: () => void },
|
|
118
|
-
) => ReactNode;
|
|
117
|
+
readonly renderConfirm?: (request: ConfirmRequest, answer: ConfirmActions) => ReactNode;
|
|
119
118
|
/**
|
|
120
119
|
* Who confirms gated calls for every frame below. Omitted: the default dialog (`ConfirmDialog`).
|
|
121
120
|
* Pass your own function to replace it.
|
|
@@ -138,6 +137,16 @@ export interface PortholeProviderProps {
|
|
|
138
137
|
readonly children?: ReactNode;
|
|
139
138
|
}
|
|
140
139
|
|
|
140
|
+
/** What an app's own confirmation dialog answers with (`renderConfirm`). */
|
|
141
|
+
export interface ConfirmActions {
|
|
142
|
+
/** Yes: the call goes, run inside this click. */
|
|
143
|
+
readonly accept: () => void;
|
|
144
|
+
/** No: the call doesn't go, and it counts toward muting the display. */
|
|
145
|
+
readonly decline: () => void;
|
|
146
|
+
/** Elsewhere (the person edits the prompt first): the call doesn't go, and doesn't count. */
|
|
147
|
+
readonly redirect: () => void;
|
|
148
|
+
}
|
|
149
|
+
|
|
141
150
|
/** The page's own nonce: `<meta name="csp-nonce" content>`, else the first `script[nonce]`'s. */
|
|
142
151
|
function pageNonce(): string | undefined {
|
|
143
152
|
if (typeof document === "undefined") {
|
|
@@ -292,6 +301,10 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
|
|
|
292
301
|
current.resolve("declined");
|
|
293
302
|
setQueue((waiting) => waiting.slice(1));
|
|
294
303
|
},
|
|
304
|
+
redirect: () => {
|
|
305
|
+
current.resolve("redirected");
|
|
306
|
+
setQueue((waiting) => waiting.slice(1));
|
|
307
|
+
},
|
|
295
308
|
})
|
|
296
309
|
: null}
|
|
297
310
|
{props.confirm === undefined && props.renderConfirm === undefined ? (
|
|
@@ -477,12 +490,15 @@ function rememberedHeight(
|
|
|
477
490
|
|
|
478
491
|
export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
479
492
|
const page = useContext(Page);
|
|
493
|
+
// The provider's registry and heights: stable, unlike the context value, which a scheme flip
|
|
494
|
+
// or a new themeKey renews (an effect keyed on it would let the frame go and make it again, #9).
|
|
495
|
+
const { live, heights } = page;
|
|
480
496
|
const key = useId();
|
|
481
497
|
const box = useRef<HTMLDivElement>(null);
|
|
482
498
|
const max = props.config.limits.maxLiveFrames;
|
|
483
499
|
const state = useSyncExternalStore(
|
|
484
|
-
(listener) =>
|
|
485
|
-
() =>
|
|
500
|
+
(listener) => live.subscribe(listener),
|
|
501
|
+
() => live.state(key),
|
|
486
502
|
(): FrameState => "waiting",
|
|
487
503
|
);
|
|
488
504
|
const { eager } = props;
|
|
@@ -493,9 +509,9 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
|
493
509
|
return;
|
|
494
510
|
}
|
|
495
511
|
if (eager === true || typeof IntersectionObserver !== "function") {
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
return () =>
|
|
512
|
+
live.near(key, true);
|
|
513
|
+
live.admit(key, max);
|
|
514
|
+
return () => live.release(key);
|
|
499
515
|
}
|
|
500
516
|
const observer = new IntersectionObserver(
|
|
501
517
|
(entries) => {
|
|
@@ -503,9 +519,9 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
|
503
519
|
if (entry === undefined) {
|
|
504
520
|
return;
|
|
505
521
|
}
|
|
506
|
-
|
|
522
|
+
live.near(key, entry.isIntersecting);
|
|
507
523
|
if (entry.isIntersecting) {
|
|
508
|
-
|
|
524
|
+
live.admit(key, max);
|
|
509
525
|
}
|
|
510
526
|
},
|
|
511
527
|
{ rootMargin: NEAR_SCREEN },
|
|
@@ -513,22 +529,22 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
|
513
529
|
observer.observe(element);
|
|
514
530
|
return () => {
|
|
515
531
|
observer.disconnect();
|
|
516
|
-
|
|
532
|
+
live.release(key);
|
|
517
533
|
};
|
|
518
|
-
}, [
|
|
534
|
+
}, [live, key, max, eager]);
|
|
519
535
|
|
|
520
|
-
const height = rememberedHeight(
|
|
536
|
+
const height = rememberedHeight(heights, props.displayId, props.aliases);
|
|
521
537
|
// A display renamed while it runs (its id settled) keeps its height under its new id.
|
|
522
538
|
const previousId = useRef(props.displayId);
|
|
523
539
|
useLayoutEffect(() => {
|
|
524
540
|
const before = previousId.current;
|
|
525
541
|
previousId.current = props.displayId;
|
|
526
|
-
const kept =
|
|
527
|
-
if (before !== props.displayId && kept !== undefined && !
|
|
528
|
-
|
|
542
|
+
const kept = heights.get(before);
|
|
543
|
+
if (before !== props.displayId && kept !== undefined && !heights.has(props.displayId)) {
|
|
544
|
+
heights.set(props.displayId, kept);
|
|
529
545
|
}
|
|
530
|
-
}, [
|
|
531
|
-
const run = () =>
|
|
546
|
+
}, [heights, props.displayId]);
|
|
547
|
+
const run = () => live.admit(key, max);
|
|
532
548
|
const placeholder = props.renderPlaceholder ?? DefaultPlaceholder;
|
|
533
549
|
return (
|
|
534
550
|
<div
|
|
@@ -593,6 +609,18 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
593
609
|
|
|
594
610
|
// The latest props, read when the display calls back (never during render).
|
|
595
611
|
const latest = useEffectEvent(() => frame);
|
|
612
|
+
// The provider's scheme and theme, read when used: a flip or a new themeKey (a new context
|
|
613
|
+
// value) re-themes the running display, never makes it again (#9, P074). What a display is
|
|
614
|
+
// made with comes from the provider's stable parts below.
|
|
615
|
+
const latestPage = useEffectEvent(() => page);
|
|
616
|
+
const {
|
|
617
|
+
handlers: pageHandlers,
|
|
618
|
+
copyText: pageCopyText,
|
|
619
|
+
confirm: pageConfirm,
|
|
620
|
+
hostInfo,
|
|
621
|
+
locate,
|
|
622
|
+
nonce,
|
|
623
|
+
} = page;
|
|
596
624
|
const notify = useEffectEvent(
|
|
597
625
|
<E extends keyof DisplayEvents>(event: E, detail: DisplayEvents[E]): void => {
|
|
598
626
|
switch (event) {
|
|
@@ -662,23 +690,23 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
662
690
|
const declared = new Set(Object.keys(config.capabilities));
|
|
663
691
|
for (const name of new Set([
|
|
664
692
|
...Object.keys(first.handlers ?? {}),
|
|
665
|
-
...Object.keys(
|
|
693
|
+
...Object.keys(pageHandlers?.() ?? {}).filter((each) => declared.has(each)),
|
|
666
694
|
])) {
|
|
667
695
|
handlers[name] = (args, context) =>
|
|
668
696
|
(
|
|
669
697
|
(latest().handlers as Record<string, AnyHandler | undefined> | undefined)?.[name] ??
|
|
670
|
-
(
|
|
698
|
+
(pageHandlers?.() as Record<string, AnyHandler | undefined> | undefined)?.[name]
|
|
671
699
|
)?.(args, named(context));
|
|
672
700
|
}
|
|
673
701
|
// Copy buttons without a handler of the host's: the provider's, which shows a toast.
|
|
674
702
|
if (config.capabilities.copyText !== undefined && handlers.copyText === undefined) {
|
|
675
|
-
const fallback =
|
|
703
|
+
const fallback = pageCopyText;
|
|
676
704
|
if (fallback !== undefined) {
|
|
677
705
|
handlers.copyText = (args, context) =>
|
|
678
706
|
fallback(args as { readonly text: string }, named(context));
|
|
679
707
|
}
|
|
680
708
|
}
|
|
681
|
-
const asks = first.confirm !== undefined ||
|
|
709
|
+
const asks = first.confirm !== undefined || pageConfirm !== undefined;
|
|
682
710
|
let display: DisplayHandle;
|
|
683
711
|
try {
|
|
684
712
|
display = createHost(config, {
|
|
@@ -686,20 +714,20 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
686
714
|
...(asks
|
|
687
715
|
? {
|
|
688
716
|
confirm: (request: ConfirmRequest, proceed: Proceed) =>
|
|
689
|
-
(latest().confirm ??
|
|
717
|
+
(latest().confirm ?? pageConfirm ?? (() => Promise.resolve(false)))(
|
|
690
718
|
{ ...request, display: { id: latest().displayId, title: latest().title } },
|
|
691
719
|
proceed,
|
|
692
720
|
),
|
|
693
721
|
}
|
|
694
722
|
: {}),
|
|
695
|
-
theme: (each) => (latest().theme ??
|
|
696
|
-
...(
|
|
697
|
-
...(
|
|
698
|
-
...(
|
|
723
|
+
theme: (each) => (latest().theme ?? latestPage().theme)?.(each) ?? {},
|
|
724
|
+
...(hostInfo === undefined ? {} : { hostInfo }),
|
|
725
|
+
...(locate === undefined ? {} : { locator: { locate } }),
|
|
726
|
+
...(nonce === undefined ? {} : { nonce }),
|
|
699
727
|
}).mount(container, {
|
|
700
728
|
displayId: first.displayId,
|
|
701
729
|
title: first.title,
|
|
702
|
-
scheme: first.scheme ??
|
|
730
|
+
scheme: first.scheme ?? latestPage().scheme ?? "light",
|
|
703
731
|
initialHeightPx: startHeight,
|
|
704
732
|
...(view === undefined ? {} : { document: view }),
|
|
705
733
|
...(instance === undefined ? {} : { instance }),
|
|
@@ -735,9 +763,22 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
735
763
|
display.destroy();
|
|
736
764
|
handle.current = null;
|
|
737
765
|
};
|
|
738
|
-
// A new display only for a new config, document
|
|
739
|
-
//
|
|
740
|
-
|
|
766
|
+
// A new display only for a new config, document or instance, or what the provider makes
|
|
767
|
+
// displays with (its nonce, hostInfo by value, whether it locates or confirms; generation, by
|
|
768
|
+
// key). Content, scheme, theme, handlers, id and title are fed to the running one.
|
|
769
|
+
}, [
|
|
770
|
+
config,
|
|
771
|
+
view,
|
|
772
|
+
instance,
|
|
773
|
+
startHeight,
|
|
774
|
+
fills,
|
|
775
|
+
pageHandlers,
|
|
776
|
+
pageCopyText,
|
|
777
|
+
pageConfirm,
|
|
778
|
+
hostInfo,
|
|
779
|
+
locate,
|
|
780
|
+
nonce,
|
|
781
|
+
]);
|
|
741
782
|
|
|
742
783
|
useEffect(() => {
|
|
743
784
|
if (content !== undefined) {
|
|
@@ -803,6 +844,21 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
803
844
|
handle.current?.refreshTheme();
|
|
804
845
|
}
|
|
805
846
|
}, [themeKey, mountThemeKey]);
|
|
847
|
+
// A new theme function (tokens a host passes inline): its values reach the running display
|
|
848
|
+
// where they changed for the scheme it shows (a flip re-reads them itself), P074.
|
|
849
|
+
const themeOf = frame.theme ?? page.theme;
|
|
850
|
+
const themed = useRef<string | null>(null);
|
|
851
|
+
useEffect(() => {
|
|
852
|
+
if (themeOf === undefined) {
|
|
853
|
+
return;
|
|
854
|
+
}
|
|
855
|
+
const now = `${scheme}\n${JSON.stringify(themeOf(scheme))}`;
|
|
856
|
+
const before = themed.current;
|
|
857
|
+
themed.current = now;
|
|
858
|
+
if (before !== null && before !== now && before.startsWith(`${scheme}\n`)) {
|
|
859
|
+
handle.current?.refreshTheme();
|
|
860
|
+
}
|
|
861
|
+
}, [themeOf, scheme]);
|
|
806
862
|
|
|
807
863
|
return (
|
|
808
864
|
<div
|
package/src/react/index.ts
CHANGED
package/src/react/view.tsx
CHANGED
|
@@ -59,11 +59,16 @@ function useClient(): PortholeClient {
|
|
|
59
59
|
}
|
|
60
60
|
|
|
61
61
|
/** The client's meta, as a React value (re-renders when frames start or stop being served). */
|
|
62
|
+
/**
|
|
63
|
+
* The client's meta. On the server too (P074): a client made with the meta it will start with
|
|
64
|
+
* (`portholeClient({ meta })`) renders the frame's placeholder or the fallback there, and the
|
|
65
|
+
* page hydrates from the same.
|
|
66
|
+
*/
|
|
62
67
|
function useMeta(client: PortholeClient) {
|
|
63
68
|
return useSyncExternalStore(
|
|
64
69
|
(listener) => client.subscribe(listener),
|
|
65
70
|
() => client.meta(),
|
|
66
|
-
() =>
|
|
71
|
+
() => client.meta(),
|
|
67
72
|
);
|
|
68
73
|
}
|
|
69
74
|
|
package/src/server/host.ts
CHANGED
|
@@ -201,7 +201,8 @@ export interface EntryOptions<V> {
|
|
|
201
201
|
request: Request,
|
|
202
202
|
) => Awaitable<InstanceRef | null | undefined>;
|
|
203
203
|
/**
|
|
204
|
-
* The app's own sign-in, which comes back to `returnTo` (the authorize URL
|
|
204
|
+
* The app's own sign-in, which comes back to `returnTo` (the authorize URL, as `authorizeUrl`
|
|
205
|
+
* names the app, with the entry's state) once signed in.
|
|
205
206
|
* Only ever on a tab: in a frame, the person is asked to open a new tab instead. `entry` is the
|
|
206
207
|
* address being opened, decoded (P070).
|
|
207
208
|
*/
|
|
@@ -218,9 +219,10 @@ export interface EntryOptions<V> {
|
|
|
218
219
|
readonly spa?: { readonly route: string };
|
|
219
220
|
/**
|
|
220
221
|
* The clean path of an instance (the reverse of `at`), or null: `issue` then answers its clean
|
|
221
|
-
* address as `link` (P072), for "open in a new tab" and "copy link".
|
|
222
|
+
* address as `link` (P072), for "open in a new tab" and "copy link". It may look it up (a
|
|
223
|
+
* promise, P074); where it fails, the frame comes without a link.
|
|
222
224
|
*/
|
|
223
|
-
readonly pathOf?: (instance: InstanceRef) => string | null
|
|
225
|
+
readonly pathOf?: (instance: InstanceRef, request: Request) => Awaitable<string | null>;
|
|
224
226
|
/**
|
|
225
227
|
* A viewer handoff, for an app whose page authenticates with a token rather than a cookie
|
|
226
228
|
* (P072): `POST <prefix>/handoff`, made with the app's own credential, leaves a short-lived key
|
|
@@ -406,10 +408,19 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
406
408
|
if (options.configs === undefined && options.displays === undefined) {
|
|
407
409
|
throw new TypeError("createContentHost needs configs or displays");
|
|
408
410
|
}
|
|
409
|
-
|
|
411
|
+
// The secret as given (an unset environment variable: none), checked with the domain below.
|
|
412
|
+
const secret: Uint8Array | null =
|
|
413
|
+
typeof options.secret === "string"
|
|
414
|
+
? utf8(options.secret.trim())
|
|
415
|
+
: options.secret instanceof Uint8Array
|
|
416
|
+
? options.secret
|
|
417
|
+
: null;
|
|
410
418
|
const healthLabel = gate?.label ?? DEFAULT_HEALTH_LABEL;
|
|
411
419
|
// The id Porthole's health check answers with: keyed, so another deployment's answer fails.
|
|
412
|
-
const healthId =
|
|
420
|
+
const healthId =
|
|
421
|
+
secret === null || secret.byteLength < 32
|
|
422
|
+
? ""
|
|
423
|
+
: base64url(hmacSha256(secret, utf8("porthole/health"))).slice(0, 22);
|
|
413
424
|
const appReserved = reservedLabels(options.reserved);
|
|
414
425
|
|
|
415
426
|
let domain: ContentDomainInfo | null = null;
|
|
@@ -423,6 +434,17 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
423
434
|
? options.domain
|
|
424
435
|
: contentDomain(options.domain, { appOrigins: options.appOrigins });
|
|
425
436
|
if (domain !== null) {
|
|
437
|
+
// Said plainly where it's missing, as where it's short (P074).
|
|
438
|
+
if (secret === null) {
|
|
439
|
+
throw new TypeError(
|
|
440
|
+
"createContentHost needs a secret: at least 32 random bytes (set PORTHOLE_SECRET; npx porthole secret makes one)",
|
|
441
|
+
);
|
|
442
|
+
}
|
|
443
|
+
if (secret.byteLength < 32) {
|
|
444
|
+
throw new TypeError(
|
|
445
|
+
"The secret must be at least 32 random bytes (set PORTHOLE_SECRET; npx porthole secret makes one)",
|
|
446
|
+
);
|
|
447
|
+
}
|
|
426
448
|
if (options.entry !== undefined && options.name?.scopeOf === undefined) {
|
|
427
449
|
throw new TypeError(
|
|
428
450
|
"Redirect entry needs a naming that says which scope a label names (prefixedName)",
|
|
@@ -632,7 +654,9 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
632
654
|
|
|
633
655
|
// The viewer handoff (P072): a key Porthole signs, naming the app's viewer until a time, in a
|
|
634
656
|
// cookie only the prefix's routes get. Never the app's own credential.
|
|
635
|
-
|
|
657
|
+
// None where the secret can't sign (then nothing is served, and no handoff made or taken).
|
|
658
|
+
const handoffKey =
|
|
659
|
+
secret === null || secret.byteLength < 32 ? null : hmacSha256(secret, utf8("porthole/handoff"));
|
|
636
660
|
const secureApp = (options.appOrigins[0] ?? "").startsWith("https:");
|
|
637
661
|
const handoffName = secureApp ? "__Secure-porthole-handoff" : "porthole-handoff";
|
|
638
662
|
const handoffCookie = (value: string, maxAge: number): string =>
|
|
@@ -644,14 +668,14 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
644
668
|
`Max-Age=${maxAge}`,
|
|
645
669
|
...(secureApp ? ["Secure"] : []),
|
|
646
670
|
].join("; ");
|
|
647
|
-
const signHandoff = (id: string, until: number): string => {
|
|
671
|
+
const signHandoff = (key: Uint8Array, id: string, until: number): string => {
|
|
648
672
|
const payload = base64url(utf8(JSON.stringify({ h: 1, v: id, x: until })));
|
|
649
|
-
return `${payload}.${base64url(hmacSha256(
|
|
673
|
+
return `${payload}.${base64url(hmacSha256(key, utf8(payload)))}`;
|
|
650
674
|
};
|
|
651
675
|
/** The viewer a request's handoff cookie names, if it is good. */
|
|
652
676
|
const handedOver = async (request: Request): Promise<V | null> => {
|
|
653
677
|
const handoff = options.entry?.handoff;
|
|
654
|
-
if (handoff === undefined) {
|
|
678
|
+
if (handoff === undefined || handoffKey === null) {
|
|
655
679
|
return null;
|
|
656
680
|
}
|
|
657
681
|
for (const part of (request.headers.get("cookie") ?? "").split(";")) {
|
|
@@ -690,18 +714,29 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
690
714
|
}
|
|
691
715
|
return null;
|
|
692
716
|
};
|
|
717
|
+
/**
|
|
718
|
+
* Where the person comes back after signing in: the authorize route as the app is reached
|
|
719
|
+
* (`authorizeUrl`'s origin and path), with this request's query (its state). Never the request's
|
|
720
|
+
* own URL, whose origin behind a TLS edge or a dev proxy isn't the app's (P074).
|
|
721
|
+
*/
|
|
722
|
+
const returnOf = (request: Request): string => {
|
|
723
|
+
const back = new URL(authorizeUrl);
|
|
724
|
+
back.search = new URL(request.url).search;
|
|
725
|
+
return back.href;
|
|
726
|
+
};
|
|
693
727
|
/** The app's sign-in: its own `signIn`, or its single-page route with `next`. */
|
|
694
728
|
const signInWith = async (
|
|
695
729
|
entry: EntryOptions<V>,
|
|
696
730
|
request: Request,
|
|
697
731
|
context: EntryContext,
|
|
698
732
|
): Promise<Response> => {
|
|
733
|
+
const returnTo = returnOf(request);
|
|
699
734
|
if (entry.signIn !== undefined) {
|
|
700
|
-
return entry.signIn(
|
|
735
|
+
return entry.signIn(returnTo, request, context);
|
|
701
736
|
}
|
|
702
737
|
const route = entry.spa?.route ?? "/";
|
|
703
|
-
const to = new URL(route,
|
|
704
|
-
to.searchParams.set("next",
|
|
738
|
+
const to = new URL(route, new URL(authorizeUrl).origin);
|
|
739
|
+
to.searchParams.set("next", returnTo);
|
|
705
740
|
return new Response(null, {
|
|
706
741
|
status: 303,
|
|
707
742
|
headers: { location: to.href, "cache-control": "no-store", "referrer-policy": "no-referrer" },
|
|
@@ -807,10 +842,10 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
807
842
|
} catch (error) {
|
|
808
843
|
return refusal(409, "refused", error instanceof Error ? error.message : String(error));
|
|
809
844
|
}
|
|
810
|
-
// The clean address, where the app says the instance's path (P072).
|
|
811
|
-
const path = options.entry?.pathOf?.(instance) ?? null;
|
|
845
|
+
// The clean address, where the app says the instance's path (P072, P074).
|
|
812
846
|
let link: string | null = null;
|
|
813
847
|
try {
|
|
848
|
+
const path = (await options.entry?.pathOf?.(instance, request)) ?? null;
|
|
814
849
|
link = path === null ? null : server.urlOf(instance.scope, path);
|
|
815
850
|
} catch {
|
|
816
851
|
link = null;
|
|
@@ -910,7 +945,10 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
910
945
|
if (typeof id !== "string" || id.length === 0 || id.length > 512) {
|
|
911
946
|
return refusal(500, "failed", "entry.handoff.id gave no id (1 to 512 characters)");
|
|
912
947
|
}
|
|
913
|
-
|
|
948
|
+
if (handoffKey === null) {
|
|
949
|
+
return refusal(503, "unavailable", "The content domain isn't served");
|
|
950
|
+
}
|
|
951
|
+
const key = signHandoff(handoffKey, id, Date.now() + HANDOFF_SECONDS * 1_000);
|
|
914
952
|
return new Response(null, {
|
|
915
953
|
status: 204,
|
|
916
954
|
headers: {
|