@botiverse/porthole 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -0
- package/dist/bridge/bridge.d.ts +12 -4
- package/dist/bridge/bridge.js +62 -27
- package/dist/bridge/navigation.d.ts +6 -0
- package/dist/bridge/navigation.js +41 -0
- package/dist/bridge/refusal.d.ts +53 -0
- package/dist/bridge/refusal.js +121 -0
- package/dist/bridge/types.d.ts +7 -0
- package/dist/check/check.d.ts +12 -3
- package/dist/check/check.js +54 -8
- package/dist/check/files.d.ts +26 -0
- package/dist/check/files.js +307 -0
- package/dist/check/lint.js +27 -10
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +5 -0
- package/dist/check/tools.d.ts +23 -0
- package/dist/check/tools.js +25 -0
- package/dist/compile/policy.d.ts +15 -0
- package/dist/compile/policy.js +32 -0
- package/dist/config/capabilities.d.ts +5 -0
- package/dist/config/schema.d.ts +8 -0
- package/dist/config/validate.js +8 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/files/paths.d.ts +99 -0
- package/dist/files/paths.js +263 -0
- package/dist/files/types.d.ts +24 -0
- package/dist/files/types.js +83 -0
- package/dist/guide/guide.js +25 -5
- package/dist/host/create-host.js +36 -4
- package/dist/host/types.d.ts +15 -2
- package/dist/index.d.ts +7 -3
- package/dist/index.js +10 -3
- package/dist/mcp/adapter.js +22 -7
- package/dist/protocol/adapter.d.ts +4 -0
- package/dist/protocol/mcp-apps.d.ts +12 -0
- package/dist/protocol/mcp-apps.js +12 -0
- package/dist/protocol/shell-adapter.js +18 -2
- package/dist/react/frame.d.ts +19 -4
- package/dist/react/frame.js +37 -9
- package/dist/server/files.d.ts +44 -0
- package/dist/server/files.js +244 -0
- package/dist/server/host.d.ts +38 -1
- package/dist/server/host.js +37 -2
- package/dist/server/index.d.ts +4 -2
- package/dist/server/index.js +4 -1
- package/dist/server/keys.d.ts +8 -0
- package/dist/server/keys.js +34 -0
- package/dist/server/server.js +287 -22
- package/dist/server/types.d.ts +49 -5
- package/dist/shell/document.d.ts +19 -0
- package/dist/shell/document.js +30 -0
- package/dist/shell/runtime.d.ts +2 -1
- package/dist/shell/runtime.js +117 -10
- package/docs/ADOPTING.md +95 -13
- package/docs/ARCHITECTURE.md +13 -3
- package/docs/DECISIONS.md +396 -4
- package/docs/DESIGN.md +43 -10
- package/package.json +1 -1
- package/src/bridge/bridge.ts +74 -23
- package/src/bridge/navigation.ts +46 -0
- package/src/bridge/refusal.ts +151 -0
- package/src/bridge/types.ts +12 -1
- package/src/check/check.ts +92 -14
- package/src/check/files.ts +384 -0
- package/src/check/lint.ts +29 -10
- package/src/check/page.ts +7 -0
- package/src/check/tools.ts +50 -0
- package/src/compile/policy.ts +38 -0
- package/src/config/capabilities.ts +5 -1
- package/src/config/schema.ts +8 -0
- package/src/config/validate.ts +8 -1
- package/src/files/paths.ts +323 -0
- package/src/files/types.ts +101 -0
- package/src/guide/guide.ts +38 -4
- package/src/host/create-host.ts +37 -4
- package/src/host/types.ts +13 -2
- package/src/index.ts +41 -0
- package/src/mcp/adapter.ts +26 -6
- package/src/protocol/adapter.ts +3 -1
- package/src/protocol/mcp-apps.ts +14 -0
- package/src/protocol/shell-adapter.ts +20 -2
- package/src/react/frame.tsx +53 -14
- package/src/server/files.ts +312 -0
- package/src/server/host.ts +72 -3
- package/src/server/index.ts +19 -0
- package/src/server/keys.ts +53 -0
- package/src/server/server.ts +353 -24
- package/src/server/types.ts +56 -4
- package/src/shell/document.ts +53 -0
- package/src/shell/runtime.ts +117 -10
package/src/bridge/bridge.ts
CHANGED
|
@@ -9,6 +9,15 @@ import type { AnnotationReport } from "../annotate/types.ts";
|
|
|
9
9
|
import { parseReport } from "../annotate/validate.ts";
|
|
10
10
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
11
11
|
import { effectiveGates } from "../compile/policy.ts";
|
|
12
|
+
import { blockedNavigationMessage, withoutSealedAddresses } from "./navigation.ts";
|
|
13
|
+
import {
|
|
14
|
+
defaultReason,
|
|
15
|
+
isRefused,
|
|
16
|
+
pendingReason,
|
|
17
|
+
reasonOf,
|
|
18
|
+
type Refused,
|
|
19
|
+
type RefusalReason,
|
|
20
|
+
} from "./refusal.ts";
|
|
12
21
|
import type {
|
|
13
22
|
CallOptions,
|
|
14
23
|
CallOutcome,
|
|
@@ -34,6 +43,8 @@ import type {
|
|
|
34
43
|
export type BridgeEvent =
|
|
35
44
|
| { readonly type: "resize"; readonly height: number; readonly width?: number }
|
|
36
45
|
| { readonly type: "error"; readonly message: string }
|
|
46
|
+
/** The shell cancelled a navigation of the frame to `url` (P080): the content's word. */
|
|
47
|
+
| { readonly type: "navigationBlocked"; readonly url: string }
|
|
37
48
|
| { readonly type: "annotation"; readonly report: AnnotationReport }
|
|
38
49
|
| { readonly type: "refused"; readonly capability: CapabilityName; readonly refusal: Refusal }
|
|
39
50
|
| { readonly type: "muted" };
|
|
@@ -45,9 +56,10 @@ export interface BridgeOptions {
|
|
|
45
56
|
readonly confirm?: Confirm;
|
|
46
57
|
/**
|
|
47
58
|
* Asked before a `consent`-gated call (P079). The host's, made to ask once per display by the
|
|
48
|
-
* caller (`createHost` keeps the answer across the display's frames).
|
|
59
|
+
* caller (`createHost` keeps the answer across the display's frames). A `Refused` refuses every
|
|
60
|
+
* such call with it, asking nothing (P080).
|
|
49
61
|
*/
|
|
50
|
-
readonly consent?: Consent;
|
|
62
|
+
readonly consent?: Consent | Refused;
|
|
51
63
|
/** The host's cache, for reads that may be answered stale (`CallOptions.stale`, P079). */
|
|
52
64
|
readonly cached?: DataCache;
|
|
53
65
|
/** Whether the embedding page has user activation now; undefined where it can't tell. */
|
|
@@ -143,10 +155,21 @@ const VALIDATORS: { readonly [N in CapabilityName]: Validator<N> } = {
|
|
|
143
155
|
...(structuredContent === undefined ? {} : { structuredContent }),
|
|
144
156
|
};
|
|
145
157
|
},
|
|
146
|
-
reportError: (args) => {
|
|
158
|
+
reportError: (args, config) => {
|
|
159
|
+
// A navigation the shell cancelled (P080): Porthole words it, naming the address without its
|
|
160
|
+
// query; the address itself goes to the host whole.
|
|
161
|
+
// A frame's sealed files' address never reaches the host from here (P083): `./` instead.
|
|
162
|
+
const blocked = isRecord(args) ? args.navigationBlocked : undefined;
|
|
163
|
+
if (blocked !== undefined) {
|
|
164
|
+
if (typeof blocked !== "string" || blocked === "" || blocked.length > MAX_URL) {
|
|
165
|
+
return null;
|
|
166
|
+
}
|
|
167
|
+
const url = withoutSealedAddresses(blocked);
|
|
168
|
+
return { message: blockedNavigationMessage(url, config), navigationBlocked: url };
|
|
169
|
+
}
|
|
147
170
|
const message = isRecord(args) ? args.message : undefined;
|
|
148
171
|
return typeof message === "string" && message !== ""
|
|
149
|
-
? { message: message.slice(0, 2_000) }
|
|
172
|
+
? { message: withoutSealedAddresses(message).slice(0, 2_000) }
|
|
150
173
|
: null;
|
|
151
174
|
},
|
|
152
175
|
copyText: (args) => {
|
|
@@ -174,22 +197,32 @@ const VALIDATORS: { readonly [N in CapabilityName]: Validator<N> } = {
|
|
|
174
197
|
|
|
175
198
|
/**
|
|
176
199
|
* The host's `consent`, asked once (P079): the first call asks, every later one gets that answer,
|
|
177
|
-
* for as long as the returned function is kept (`createHost` keeps one per display). A
|
|
178
|
-
*
|
|
200
|
+
* for as long as the returned function is kept (`createHost` keeps one per display). A `Refused`
|
|
201
|
+
* it throws is an answer, kept and thrown again at every call (P080); anything else it throws is
|
|
202
|
+
* no answer: thrown for that call, and the next asks again.
|
|
179
203
|
*/
|
|
180
204
|
export function onceConsent(consent: Consent): Consent {
|
|
181
|
-
let answer: Promise<boolean> | null = null;
|
|
182
|
-
return (request) =>
|
|
183
|
-
(answer ??= Promise.resolve()
|
|
205
|
+
let answer: Promise<boolean | Refused> | null = null;
|
|
206
|
+
return async (request) => {
|
|
207
|
+
const asked = (answer ??= Promise.resolve()
|
|
184
208
|
.then(() => consent(request))
|
|
185
209
|
.then(
|
|
186
210
|
// Only a real yes: anything else a host's function gives is a no (fail closed).
|
|
187
211
|
(allowed: unknown) => allowed === true,
|
|
188
|
-
() => {
|
|
212
|
+
(error: unknown) => {
|
|
213
|
+
if (isRefused(error)) {
|
|
214
|
+
return error;
|
|
215
|
+
}
|
|
189
216
|
answer = null;
|
|
190
|
-
|
|
217
|
+
throw error;
|
|
191
218
|
},
|
|
192
219
|
));
|
|
220
|
+
const given = await asked;
|
|
221
|
+
if (typeof given !== "boolean") {
|
|
222
|
+
throw given;
|
|
223
|
+
}
|
|
224
|
+
return given;
|
|
225
|
+
};
|
|
193
226
|
}
|
|
194
227
|
|
|
195
228
|
export function createBridge(options: BridgeOptions): HostFunctionBridge {
|
|
@@ -203,9 +236,15 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
|
|
|
203
236
|
capability: CapabilityName,
|
|
204
237
|
refusal: Refusal,
|
|
205
238
|
message?: string,
|
|
239
|
+
reason?: RefusalReason,
|
|
206
240
|
): CallOutcome<T> => {
|
|
207
241
|
onEvent({ type: "refused", capability, refusal });
|
|
208
|
-
return {
|
|
242
|
+
return {
|
|
243
|
+
ok: false,
|
|
244
|
+
refusal,
|
|
245
|
+
...(message === undefined ? {} : { message }),
|
|
246
|
+
reason: reason ?? defaultReason(capability, refusal),
|
|
247
|
+
};
|
|
209
248
|
};
|
|
210
249
|
|
|
211
250
|
const withinRate = (capability: CapabilityName, perMinute: number): boolean => {
|
|
@@ -253,21 +292,27 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
|
|
|
253
292
|
}
|
|
254
293
|
}
|
|
255
294
|
if (gates.includes("consent")) {
|
|
256
|
-
|
|
295
|
+
const consent = options.consent;
|
|
296
|
+
if (consent === undefined) {
|
|
257
297
|
return refuse<Result>(capability, "no-consent");
|
|
258
298
|
}
|
|
259
|
-
|
|
299
|
+
// The host's policy, known before any call: every one refused with its reason (P080).
|
|
300
|
+
if (isRefused(consent)) {
|
|
301
|
+
return refuse<Result>(capability, "denied", undefined, reasonOf(consent));
|
|
302
|
+
}
|
|
303
|
+
let answer: unknown = false;
|
|
260
304
|
try {
|
|
261
|
-
|
|
305
|
+
answer = await consent({ capability, args, display } as ConfirmRequest);
|
|
306
|
+
} catch (error) {
|
|
307
|
+
// A Refused is the host's no, with its reason; any other failure is no answer yet.
|
|
308
|
+
return refuse<Result>(
|
|
262
309
|
capability,
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
} catch {
|
|
268
|
-
allowed = false;
|
|
310
|
+
"denied",
|
|
311
|
+
undefined,
|
|
312
|
+
isRefused(error) ? reasonOf(error) : pendingReason(capability),
|
|
313
|
+
);
|
|
269
314
|
}
|
|
270
|
-
if (
|
|
315
|
+
if (answer !== true) {
|
|
271
316
|
return refuse<Result>(capability, "denied");
|
|
272
317
|
}
|
|
273
318
|
}
|
|
@@ -321,7 +366,11 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
|
|
|
321
366
|
} else if (capability === "annotate") {
|
|
322
367
|
onEvent({ type: "annotation", report: args as CapabilityArgs["annotate"] });
|
|
323
368
|
} else {
|
|
324
|
-
|
|
369
|
+
const report = args as CapabilityArgs["reportError"];
|
|
370
|
+
if (report.navigationBlocked !== undefined) {
|
|
371
|
+
onEvent({ type: "navigationBlocked", url: report.navigationBlocked });
|
|
372
|
+
}
|
|
373
|
+
onEvent({ type: "error", message: report.message });
|
|
325
374
|
}
|
|
326
375
|
return { ok: true, value: undefined as Result };
|
|
327
376
|
}
|
|
@@ -353,10 +402,12 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
|
|
|
353
402
|
);
|
|
354
403
|
return { ok: true, value: value as Result };
|
|
355
404
|
} catch (error) {
|
|
405
|
+
// A host's Refused tells content its reason (P080); any other error stays the host's.
|
|
356
406
|
return refuse<Result>(
|
|
357
407
|
capability,
|
|
358
408
|
"failed",
|
|
359
409
|
error instanceof Error ? error.message : String(error),
|
|
410
|
+
isRefused(error) ? reasonOf(error) : undefined,
|
|
360
411
|
);
|
|
361
412
|
}
|
|
362
413
|
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* A navigation the shell cancelled (P079), as the host is told it (P080): the address, whole, on
|
|
5
|
+
* the `navigationBlocked` event (the host's to keep), and a sentence for the content's errors
|
|
6
|
+
* (`contentError`, which a host may give the agent that wrote it) that names the address without
|
|
7
|
+
* its query or fragment, where a viewer's data would be.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* A frame's sealed files' address (P083) is its access: whatever content says, the host is told
|
|
12
|
+
* it as `./`, the page's own files (the shell says it so already; content may not).
|
|
13
|
+
*/
|
|
14
|
+
const SEALED = /(?:https?:\/\/[^\s"'<>/]+)?\/__porthole\/f\/[A-Za-z0-9_-]{20,}\//gu;
|
|
15
|
+
export const withoutSealedAddresses = (text: string): string => text.replace(SEALED, "./");
|
|
16
|
+
|
|
17
|
+
/** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
|
|
18
|
+
export function addressWithoutQuery(url: string): string {
|
|
19
|
+
// A page's own file (P084), as the shell names it: its path, without query or fragment.
|
|
20
|
+
if (url.startsWith("./")) {
|
|
21
|
+
const path = url.split(/[?#]/u)[0] ?? "./";
|
|
22
|
+
return path === url ? path : `${path}?…`;
|
|
23
|
+
}
|
|
24
|
+
let parsed: URL;
|
|
25
|
+
try {
|
|
26
|
+
parsed = new URL(url);
|
|
27
|
+
} catch {
|
|
28
|
+
return "another address";
|
|
29
|
+
}
|
|
30
|
+
if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
|
|
31
|
+
return `a ${parsed.protocol} address`;
|
|
32
|
+
}
|
|
33
|
+
const rest = parsed.search !== "" || parsed.hash !== "" ? "?…" : "";
|
|
34
|
+
return `${parsed.origin}${parsed.pathname}${rest}`;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** What the content's errors say about a navigation the shell cancelled. */
|
|
38
|
+
export function blockedNavigationMessage(url: string, config: PortholeConfig): string {
|
|
39
|
+
const links =
|
|
40
|
+
config.capabilities.openLink === undefined
|
|
41
|
+
? ""
|
|
42
|
+
: config.mode === "mcp-app"
|
|
43
|
+
? " Open links with ui/open-link (a new tab)."
|
|
44
|
+
: " Open links with openLink(url) or an <a href> (a new tab).";
|
|
45
|
+
return `It tried to navigate its frame to ${addressWithoutQuery(url)}, and was stopped: content never leaves its page.${links}`;
|
|
46
|
+
}
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
import type { CapabilityName } from "../config/capabilities.ts";
|
|
2
|
+
import type { Refusal } from "./types.ts";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Why a call was refused, as content is told (P080): a code it can branch on and a sentence it can
|
|
6
|
+
* show the person viewing it. Carried in a refused request's JSON-RPC error, as its `data`; the
|
|
7
|
+
* shell's globals reject with an error that has both (`error.code`, `error.message`).
|
|
8
|
+
*
|
|
9
|
+
* - `consent_required`: the viewer hasn't allowed it yet (their answer is still to come).
|
|
10
|
+
* - `denied`: the viewer (or the person asked to confirm) said no.
|
|
11
|
+
* - `rate_limited`: too many calls this minute.
|
|
12
|
+
* - `not_allowed`: the host doesn't let this content have it, here or at all (a URI it doesn't
|
|
13
|
+
* serve, a page where data never runs).
|
|
14
|
+
* - `failed`: the host tried and couldn't.
|
|
15
|
+
*/
|
|
16
|
+
export const REFUSAL_CODES = [
|
|
17
|
+
"consent_required",
|
|
18
|
+
"denied",
|
|
19
|
+
"rate_limited",
|
|
20
|
+
"not_allowed",
|
|
21
|
+
"failed",
|
|
22
|
+
] as const;
|
|
23
|
+
|
|
24
|
+
export type RefusalCode = (typeof REFUSAL_CODES)[number];
|
|
25
|
+
|
|
26
|
+
/** What content is told about a refusal: the JSON-RPC error's `data`. */
|
|
27
|
+
export interface RefusalReason {
|
|
28
|
+
readonly code: RefusalCode;
|
|
29
|
+
/** A sentence for the person viewing the content: the host's, else Porthole's. */
|
|
30
|
+
readonly message: string;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** The most a refusal's message carries to content. */
|
|
34
|
+
const MAX_MESSAGE = 500;
|
|
35
|
+
|
|
36
|
+
export function isRefusalCode(value: unknown): value is RefusalCode {
|
|
37
|
+
return typeof value === "string" && (REFUSAL_CODES as readonly string[]).includes(value);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* A refusal the host gives, with the reason content is told (P080). Throw it from a handler (this
|
|
42
|
+
* URI isn't one you serve: `not_allowed`; the viewer didn't allow this kind of data: `denied`), or
|
|
43
|
+
* from a `consent` function (kept as the display's answer, as `false` is). Or pass one as
|
|
44
|
+
* `HostOptions.consent` itself: every `consent`-gated call is refused with it, and those
|
|
45
|
+
* capabilities need no handler (a page where data never runs).
|
|
46
|
+
*
|
|
47
|
+
* Any other error a handler throws is `failed` with Porthole's words: its message stays the host's.
|
|
48
|
+
*/
|
|
49
|
+
export class Refused extends Error {
|
|
50
|
+
readonly code: RefusalCode;
|
|
51
|
+
|
|
52
|
+
/** `message`: a sentence for the viewer; absent, Porthole's for the code. */
|
|
53
|
+
constructor(code: RefusalCode, message?: string) {
|
|
54
|
+
if (!isRefusalCode(code)) {
|
|
55
|
+
throw new TypeError(`Refused: code must be one of ${REFUSAL_CODES.join(", ")}`);
|
|
56
|
+
}
|
|
57
|
+
super(message === undefined || message.trim() === "" ? DEFAULT_MESSAGES[code] : message);
|
|
58
|
+
this.name = "Refused";
|
|
59
|
+
this.code = code;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Whether `value` is a `Refused`: by class, or by shape where two copies of Porthole meet (a
|
|
65
|
+
* host's bundle and a library's).
|
|
66
|
+
*/
|
|
67
|
+
export function isRefused(value: unknown): value is Refused {
|
|
68
|
+
return (
|
|
69
|
+
value instanceof Refused ||
|
|
70
|
+
(value instanceof Error &&
|
|
71
|
+
value.name === "Refused" &&
|
|
72
|
+
isRefusalCode((value as { code?: unknown }).code))
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** The reason a host's `Refused` gives content. */
|
|
77
|
+
export function reasonOf(refused: Refused): RefusalReason {
|
|
78
|
+
const message = refused.message.trim();
|
|
79
|
+
return {
|
|
80
|
+
code: refused.code,
|
|
81
|
+
message: (message === "" ? DEFAULT_MESSAGES[refused.code] : message).slice(0, MAX_MESSAGE),
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Porthole's sentence for each code, where the host gave none. */
|
|
86
|
+
const DEFAULT_MESSAGES: { readonly [Code in RefusalCode]: string } = {
|
|
87
|
+
consent_required: "This needs your permission first.",
|
|
88
|
+
denied: "You didn't allow this.",
|
|
89
|
+
rate_limited: "Too many requests: try again in a minute.",
|
|
90
|
+
not_allowed: "This isn't available here.",
|
|
91
|
+
failed: "The app couldn't do this.",
|
|
92
|
+
};
|
|
93
|
+
|
|
94
|
+
/** Where a data capability's words differ: they name the data. */
|
|
95
|
+
const DATA_MESSAGES: { readonly [Code in RefusalCode]: string } = {
|
|
96
|
+
consent_required: "Reading this data needs your permission first.",
|
|
97
|
+
denied: "You didn't allow this to read your data.",
|
|
98
|
+
rate_limited: "Too many data requests: try again in a minute.",
|
|
99
|
+
not_allowed: "This data isn't available here.",
|
|
100
|
+
failed: "The app couldn't get this data.",
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
/** Each refusal's code, as content is told it. */
|
|
104
|
+
const CODES: { readonly [R in Refusal]: RefusalCode } = {
|
|
105
|
+
"not-declared": "not_allowed",
|
|
106
|
+
invalid: "not_allowed",
|
|
107
|
+
"no-user-activation": "not_allowed",
|
|
108
|
+
"no-confirm": "not_allowed",
|
|
109
|
+
declined: "denied",
|
|
110
|
+
redirected: "denied",
|
|
111
|
+
muted: "denied",
|
|
112
|
+
"no-consent": "not_allowed",
|
|
113
|
+
denied: "denied",
|
|
114
|
+
"rate-limited": "rate_limited",
|
|
115
|
+
failed: "failed",
|
|
116
|
+
};
|
|
117
|
+
|
|
118
|
+
/** Refusals whose own words say more than their code's. */
|
|
119
|
+
const OWN_MESSAGES: { readonly [R in Refusal]?: string } = {
|
|
120
|
+
"no-user-activation": "This needs a click.",
|
|
121
|
+
invalid: "The app can't take this request.",
|
|
122
|
+
muted: "You declined this too often: it isn't asked again until it runs again.",
|
|
123
|
+
};
|
|
124
|
+
|
|
125
|
+
/** What content is told about a refusal Porthole made (the host gave no `Refused`). */
|
|
126
|
+
export function defaultReason(capability: CapabilityName, refusal: Refusal): RefusalReason {
|
|
127
|
+
const code = CODES[refusal];
|
|
128
|
+
const data = capability === "readData" || capability === "subscribeData";
|
|
129
|
+
return {
|
|
130
|
+
code,
|
|
131
|
+
message: OWN_MESSAGES[refusal] ?? (data ? DATA_MESSAGES : DEFAULT_MESSAGES)[code],
|
|
132
|
+
};
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/** What content is told about a refused call: the bridge's reason, else Porthole's for it. */
|
|
136
|
+
export function reasonFor(
|
|
137
|
+
capability: CapabilityName,
|
|
138
|
+
outcome: { readonly refusal: Refusal; readonly reason?: RefusalReason },
|
|
139
|
+
): RefusalReason {
|
|
140
|
+
const reason = outcome.reason ?? defaultReason(capability, outcome.refusal);
|
|
141
|
+
return { code: reason.code, message: reason.message };
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** A consent function that failed (threw, rejected): not an answer, so asked again at the next. */
|
|
145
|
+
export function pendingReason(capability: CapabilityName): RefusalReason {
|
|
146
|
+
const data = capability === "readData" || capability === "subscribeData";
|
|
147
|
+
return {
|
|
148
|
+
code: "consent_required",
|
|
149
|
+
message: (data ? DATA_MESSAGES : DEFAULT_MESSAGES).consent_required,
|
|
150
|
+
};
|
|
151
|
+
}
|
package/src/bridge/types.ts
CHANGED
|
@@ -5,6 +5,7 @@ import type {
|
|
|
5
5
|
HandledCapability,
|
|
6
6
|
} from "../config/capabilities.ts";
|
|
7
7
|
import type { InstanceRef } from "../isolation/types.ts";
|
|
8
|
+
import type { RefusalReason } from "./refusal.ts";
|
|
8
9
|
|
|
9
10
|
/**
|
|
10
11
|
* The host-function bridge (ARCHITECTURE § Framework layer): carries a capability call from the
|
|
@@ -48,6 +49,9 @@ export type CapabilityHandlers = { readonly [N in HandledCapability]?: Capabilit
|
|
|
48
49
|
* Asked once per display before its first call of a `consent`-gated capability (P079): may this
|
|
49
50
|
* content have them (read the viewer's data)? The request is that first call. A host remembers
|
|
50
51
|
* the answer where it likes (per viewer, per widget); Porthole keeps it for the display's life.
|
|
52
|
+
* `false` is a no (content is told `denied`); a thrown `Refused` is a no with its reason, kept
|
|
53
|
+
* the same way (P080); anything else it throws is no answer yet (`consent_required`), and the next
|
|
54
|
+
* call asks again.
|
|
51
55
|
*/
|
|
52
56
|
export type Consent = (request: ConfirmRequest) => boolean | Promise<boolean>;
|
|
53
57
|
|
|
@@ -126,7 +130,14 @@ export type Refusal =
|
|
|
126
130
|
export type CallOutcome<T> =
|
|
127
131
|
/** `stale`: a `readData` answered from the host's cache (`DataCache`). */
|
|
128
132
|
| { readonly ok: true; readonly value: T; readonly stale?: true }
|
|
129
|
-
| {
|
|
133
|
+
| {
|
|
134
|
+
readonly ok: false;
|
|
135
|
+
readonly refusal: Refusal;
|
|
136
|
+
/** What the host's handler threw: the host's own words, never sent to content. */
|
|
137
|
+
readonly message?: string;
|
|
138
|
+
/** What content is told (P080): the host's `Refused`, else Porthole's for the refusal. */
|
|
139
|
+
readonly reason?: RefusalReason;
|
|
140
|
+
};
|
|
130
141
|
|
|
131
142
|
/** What an adapter adds to a call, beyond what the content sent. */
|
|
132
143
|
export interface CallOptions {
|
package/src/check/check.ts
CHANGED
|
@@ -3,7 +3,11 @@ import type { InstanceRef } from "../isolation/types.ts";
|
|
|
3
3
|
import { presets } from "../presets/presets.ts";
|
|
4
4
|
import { createServer } from "../server/server.ts";
|
|
5
5
|
import { CHECK_CONTENT_DOMAIN, CHECK_ORIGIN } from "./drivers.ts";
|
|
6
|
-
import { lintContent
|
|
6
|
+
import { lintContent } from "./lint.ts";
|
|
7
|
+
import { lintFiles, whereOf, type FileContents, type FileFinding } from "./files.ts";
|
|
8
|
+
import { DEFAULT_ENTRY, servesFiles } from "../files/paths.ts";
|
|
9
|
+
import { sha256 } from "../server/crypto.ts";
|
|
10
|
+
import type { StoredFiles } from "../server/types.ts";
|
|
7
11
|
// The check page's script, imported as a module so a bundler takes it in (P075): no file is
|
|
8
12
|
// looked up beside this one at run time.
|
|
9
13
|
import PAGE_SCRIPT from "./page-source.ts";
|
|
@@ -55,7 +59,15 @@ export interface CheckDriver {
|
|
|
55
59
|
export interface CheckOptions {
|
|
56
60
|
readonly config: PortholeConfig;
|
|
57
61
|
/** The content as the agent would send it: a fragment, or a whole document. */
|
|
58
|
-
readonly content
|
|
62
|
+
readonly content?: string;
|
|
63
|
+
/**
|
|
64
|
+
* A page that comes with files (P081), in place of `content`: every file by its path. The whole
|
|
65
|
+
* set is served, as people's browsers get it, and its entry is run and measured. Needs a served
|
|
66
|
+
* artifact config and a driver that serves (`playwrightDriver`).
|
|
67
|
+
*/
|
|
68
|
+
readonly files?: FileContents;
|
|
69
|
+
/** The page a set opens at (default `index.html`). */
|
|
70
|
+
readonly entry?: string;
|
|
59
71
|
readonly driver: CheckDriver;
|
|
60
72
|
/** Widths, px. Default: the manual's phone and desktop widths (`config.layout`). */
|
|
61
73
|
readonly widths?: readonly number[];
|
|
@@ -106,7 +118,8 @@ export interface CheckReport {
|
|
|
106
118
|
* refuses, overflow or cut, no lint error.
|
|
107
119
|
*/
|
|
108
120
|
readonly ok: boolean;
|
|
109
|
-
|
|
121
|
+
/** What the lint found (for a page with files, each finding names its file, `path`). */
|
|
122
|
+
readonly lint: readonly FileFinding[];
|
|
110
123
|
readonly runs: readonly CheckRun[];
|
|
111
124
|
/** One short summary for the agent: each problem once, with where it happened. */
|
|
112
125
|
readonly text: string;
|
|
@@ -130,9 +143,53 @@ function checkedAs(config: PortholeConfig): PortholeConfig {
|
|
|
130
143
|
|
|
131
144
|
const escapeScript = (code: string) => code.replace(/<\/script/giu, "<\\/script");
|
|
132
145
|
|
|
146
|
+
/** A set's own files named by their path, as the agent wrote them, not the frame's address. */
|
|
147
|
+
const ownPaths = (text: string): string =>
|
|
148
|
+
text.replace(/https:\/\/[a-z0-9.-]+\/__porthole\/f\/[\w-]+\//gu, "");
|
|
149
|
+
|
|
150
|
+
const hex = (bytes: Uint8Array): string =>
|
|
151
|
+
Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
|
|
152
|
+
|
|
153
|
+
/** A set's files as the check's server stores them, its entry instrumented (P081). */
|
|
154
|
+
function checkedFiles(files: FileContents, entry: string, page: string): StoredFiles {
|
|
155
|
+
const bytes = (body: string | Uint8Array): Uint8Array =>
|
|
156
|
+
typeof body === "string" ? new TextEncoder().encode(body) : body;
|
|
157
|
+
const served = new Map<string, Uint8Array>(
|
|
158
|
+
Object.entries(files).map(([path, body]) => [path, path === entry ? bytes(page) : bytes(body)]),
|
|
159
|
+
);
|
|
160
|
+
return {
|
|
161
|
+
files: Object.fromEntries(
|
|
162
|
+
[...served].map(([path, body]) => [
|
|
163
|
+
path,
|
|
164
|
+
{ size: body.byteLength, sha256: hex(sha256(body)) },
|
|
165
|
+
]),
|
|
166
|
+
),
|
|
167
|
+
entry,
|
|
168
|
+
read: (path) => Promise.resolve(served.get(path) ?? null),
|
|
169
|
+
};
|
|
170
|
+
}
|
|
171
|
+
|
|
133
172
|
export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
134
173
|
const { config } = options;
|
|
135
|
-
const
|
|
174
|
+
const entry = options.entry ?? DEFAULT_ENTRY;
|
|
175
|
+
const files = options.files;
|
|
176
|
+
if ((files === undefined) === (options.content === undefined)) {
|
|
177
|
+
throw new TypeError("checkPage takes content, or files: one of them");
|
|
178
|
+
}
|
|
179
|
+
if (files !== undefined && !servesFiles(config)) {
|
|
180
|
+
throw new TypeError("A page with files is checked under a served artifact config");
|
|
181
|
+
}
|
|
182
|
+
const entryText = (): string => {
|
|
183
|
+
const body = files?.[entry];
|
|
184
|
+
return body === undefined
|
|
185
|
+
? ""
|
|
186
|
+
: typeof body === "string"
|
|
187
|
+
? body
|
|
188
|
+
: new TextDecoder().decode(body);
|
|
189
|
+
};
|
|
190
|
+
const written = files === undefined ? (options.content ?? "") : entryText();
|
|
191
|
+
const lint: FileFinding[] =
|
|
192
|
+
files === undefined ? lintContent(config, written) : lintFiles(config, files, { entry });
|
|
136
193
|
if (config.mode === "url") {
|
|
137
194
|
return {
|
|
138
195
|
ok: true,
|
|
@@ -149,9 +206,13 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
|
149
206
|
const script = options.page ?? PAGE_SCRIPT;
|
|
150
207
|
const html = `<!doctype html><html><head><meta charset="utf-8"><title>Porthole check</title><style>body{margin:0;padding:8px}section{margin-bottom:16px}</style></head><body><script>${escapeScript(script)}</script></body></html>`;
|
|
151
208
|
// Its inline scripts named, so an error says the line in the content as written (P074).
|
|
152
|
-
const { content, scriptLines } = namedScripts(
|
|
209
|
+
const { content, scriptLines } = namedScripts(written);
|
|
153
210
|
|
|
154
211
|
const session = await options.driver.open();
|
|
212
|
+
if (files !== undefined && session.serve === undefined) {
|
|
213
|
+
await session.close();
|
|
214
|
+
throw new TypeError("A page with files is checked served: this driver can't serve (no serve)");
|
|
215
|
+
}
|
|
155
216
|
// A served config runs served, on a content origin the driver answers, under Porthole's own
|
|
156
217
|
// server: its CSP in headers, its shell, its storage and cookies (P074). Else opaque.
|
|
157
218
|
const servedHere =
|
|
@@ -163,7 +224,14 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
|
163
224
|
secret: crypto.getRandomValues(new Uint8Array(32)),
|
|
164
225
|
hostOrigins: [CHECK_ORIGIN],
|
|
165
226
|
configs: { check: servedConfig },
|
|
166
|
-
artifacts: {
|
|
227
|
+
artifacts: {
|
|
228
|
+
get: () =>
|
|
229
|
+
Promise.resolve(
|
|
230
|
+
files === undefined
|
|
231
|
+
? { html: instrumented(content) }
|
|
232
|
+
: checkedFiles(files, entry, instrumented(content)),
|
|
233
|
+
),
|
|
234
|
+
},
|
|
167
235
|
})
|
|
168
236
|
: null;
|
|
169
237
|
const handler = async (request: Request): Promise<Response> => {
|
|
@@ -240,10 +308,19 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
|
240
308
|
data?.scrollWidth !== undefined &&
|
|
241
309
|
data.clientWidth !== null &&
|
|
242
310
|
data.scrollWidth > data.clientWidth + 1,
|
|
243
|
-
errors: unique(data?.errors ?? []),
|
|
244
|
-
blocked: uniqueBy(
|
|
245
|
-
|
|
246
|
-
|
|
311
|
+
errors: unique((data?.errors ?? []).map(ownPaths)),
|
|
312
|
+
blocked: uniqueBy(
|
|
313
|
+
(data?.blocked ?? []).map((each) => ({ ...each, url: ownPaths(each.url) })),
|
|
314
|
+
(each) => `${each.url} ${each.directive}`,
|
|
315
|
+
),
|
|
316
|
+
failedLoads: uniqueBy(
|
|
317
|
+
(data?.failedLoads ?? []).map((each) => ({ ...each, url: ownPaths(each.url) })),
|
|
318
|
+
(each) => each.url,
|
|
319
|
+
),
|
|
320
|
+
console: uniqueBy(
|
|
321
|
+
(data?.console ?? []).map((each) => ({ ...each, text: ownPaths(each.text) })),
|
|
322
|
+
(each) => `${each.level} ${each.text}`,
|
|
323
|
+
),
|
|
247
324
|
calls: uniqueBy(data?.calls ?? [], (each) => `${each.capability} ${each.outcome}`),
|
|
248
325
|
...(screenshot === undefined ? {} : { screenshot }),
|
|
249
326
|
});
|
|
@@ -297,7 +374,7 @@ const clip = (text: string, most = 200) =>
|
|
|
297
374
|
*/
|
|
298
375
|
function summary(
|
|
299
376
|
config: PortholeConfig,
|
|
300
|
-
lint: readonly
|
|
377
|
+
lint: readonly FileFinding[],
|
|
301
378
|
runs: readonly CheckRun[],
|
|
302
379
|
most: number,
|
|
303
380
|
): string {
|
|
@@ -348,9 +425,10 @@ function summary(
|
|
|
348
425
|
}
|
|
349
426
|
}
|
|
350
427
|
const lines = [
|
|
351
|
-
...lint.map(
|
|
352
|
-
|
|
353
|
-
`${each.severity === "error" ? "Error" : "Warning"}${each.line === undefined ? "" : ` (line ${each.line})`}: ${each.message}
|
|
428
|
+
...lint.map((each) =>
|
|
429
|
+
each.path === undefined
|
|
430
|
+
? `${each.severity === "error" ? "Error" : "Warning"}${each.line === undefined ? "" : ` (line ${each.line})`}: ${each.message}`
|
|
431
|
+
: `${each.severity === "error" ? "Error" : "Warning"} (${whereOf(each).replace(/: $/u, "")}): ${each.message}`,
|
|
354
432
|
),
|
|
355
433
|
...[...where].map(
|
|
356
434
|
([problem, at]) =>
|