@botiverse/porthole 0.2.4 → 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 +17 -11
- package/dist/check/check.d.ts +100 -0
- package/dist/check/check.js +247 -0
- package/dist/check/drivers.d.ts +43 -0
- package/dist/check/drivers.js +181 -0
- package/dist/check/index.d.ts +8 -0
- package/dist/check/index.js +8 -0
- package/dist/check/instrument.d.ts +71 -0
- package/dist/check/instrument.js +84 -0
- package/dist/check/lint.d.ts +21 -0
- package/dist/check/lint.js +131 -0
- package/dist/check/page-source.d.ts +2 -0
- package/dist/check/page-source.js +2 -0
- package/dist/check/page.d.ts +13 -0
- package/dist/check/page.js +170 -0
- package/dist/check/tools.d.ts +61 -0
- package/dist/check/tools.js +140 -0
- package/dist/conformance/host-kit.d.ts +26 -5
- package/dist/conformance/host-kit.js +46 -22
- 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/displays/displays.d.ts +61 -0
- package/dist/displays/displays.js +113 -0
- package/dist/host/client.d.ts +110 -0
- package/dist/host/client.js +274 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +6 -0
- package/dist/node/index.d.ts +26 -1
- package/dist/node/index.js +91 -1
- package/dist/react/frame.d.ts +79 -3
- package/dist/react/frame.js +183 -42
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +1 -0
- package/dist/react/view.d.ts +54 -0
- package/dist/react/view.js +151 -0
- package/dist/server/bootstrap.d.ts +27 -0
- package/dist/server/bootstrap.js +63 -0
- package/dist/server/host.d.ts +77 -8
- package/dist/server/host.js +268 -11
- package/dist/server/index.d.ts +4 -2
- package/dist/server/index.js +3 -1
- package/dist/server/pages.d.ts +19 -0
- package/dist/server/pages.js +8 -0
- package/dist/server/proxy.d.ts +24 -0
- package/dist/server/proxy.js +67 -0
- package/dist/server/server.js +14 -1
- package/dist/server/types.d.ts +8 -0
- package/docs/ADOPTING.md +278 -108
- package/docs/DECISIONS.md +280 -0
- package/docs/DESIGN.md +84 -2
- package/examples/app.mjs +82 -78
- package/examples/conformance/page.spec.mjs +23 -0
- package/examples/conformance/playwright.config.mjs +3 -2
- package/examples/conformance/porthole.spec.mjs +6 -3
- package/examples/displays.mjs +21 -0
- package/examples/mcp/server.mjs +121 -0
- package/examples/node/server.mjs +16 -34
- package/examples/workers/worker.mjs +19 -7
- package/package.json +13 -1
- package/src/check/check.ts +386 -0
- package/src/check/drivers.ts +242 -0
- package/src/check/index.ts +22 -0
- package/src/check/instrument.ts +138 -0
- package/src/check/lint.ts +238 -0
- package/src/check/page-source.ts +19 -0
- package/src/check/page.ts +230 -0
- package/src/check/tools.ts +206 -0
- package/src/conformance/host-kit.ts +82 -27
- package/src/conformance/index.ts +1 -0
- package/src/conformance/reporter.ts +38 -0
- package/src/displays/displays.ts +191 -0
- package/src/host/client.ts +395 -0
- package/src/index.ts +25 -0
- package/src/node/index.ts +112 -2
- package/src/react/frame.tsx +271 -57
- package/src/react/index.ts +9 -0
- package/src/react/view.tsx +237 -0
- package/src/server/bootstrap.ts +97 -0
- package/src/server/host.ts +372 -18
- package/src/server/index.ts +11 -1
- package/src/server/pages.ts +28 -0
- package/src/server/proxy.ts +86 -0
- package/src/server/server.ts +26 -2
- package/src/server/types.ts +5 -0
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import { createContentHost } from "./host.js";
|
|
2
|
+
/** Why the content host can't be made for some settings. */
|
|
3
|
+
class Unservable extends Error {
|
|
4
|
+
name = "ContentHostUnservable";
|
|
5
|
+
}
|
|
6
|
+
export function contentHostFor(build, options = {}) {
|
|
7
|
+
const made = new WeakMap();
|
|
8
|
+
const hostOf = (env) => {
|
|
9
|
+
let found = made.get(env);
|
|
10
|
+
if (found === undefined) {
|
|
11
|
+
try {
|
|
12
|
+
found = createContentHost(build(env));
|
|
13
|
+
}
|
|
14
|
+
catch (error) {
|
|
15
|
+
found = new Unservable(`the content domain can't be served: ${error instanceof Error ? error.message : String(error)}`);
|
|
16
|
+
(options.log ?? (() => { }))(found.message);
|
|
17
|
+
}
|
|
18
|
+
made.set(env, found);
|
|
19
|
+
}
|
|
20
|
+
if (found instanceof Unservable) {
|
|
21
|
+
throw found;
|
|
22
|
+
}
|
|
23
|
+
return found;
|
|
24
|
+
};
|
|
25
|
+
const unavailable = (error) => new Response(`Unavailable: ${error.message}.`, {
|
|
26
|
+
status: 503,
|
|
27
|
+
headers: {
|
|
28
|
+
"content-type": "text/plain; charset=utf-8",
|
|
29
|
+
"cache-control": "no-store",
|
|
30
|
+
"x-content-type-options": "nosniff",
|
|
31
|
+
"x-robots-tag": "noindex, nofollow",
|
|
32
|
+
},
|
|
33
|
+
});
|
|
34
|
+
return {
|
|
35
|
+
host: hostOf,
|
|
36
|
+
async fetch(request, env) {
|
|
37
|
+
let host;
|
|
38
|
+
try {
|
|
39
|
+
host = hostOf(env);
|
|
40
|
+
}
|
|
41
|
+
catch (error) {
|
|
42
|
+
if (error instanceof Unservable) {
|
|
43
|
+
return unavailable(error);
|
|
44
|
+
}
|
|
45
|
+
throw error;
|
|
46
|
+
}
|
|
47
|
+
return host.fetch(request);
|
|
48
|
+
},
|
|
49
|
+
async routes(request, env, viewerOf) {
|
|
50
|
+
let host;
|
|
51
|
+
try {
|
|
52
|
+
host = hostOf(env);
|
|
53
|
+
}
|
|
54
|
+
catch (error) {
|
|
55
|
+
if (error instanceof Unservable) {
|
|
56
|
+
return unavailable(error);
|
|
57
|
+
}
|
|
58
|
+
throw error;
|
|
59
|
+
}
|
|
60
|
+
return host.routes(viewerOf)(request);
|
|
61
|
+
},
|
|
62
|
+
};
|
|
63
|
+
}
|
package/dist/server/host.d.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
2
|
import type { InstanceRef } from "../isolation/types.ts";
|
|
3
|
+
import type { Displays } from "../displays/displays.ts";
|
|
4
|
+
import type { ContentClientMeta } from "../host/client.ts";
|
|
3
5
|
import { type ContentDomainInfo } from "./domain.ts";
|
|
4
6
|
import { type Naming } from "./naming.ts";
|
|
5
7
|
import type { Access, ArtifactStore, AuthorizeAnswer, AuthorizeRequest, Grant, PortholeServer, TicketStore, Upstream } from "./types.ts";
|
|
@@ -27,6 +29,11 @@ export interface HealthOptions {
|
|
|
27
29
|
* its clients whether frames are served pushes it from here.
|
|
28
30
|
*/
|
|
29
31
|
readonly onChange?: (view: ContentHealthView) => void;
|
|
32
|
+
/**
|
|
33
|
+
* Told when frames start or stop being served (P072): `meta().served` flipped. Deduplicated:
|
|
34
|
+
* once per flip, not per check.
|
|
35
|
+
*/
|
|
36
|
+
readonly onServedChange?: (served: boolean) => void;
|
|
30
37
|
}
|
|
31
38
|
/** Where content stands, for the app's own meta and logs. */
|
|
32
39
|
export interface ContentHealthView {
|
|
@@ -54,6 +61,13 @@ export interface ContentMeta {
|
|
|
54
61
|
readonly contentSource: string | null;
|
|
55
62
|
readonly health: ContentHealthView | null;
|
|
56
63
|
}
|
|
64
|
+
export type { ContentClientMeta } from "../host/client.ts";
|
|
65
|
+
/** A logger (pino, console, winston): the kit's events at their level (P072). */
|
|
66
|
+
export interface ContentLogger {
|
|
67
|
+
readonly info?: (message: string, event: ContentHostEvent) => void;
|
|
68
|
+
readonly warn?: (message: string, event: ContentHostEvent) => void;
|
|
69
|
+
readonly error?: (message: string, event: ContentHostEvent) => void;
|
|
70
|
+
}
|
|
57
71
|
type Awaitable<T> = T | Promise<T>;
|
|
58
72
|
export interface ContentHostOptions<V> {
|
|
59
73
|
/** `content.example.com`, `content.localhost:8790`; empty: content off. Or parsed settings. */
|
|
@@ -63,8 +77,18 @@ export interface ContentHostOptions<V> {
|
|
|
63
77
|
/** At least 32 random bytes (or a string of at least 32 bytes). */
|
|
64
78
|
readonly secret: Uint8Array | string;
|
|
65
79
|
readonly tickets?: TicketStore;
|
|
66
|
-
/**
|
|
67
|
-
|
|
80
|
+
/**
|
|
81
|
+
* The configs content is served under, given the content source (`https://*.<domain>`). Or
|
|
82
|
+
* `displays` (P072), which says it for every kind once.
|
|
83
|
+
*/
|
|
84
|
+
readonly configs?: Readonly<Record<string, PortholeConfig>> | ((source: string) => Readonly<Record<string, PortholeConfig>>);
|
|
85
|
+
/** The app's display kinds (`defineDisplays`): their served configs, in place of `configs`. */
|
|
86
|
+
readonly displays?: Displays;
|
|
87
|
+
/**
|
|
88
|
+
* Where `routes` answers on the app's origin (P072): `<prefix>/frames`, `/authorize`, `/meta`,
|
|
89
|
+
* `/handoff`. Default `/porthole`.
|
|
90
|
+
*/
|
|
91
|
+
readonly prefix?: string;
|
|
68
92
|
/**
|
|
69
93
|
* How a scope is named (`prefixedName("a-")`); default: keyed labels. Redirect entry needs one
|
|
70
94
|
* that says which scope a label names (`prefixedName` does).
|
|
@@ -104,7 +128,8 @@ export interface ContentHostOptions<V> {
|
|
|
104
128
|
readonly perMinute: number;
|
|
105
129
|
readonly key?: (request: Request, viewer: V | null) => string;
|
|
106
130
|
};
|
|
107
|
-
|
|
131
|
+
/** The kit's events: a function, or a logger (`{ info, warn, error }`). */
|
|
132
|
+
readonly log?: ((event: ContentHostEvent) => void) | ContentLogger;
|
|
108
133
|
/**
|
|
109
134
|
* Redirect entry (P068): clean addresses (`urlOf`) that open directly, in a new tab, on a
|
|
110
135
|
* reload, from a bookmark or a link someone with access was sent. Without a cookie, the content
|
|
@@ -114,8 +139,11 @@ export interface ContentHostOptions<V> {
|
|
|
114
139
|
readonly entry?: EntryOptions<V>;
|
|
115
140
|
}
|
|
116
141
|
export interface EntryOptions<V> {
|
|
117
|
-
/**
|
|
118
|
-
|
|
142
|
+
/**
|
|
143
|
+
* The app's authorize route (`ContentHost.authorize`), an absolute URL on an app origin.
|
|
144
|
+
* Default: `<first app origin><prefix>/authorize`, where `routes` answers it.
|
|
145
|
+
*/
|
|
146
|
+
readonly authorizeUrl?: string;
|
|
119
147
|
/**
|
|
120
148
|
* Policy 1 for a clean address: the instance a scope's path means, or null/undefined: nothing
|
|
121
149
|
* (404). The path is the address's pathname; its query rides along but never chooses the
|
|
@@ -126,11 +154,36 @@ export interface EntryOptions<V> {
|
|
|
126
154
|
*/
|
|
127
155
|
readonly at: (scope: string, path: string, viewer: V | null, request: Request) => Awaitable<InstanceRef | null | undefined>;
|
|
128
156
|
/**
|
|
129
|
-
* The app's own sign-in, which comes back to `returnTo` (the authorize URL
|
|
157
|
+
* The app's own sign-in, which comes back to `returnTo` (the authorize URL, as `authorizeUrl`
|
|
158
|
+
* names the app, with the entry's state) once signed in.
|
|
130
159
|
* Only ever on a tab: in a frame, the person is asked to open a new tab instead. `entry` is the
|
|
131
160
|
* address being opened, decoded (P070).
|
|
132
161
|
*/
|
|
133
|
-
readonly signIn
|
|
162
|
+
readonly signIn?: (returnTo: string, request: Request, entry: EntryContext) => Awaitable<Response>;
|
|
163
|
+
/**
|
|
164
|
+
* A single-page app's sign-in route (P072): the default `signIn` sends the person there with
|
|
165
|
+
* `?next=<authorize URL>`, and the app goes on to `next` once signed in (check it with
|
|
166
|
+
* `entryTarget`).
|
|
167
|
+
*/
|
|
168
|
+
readonly spa?: {
|
|
169
|
+
readonly route: string;
|
|
170
|
+
};
|
|
171
|
+
/**
|
|
172
|
+
* The clean path of an instance (the reverse of `at`), or null: `issue` then answers its clean
|
|
173
|
+
* address as `link` (P072), for "open in a new tab" and "copy link". It may look it up (a
|
|
174
|
+
* promise, P074); where it fails, the frame comes without a link.
|
|
175
|
+
*/
|
|
176
|
+
readonly pathOf?: (instance: InstanceRef, request: Request) => Awaitable<string | null>;
|
|
177
|
+
/**
|
|
178
|
+
* A viewer handoff, for an app whose page authenticates with a token rather than a cookie
|
|
179
|
+
* (P072): `POST <prefix>/handoff`, made with the app's own credential, leaves a short-lived key
|
|
180
|
+
* for its viewer in a cookie only the authorize route gets. `id` says who the viewer is (at
|
|
181
|
+
* most 512 characters); `viewer` turns it back into the app's viewer, or null.
|
|
182
|
+
*/
|
|
183
|
+
readonly handoff?: {
|
|
184
|
+
readonly id: (viewer: V) => string;
|
|
185
|
+
readonly viewer: (id: string, request: Request) => Awaitable<V | null>;
|
|
186
|
+
};
|
|
134
187
|
/**
|
|
135
188
|
* The app's refusal page on a tab (a frame gets Porthole's plain one), for the address in
|
|
136
189
|
* `entry`. Nothing (null, undefined): Porthole's own (P070).
|
|
@@ -177,6 +230,23 @@ export interface ContentHost<V> {
|
|
|
177
230
|
* nothing is served. Opens through redirect entry (`entry`); frames take tickets (`issue`).
|
|
178
231
|
*/
|
|
179
232
|
urlOf(scope: string, path?: string): string | null;
|
|
233
|
+
/** Where `routes` answers (`/porthole`). */
|
|
234
|
+
readonly prefix: string;
|
|
235
|
+
/**
|
|
236
|
+
* The app's Porthole routes in one handler (P072): `POST <prefix>/frames` (`issue`), `GET
|
|
237
|
+
* <prefix>/authorize`, `GET <prefix>/meta` (`clientMeta`), `POST`/`DELETE <prefix>/handoff`.
|
|
238
|
+
* Null for any other request: the app's own routes.
|
|
239
|
+
*/
|
|
240
|
+
routes(viewerOf: (request: Request) => Awaitable<V | null>): (request: Request) => Promise<Response | null>;
|
|
241
|
+
/** What `GET <prefix>/meta` answers the page. */
|
|
242
|
+
clientMeta(): ContentClientMeta;
|
|
243
|
+
/** The viewer handoff (`entry.handoff`), as a fetch handler: POST sets it, DELETE clears it. */
|
|
244
|
+
handoff(viewerOf: (request: Request) => Awaitable<V | null>): (request: Request) => Promise<Response>;
|
|
245
|
+
/** Drops cached `authorize` answers (`authorizeTtlSeconds`): all, or a scope's, or a subject's. */
|
|
246
|
+
forget(filter?: {
|
|
247
|
+
readonly scope?: string;
|
|
248
|
+
readonly subject?: string;
|
|
249
|
+
}): void;
|
|
180
250
|
/** The app's authorize route for redirect entry (`entry.authorizeUrl`), as a fetch handler. */
|
|
181
251
|
authorize(viewerOf: (request: Request) => Awaitable<V | null>): (request: Request) => Promise<Response>;
|
|
182
252
|
/** A url-mode app's access for a WebSocket upgrade (`server.access`), or null. */
|
|
@@ -189,4 +259,3 @@ export interface ContentHost<V> {
|
|
|
189
259
|
close(): void;
|
|
190
260
|
}
|
|
191
261
|
export declare function createContentHost<V>(options: ContentHostOptions<V>): ContentHost<V>;
|
|
192
|
-
export {};
|
package/dist/server/host.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { embedderFrameSourcesOf } from "../compile/policy.js";
|
|
2
|
-
import { base64url, hmacSha256, utf8 } from "./crypto.js";
|
|
2
|
+
import { base64url, fromBase64url, fromUtf8, hmacSha256, timingSafeEqual, utf8 } from "./crypto.js";
|
|
3
3
|
import { ContentDomainError, contentDomain, serverDomain, } from "./domain.js";
|
|
4
4
|
import { reservedLabels } from "./naming.js";
|
|
5
5
|
import { appStatusPage } from "./pages.js";
|
|
@@ -37,6 +37,33 @@ const plain = (status, text) => new Response(text, {
|
|
|
37
37
|
"x-robots-tag": "noindex, nofollow",
|
|
38
38
|
},
|
|
39
39
|
});
|
|
40
|
+
/** How long a viewer handoff holds (P072): the app's page refreshes it on load and focus. */
|
|
41
|
+
const HANDOFF_SECONDS = 600;
|
|
42
|
+
/** The kit's events to the app's `log`: its function, or its logger at each event's level. */
|
|
43
|
+
function logOf(given) {
|
|
44
|
+
if (given === undefined) {
|
|
45
|
+
return () => { };
|
|
46
|
+
}
|
|
47
|
+
if (typeof given === "function") {
|
|
48
|
+
return given;
|
|
49
|
+
}
|
|
50
|
+
return (event) => {
|
|
51
|
+
const message = event.evt === "porthole.content.healthy"
|
|
52
|
+
? "Porthole: the content domain answers; frames are served"
|
|
53
|
+
: event.evt === "porthole.content.unhealthy"
|
|
54
|
+
? `Porthole: frames aren't served: ${event.reason}`
|
|
55
|
+
: `Porthole: the content domain can't be served (${event.code}): ${event.reason}`;
|
|
56
|
+
if (event.evt === "porthole.content.healthy") {
|
|
57
|
+
given.info?.(message, event);
|
|
58
|
+
}
|
|
59
|
+
else if (event.evt === "porthole.content.unhealthy") {
|
|
60
|
+
given.warn?.(message, event);
|
|
61
|
+
}
|
|
62
|
+
else {
|
|
63
|
+
given.error?.(message, event);
|
|
64
|
+
}
|
|
65
|
+
};
|
|
66
|
+
}
|
|
40
67
|
/** The CSP source for an authorize route: its origin and path, so nothing else there frames. */
|
|
41
68
|
const authorizeSource = (url) => {
|
|
42
69
|
const parsed = new URL(url);
|
|
@@ -54,11 +81,26 @@ const fetchProbe = async (url, timeoutMs) => {
|
|
|
54
81
|
};
|
|
55
82
|
export function createContentHost(options) {
|
|
56
83
|
const gate = options.health;
|
|
57
|
-
const log = options.log
|
|
58
|
-
const
|
|
84
|
+
const log = logOf(options.log);
|
|
85
|
+
const prefix = (options.prefix ?? "/porthole").replace(/\/+$/u, "");
|
|
86
|
+
if (!/^\/[\w./-]*$/u.test(prefix)) {
|
|
87
|
+
throw new TypeError("A route prefix is a path: /porthole");
|
|
88
|
+
}
|
|
89
|
+
const authorizeUrl = options.entry?.authorizeUrl ?? `${options.appOrigins[0] ?? ""}${prefix}/authorize`;
|
|
90
|
+
if (options.configs === undefined && options.displays === undefined) {
|
|
91
|
+
throw new TypeError("createContentHost needs configs or displays");
|
|
92
|
+
}
|
|
93
|
+
// The secret as given (an unset environment variable: none), checked with the domain below.
|
|
94
|
+
const secret = typeof options.secret === "string"
|
|
95
|
+
? utf8(options.secret.trim())
|
|
96
|
+
: options.secret instanceof Uint8Array
|
|
97
|
+
? options.secret
|
|
98
|
+
: null;
|
|
59
99
|
const healthLabel = gate?.label ?? DEFAULT_HEALTH_LABEL;
|
|
60
100
|
// The id Porthole's health check answers with: keyed, so another deployment's answer fails.
|
|
61
|
-
const healthId =
|
|
101
|
+
const healthId = secret === null || secret.byteLength < 32
|
|
102
|
+
? ""
|
|
103
|
+
: base64url(hmacSha256(secret, utf8("porthole/health"))).slice(0, 22);
|
|
62
104
|
const appReserved = reservedLabels(options.reserved);
|
|
63
105
|
let domain = null;
|
|
64
106
|
let server = null;
|
|
@@ -70,11 +112,26 @@ export function createContentHost(options) {
|
|
|
70
112
|
? options.domain
|
|
71
113
|
: contentDomain(options.domain, { appOrigins: options.appOrigins });
|
|
72
114
|
if (domain !== null) {
|
|
115
|
+
// Said plainly where it's missing, as where it's short (P074).
|
|
116
|
+
if (secret === null) {
|
|
117
|
+
throw new TypeError("createContentHost needs a secret: at least 32 random bytes (set PORTHOLE_SECRET; npx porthole secret makes one)");
|
|
118
|
+
}
|
|
119
|
+
if (secret.byteLength < 32) {
|
|
120
|
+
throw new TypeError("The secret must be at least 32 random bytes (set PORTHOLE_SECRET; npx porthole secret makes one)");
|
|
121
|
+
}
|
|
73
122
|
if (options.entry !== undefined && options.name?.scopeOf === undefined) {
|
|
74
123
|
throw new TypeError("Redirect entry needs a naming that says which scope a label names (prefixedName)");
|
|
75
124
|
}
|
|
125
|
+
const displays = options.displays;
|
|
76
126
|
configs =
|
|
77
|
-
|
|
127
|
+
options.configs === undefined
|
|
128
|
+
? (displays?.served(domain.source) ??
|
|
129
|
+
(() => {
|
|
130
|
+
throw new TypeError(displays?.problem(domain.source) ?? "No configs");
|
|
131
|
+
})())
|
|
132
|
+
: typeof options.configs === "function"
|
|
133
|
+
? options.configs(domain.source)
|
|
134
|
+
: options.configs;
|
|
78
135
|
server = createServer({
|
|
79
136
|
content: serverDomain(domain, {
|
|
80
137
|
...(options.name === undefined ? {} : { name: options.name }),
|
|
@@ -90,7 +147,7 @@ export function createContentHost(options) {
|
|
|
90
147
|
? {}
|
|
91
148
|
: {
|
|
92
149
|
entry: {
|
|
93
|
-
authorizeUrl
|
|
150
|
+
authorizeUrl,
|
|
94
151
|
// Whether a clean address names anything, before a browser is sent away (P070).
|
|
95
152
|
named: async (label, path, request) => {
|
|
96
153
|
const scope = options.name?.scopeOf?.(label) ?? null;
|
|
@@ -128,6 +185,20 @@ export function createContentHost(options) {
|
|
|
128
185
|
log({ evt: "porthole.content.misconfigured", code, reason });
|
|
129
186
|
}
|
|
130
187
|
const served = () => server !== null && view.state === "healthy";
|
|
188
|
+
// onServedChange: once per flip of served(), the first decision included.
|
|
189
|
+
let toldServed = null;
|
|
190
|
+
const tellServed = () => {
|
|
191
|
+
const now = served();
|
|
192
|
+
if (now !== toldServed && view.state !== "checking") {
|
|
193
|
+
toldServed = now;
|
|
194
|
+
try {
|
|
195
|
+
gate?.onServedChange?.(now);
|
|
196
|
+
}
|
|
197
|
+
catch {
|
|
198
|
+
// The app's listener failing changes nothing here.
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
};
|
|
131
202
|
// The health gate: one check at a time, again after a minute while unhealthy, ten while healthy.
|
|
132
203
|
let timer = null;
|
|
133
204
|
let running = null;
|
|
@@ -193,6 +264,7 @@ export function createContentHost(options) {
|
|
|
193
264
|
// The app's listener failing changes nothing here.
|
|
194
265
|
}
|
|
195
266
|
}
|
|
267
|
+
tellServed();
|
|
196
268
|
running = null;
|
|
197
269
|
schedule();
|
|
198
270
|
return view;
|
|
@@ -242,7 +314,88 @@ export function createContentHost(options) {
|
|
|
242
314
|
const top = label.split(".").at(-1) ?? "";
|
|
243
315
|
return top !== "" && appReserved(top) ? null : { url, label };
|
|
244
316
|
};
|
|
245
|
-
|
|
317
|
+
// The viewer handoff (P072): a key Porthole signs, naming the app's viewer until a time, in a
|
|
318
|
+
// cookie only the prefix's routes get. Never the app's own credential.
|
|
319
|
+
// None where the secret can't sign (then nothing is served, and no handoff made or taken).
|
|
320
|
+
const handoffKey = secret === null || secret.byteLength < 32 ? null : hmacSha256(secret, utf8("porthole/handoff"));
|
|
321
|
+
const secureApp = (options.appOrigins[0] ?? "").startsWith("https:");
|
|
322
|
+
const handoffName = secureApp ? "__Secure-porthole-handoff" : "porthole-handoff";
|
|
323
|
+
const handoffCookie = (value, maxAge) => [
|
|
324
|
+
`${handoffName}=${value}`,
|
|
325
|
+
`Path=${prefix}`,
|
|
326
|
+
"HttpOnly",
|
|
327
|
+
"SameSite=Lax",
|
|
328
|
+
`Max-Age=${maxAge}`,
|
|
329
|
+
...(secureApp ? ["Secure"] : []),
|
|
330
|
+
].join("; ");
|
|
331
|
+
const signHandoff = (key, id, until) => {
|
|
332
|
+
const payload = base64url(utf8(JSON.stringify({ h: 1, v: id, x: until })));
|
|
333
|
+
return `${payload}.${base64url(hmacSha256(key, utf8(payload)))}`;
|
|
334
|
+
};
|
|
335
|
+
/** The viewer a request's handoff cookie names, if it is good. */
|
|
336
|
+
const handedOver = async (request) => {
|
|
337
|
+
const handoff = options.entry?.handoff;
|
|
338
|
+
if (handoff === undefined || handoffKey === null) {
|
|
339
|
+
return null;
|
|
340
|
+
}
|
|
341
|
+
for (const part of (request.headers.get("cookie") ?? "").split(";")) {
|
|
342
|
+
const at = part.indexOf("=");
|
|
343
|
+
if (at < 0 || part.slice(0, at).trim() !== handoffName) {
|
|
344
|
+
continue;
|
|
345
|
+
}
|
|
346
|
+
const [payload = "", mac = "", ...rest] = part
|
|
347
|
+
.slice(at + 1)
|
|
348
|
+
.trim()
|
|
349
|
+
.split(".");
|
|
350
|
+
const given = fromBase64url(mac);
|
|
351
|
+
if (rest.length > 0 ||
|
|
352
|
+
given === null ||
|
|
353
|
+
!timingSafeEqual(given, hmacSha256(handoffKey, utf8(payload)))) {
|
|
354
|
+
continue;
|
|
355
|
+
}
|
|
356
|
+
const bytes = fromBase64url(payload);
|
|
357
|
+
let said = null;
|
|
358
|
+
try {
|
|
359
|
+
said = bytes === null ? null : JSON.parse(fromUtf8(bytes));
|
|
360
|
+
}
|
|
361
|
+
catch {
|
|
362
|
+
said = null;
|
|
363
|
+
}
|
|
364
|
+
if (isRecord(said) &&
|
|
365
|
+
said.h === 1 &&
|
|
366
|
+
typeof said.v === "string" &&
|
|
367
|
+
typeof said.x === "number" &&
|
|
368
|
+
said.x > Date.now()) {
|
|
369
|
+
return handoff.viewer(said.v, request);
|
|
370
|
+
}
|
|
371
|
+
}
|
|
372
|
+
return null;
|
|
373
|
+
};
|
|
374
|
+
/**
|
|
375
|
+
* Where the person comes back after signing in: the authorize route as the app is reached
|
|
376
|
+
* (`authorizeUrl`'s origin and path), with this request's query (its state). Never the request's
|
|
377
|
+
* own URL, whose origin behind a TLS edge or a dev proxy isn't the app's (P074).
|
|
378
|
+
*/
|
|
379
|
+
const returnOf = (request) => {
|
|
380
|
+
const back = new URL(authorizeUrl);
|
|
381
|
+
back.search = new URL(request.url).search;
|
|
382
|
+
return back.href;
|
|
383
|
+
};
|
|
384
|
+
/** The app's sign-in: its own `signIn`, or its single-page route with `next`. */
|
|
385
|
+
const signInWith = async (entry, request, context) => {
|
|
386
|
+
const returnTo = returnOf(request);
|
|
387
|
+
if (entry.signIn !== undefined) {
|
|
388
|
+
return entry.signIn(returnTo, request, context);
|
|
389
|
+
}
|
|
390
|
+
const route = entry.spa?.route ?? "/";
|
|
391
|
+
const to = new URL(route, new URL(authorizeUrl).origin);
|
|
392
|
+
to.searchParams.set("next", returnTo);
|
|
393
|
+
return new Response(null, {
|
|
394
|
+
status: 303,
|
|
395
|
+
headers: { location: to.href, "cache-control": "no-store", "referrer-policy": "no-referrer" },
|
|
396
|
+
});
|
|
397
|
+
};
|
|
398
|
+
const host = {
|
|
246
399
|
get domain() {
|
|
247
400
|
return domain;
|
|
248
401
|
},
|
|
@@ -254,7 +407,7 @@ export function createContentHost(options) {
|
|
|
254
407
|
: [
|
|
255
408
|
...embedderFrameSourcesOf(Object.values(configs)),
|
|
256
409
|
// A frame on a clean address goes by the authorize route (only that path).
|
|
257
|
-
...(options.entry === undefined ? [] : [authorizeSource(
|
|
410
|
+
...(options.entry === undefined ? [] : [authorizeSource(authorizeUrl)]),
|
|
258
411
|
],
|
|
259
412
|
owns: (request) => routeOf(request) !== null,
|
|
260
413
|
async fetch(request) {
|
|
@@ -329,7 +482,16 @@ export function createContentHost(options) {
|
|
|
329
482
|
catch (error) {
|
|
330
483
|
return refusal(409, "refused", error instanceof Error ? error.message : String(error));
|
|
331
484
|
}
|
|
332
|
-
|
|
485
|
+
// The clean address, where the app says the instance's path (P072, P074).
|
|
486
|
+
let link = null;
|
|
487
|
+
try {
|
|
488
|
+
const path = (await options.entry?.pathOf?.(instance, request)) ?? null;
|
|
489
|
+
link = path === null ? null : server.urlOf(instance.scope, path);
|
|
490
|
+
}
|
|
491
|
+
catch {
|
|
492
|
+
link = null;
|
|
493
|
+
}
|
|
494
|
+
return json(201, link === null ? location : { ...location, link });
|
|
333
495
|
}
|
|
334
496
|
catch {
|
|
335
497
|
return refusal(500, "failed", "The app's policy failed");
|
|
@@ -341,6 +503,100 @@ export function createContentHost(options) {
|
|
|
341
503
|
contentSource: domain?.source ?? null,
|
|
342
504
|
health: gate === undefined ? null : view,
|
|
343
505
|
}),
|
|
506
|
+
prefix,
|
|
507
|
+
clientMeta: () => ({
|
|
508
|
+
served: served(),
|
|
509
|
+
contentSource: domain?.source ?? null,
|
|
510
|
+
frameSources: host.frameSources,
|
|
511
|
+
health: gate === undefined
|
|
512
|
+
? null
|
|
513
|
+
: { state: view.state, ...(view.reason === undefined ? {} : { reason: view.reason }) },
|
|
514
|
+
}),
|
|
515
|
+
routes(viewerOf) {
|
|
516
|
+
const issue = host.issue(viewerOf);
|
|
517
|
+
const authorize = host.authorize(viewerOf);
|
|
518
|
+
const handoff = host.handoff(viewerOf);
|
|
519
|
+
return async (request) => {
|
|
520
|
+
let pathname;
|
|
521
|
+
try {
|
|
522
|
+
pathname = new URL(request.url).pathname;
|
|
523
|
+
}
|
|
524
|
+
catch {
|
|
525
|
+
return null;
|
|
526
|
+
}
|
|
527
|
+
if (!pathname.startsWith(`${prefix}/`)) {
|
|
528
|
+
return null;
|
|
529
|
+
}
|
|
530
|
+
const method = request.method.toUpperCase();
|
|
531
|
+
switch (pathname.slice(prefix.length)) {
|
|
532
|
+
case "/frames":
|
|
533
|
+
return issue(request);
|
|
534
|
+
case "/authorize":
|
|
535
|
+
return authorize(request);
|
|
536
|
+
case "/meta":
|
|
537
|
+
return method === "GET" || method === "HEAD"
|
|
538
|
+
? json(200, host.clientMeta())
|
|
539
|
+
: refusal(405, "method", "GET here");
|
|
540
|
+
case "/handoff":
|
|
541
|
+
return handoff(request);
|
|
542
|
+
default:
|
|
543
|
+
return null;
|
|
544
|
+
}
|
|
545
|
+
};
|
|
546
|
+
},
|
|
547
|
+
handoff(viewerOf) {
|
|
548
|
+
return async (request) => {
|
|
549
|
+
const method = request.method.toUpperCase();
|
|
550
|
+
if (method !== "POST" && method !== "DELETE") {
|
|
551
|
+
return refusal(405, "method", "POST (or DELETE) here");
|
|
552
|
+
}
|
|
553
|
+
const handoff = options.entry?.handoff;
|
|
554
|
+
if (handoff === undefined) {
|
|
555
|
+
return refusal(404, "not-found", "This app has no viewer handoff (entry.handoff)");
|
|
556
|
+
}
|
|
557
|
+
// The app's own page only: a request from another site never sets or clears it.
|
|
558
|
+
const origin = request.headers.get("origin");
|
|
559
|
+
const site = request.headers.get("sec-fetch-site");
|
|
560
|
+
if ((origin !== null && !options.appOrigins.includes(origin)) ||
|
|
561
|
+
(origin === null && site !== null && site !== "same-origin")) {
|
|
562
|
+
return refusal(403, "cross-site", "Only the app's own page hands its viewer over");
|
|
563
|
+
}
|
|
564
|
+
if (method === "DELETE") {
|
|
565
|
+
return new Response(null, {
|
|
566
|
+
status: 204,
|
|
567
|
+
headers: { "set-cookie": handoffCookie("", 0), "cache-control": "no-store" },
|
|
568
|
+
});
|
|
569
|
+
}
|
|
570
|
+
let viewer;
|
|
571
|
+
try {
|
|
572
|
+
viewer = await viewerOf(request);
|
|
573
|
+
}
|
|
574
|
+
catch {
|
|
575
|
+
return refusal(500, "failed", "The app couldn't tell who is asking");
|
|
576
|
+
}
|
|
577
|
+
if (viewer === null) {
|
|
578
|
+
return refusal(401, "unauthenticated", "Sign in first: the handoff names a viewer");
|
|
579
|
+
}
|
|
580
|
+
const id = handoff.id(viewer);
|
|
581
|
+
if (typeof id !== "string" || id.length === 0 || id.length > 512) {
|
|
582
|
+
return refusal(500, "failed", "entry.handoff.id gave no id (1 to 512 characters)");
|
|
583
|
+
}
|
|
584
|
+
if (handoffKey === null) {
|
|
585
|
+
return refusal(503, "unavailable", "The content domain isn't served");
|
|
586
|
+
}
|
|
587
|
+
const key = signHandoff(handoffKey, id, Date.now() + HANDOFF_SECONDS * 1_000);
|
|
588
|
+
return new Response(null, {
|
|
589
|
+
status: 204,
|
|
590
|
+
headers: {
|
|
591
|
+
"set-cookie": handoffCookie(key, HANDOFF_SECONDS),
|
|
592
|
+
"cache-control": "no-store",
|
|
593
|
+
},
|
|
594
|
+
});
|
|
595
|
+
};
|
|
596
|
+
},
|
|
597
|
+
forget(filter = {}) {
|
|
598
|
+
server?.forget(filter);
|
|
599
|
+
},
|
|
344
600
|
urlOf(scope, path = "/") {
|
|
345
601
|
return server === null || !served() ? null : server.urlOf(scope, path);
|
|
346
602
|
},
|
|
@@ -368,7 +624,7 @@ export function createContentHost(options) {
|
|
|
368
624
|
const scope = options.name?.scopeOf?.(state.label) ?? null;
|
|
369
625
|
let viewer;
|
|
370
626
|
try {
|
|
371
|
-
viewer = await viewerOf(request);
|
|
627
|
+
viewer = (await viewerOf(request)) ?? (await handedOver(request));
|
|
372
628
|
}
|
|
373
629
|
catch {
|
|
374
630
|
return appPage(500, "Something went wrong", "The app couldn't tell who is asking.", "error", method);
|
|
@@ -392,7 +648,7 @@ export function createContentHost(options) {
|
|
|
392
648
|
// The app's sign-in never shows in a frame: the person opens a tab for it.
|
|
393
649
|
return framed
|
|
394
650
|
? appPage(401, "Open this in a new tab to sign in", "Signing in doesn't work inside a frame.", "sign-in", method)
|
|
395
|
-
: await entry
|
|
651
|
+
: await signInWith(entry, request, context);
|
|
396
652
|
}
|
|
397
653
|
const status = instance === null ? 404 : 403;
|
|
398
654
|
const own = framed ? null : await entry.refusal?.(status, request, context);
|
|
@@ -443,4 +699,5 @@ export function createContentHost(options) {
|
|
|
443
699
|
}
|
|
444
700
|
},
|
|
445
701
|
};
|
|
702
|
+
return host;
|
|
446
703
|
}
|
package/dist/server/index.d.ts
CHANGED
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
* content without a valid ticket or cookie gets nothing of the content.
|
|
34
34
|
*/
|
|
35
35
|
export { createServer } from "./server.ts";
|
|
36
|
-
export { createContentHost, HEALTH_PATH, type ContentHealthView, type ContentHost, type ContentHostEvent, type ContentHostOptions, type EntryContext, type EntryOptions, type ContentMeta, type HealthOptions, type HealthProbe, } from "./host.ts";
|
|
36
|
+
export { createContentHost, HEALTH_PATH, type ContentHealthView, type ContentHost, type ContentHostEvent, type ContentHostOptions, type ContentClientMeta, type ContentLogger, type EntryContext, type EntryOptions, type ContentMeta, type HealthOptions, type HealthProbe, } from "./host.ts";
|
|
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";
|
|
@@ -41,5 +41,7 @@ export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
|
|
|
41
41
|
export { conformancePage } from "../conformance/page.ts";
|
|
42
42
|
export type { PortholeConfig } from "../config/schema.ts";
|
|
43
43
|
export type { FrameLocation, InstanceRef, ServedDocument } from "../isolation/types.ts";
|
|
44
|
-
export { proxyTo, type ProxyOptions } from "./proxy.ts";
|
|
44
|
+
export { isPortholeCookie, proxyTo, upstreamHeaders, withoutPortholeCookies, type ProxyOptions, } from "./proxy.ts";
|
|
45
|
+
export { statusPageOf as statusPage } from "./pages.ts";
|
|
46
|
+
export { contentHostFor, type ContentHostFor } from "./bootstrap.ts";
|
|
45
47
|
export type { Access, ArtifactStore, AuthorizeAnswer, AuthorizeRequest, Authorizer, ContentDomain, EntryState, Grant, PortholeServer, ServerOptions, TicketRecord, TicketStore, Upstream, } from "./types.ts";
|
package/dist/server/index.js
CHANGED
|
@@ -40,4 +40,6 @@ export { FRAME_STATUS_METHOD } from "../isolation/types.js";
|
|
|
40
40
|
export { isHostLabel, prefixedName } from "./naming.js";
|
|
41
41
|
// The page an app serves in conformance test mode (P071).
|
|
42
42
|
export { conformancePage } from "../conformance/page.js";
|
|
43
|
-
export { proxyTo } from "./proxy.js";
|
|
43
|
+
export { isPortholeCookie, proxyTo, upstreamHeaders, withoutPortholeCookies, } from "./proxy.js";
|
|
44
|
+
export { statusPageOf as statusPage } from "./pages.js";
|
|
45
|
+
export { contentHostFor } from "./bootstrap.js";
|
package/dist/server/pages.d.ts
CHANGED
|
@@ -18,3 +18,22 @@ export declare function appStatusPage(status: number, title: string, detail: str
|
|
|
18
18
|
readonly href: string;
|
|
19
19
|
readonly text: string;
|
|
20
20
|
}, method?: string): Response;
|
|
21
|
+
/**
|
|
22
|
+
* A page saying why a frame shows nothing, for a relay of the app's own (P072): told to the page
|
|
23
|
+
* that frames it, at each web host origin and (a desktop scheme among them) to its parent (P070),
|
|
24
|
+
* its one script inline under its hash, so it works on any origin.
|
|
25
|
+
*/
|
|
26
|
+
export declare function statusPageOf(options: {
|
|
27
|
+
readonly status: number;
|
|
28
|
+
readonly title: string;
|
|
29
|
+
readonly detail: string;
|
|
30
|
+
readonly reason?: FrameBlock;
|
|
31
|
+
readonly hostOrigins: readonly string[];
|
|
32
|
+
/** Who may frame it (`frame-ancestors`): default, the host origins. */
|
|
33
|
+
readonly frameAncestors?: string;
|
|
34
|
+
readonly link?: {
|
|
35
|
+
readonly href: string;
|
|
36
|
+
readonly text: string;
|
|
37
|
+
};
|
|
38
|
+
readonly method?: string;
|
|
39
|
+
}): Response;
|
package/dist/server/pages.js
CHANGED
|
@@ -140,3 +140,11 @@ export function appStatusPage(status, title, detail, frameAncestors, reason, hos
|
|
|
140
140
|
},
|
|
141
141
|
});
|
|
142
142
|
}
|
|
143
|
+
/**
|
|
144
|
+
* A page saying why a frame shows nothing, for a relay of the app's own (P072): told to the page
|
|
145
|
+
* that frames it, at each web host origin and (a desktop scheme among them) to its parent (P070),
|
|
146
|
+
* its one script inline under its hash, so it works on any origin.
|
|
147
|
+
*/
|
|
148
|
+
export function statusPageOf(options) {
|
|
149
|
+
return appStatusPage(options.status, options.title, options.detail, options.frameAncestors ?? options.hostOrigins.join(" "), options.reason ?? "error", options.hostOrigins, options.link, options.method);
|
|
150
|
+
}
|