@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/README.md
CHANGED
|
@@ -52,6 +52,31 @@ display.setContent("<p>Hello from an agent</p>");
|
|
|
52
52
|
In React: `<PortholeProvider>` around `<PortholeFrame config displayId title scheme content />` from
|
|
53
53
|
`@botiverse/porthole/react`.
|
|
54
54
|
|
|
55
|
+
## Pages made of many files
|
|
56
|
+
|
|
57
|
+
A served page may come with files of its own: a build's output, a report with its images, a
|
|
58
|
+
dashboard that reads its data (0.6). The store answers a manifest and the bytes by path, and the
|
|
59
|
+
page's relative addresses are its own version's:
|
|
60
|
+
|
|
61
|
+
```js
|
|
62
|
+
source: async (id, version) => ({
|
|
63
|
+
files: { "index.html": { size: 397, sha256: "…" }, "assets/app.js": { size: 142870, sha256: "…" } },
|
|
64
|
+
read: (path) => myStore.bytes(id, version, path), // Uint8Array or a stream, whole
|
|
65
|
+
}),
|
|
66
|
+
entry: {
|
|
67
|
+
// "/v/3/<file>" is version 3, any other path the latest's: answer with the version's own address.
|
|
68
|
+
at: async (scope, path) => {
|
|
69
|
+
const at = versionedAddress(path), version = at?.version ?? (await latestOf(scope));
|
|
70
|
+
return at && { instance: pageOf(scope, version), base: versionBase(version), file: at.file, pinned: true };
|
|
71
|
+
},
|
|
72
|
+
},
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Each file is served from the manifest only, typed by Porthole's own table, `nosniff`, with a CSP
|
|
76
|
+
that opens that version's path and nothing else of its origin; `checkFileSet` checks a version's
|
|
77
|
+
paths and limits when it is published, `lintFiles` and `checkPage({ files })` are the agent's
|
|
78
|
+
side. docs/ADOPTING.md § Pages made of many files.
|
|
79
|
+
|
|
55
80
|
## What the agent gets
|
|
56
81
|
|
|
57
82
|
```js
|
package/dist/bridge/bridge.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { type CapabilityName } from "../config/capabilities.ts";
|
|
2
2
|
import type { AnnotationReport } from "../annotate/types.ts";
|
|
3
3
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
4
|
+
import { type Refused } from "./refusal.ts";
|
|
4
5
|
import type { CapabilityHandlers, Confirm, ConfirmDisplay, Consent, DataCache, HostFunctionBridge, Refusal } from "./types.ts";
|
|
5
6
|
/**
|
|
6
7
|
* The host-function bridge: every capability call from a frame passes here, and nowhere else
|
|
@@ -15,6 +16,11 @@ export type BridgeEvent = {
|
|
|
15
16
|
} | {
|
|
16
17
|
readonly type: "error";
|
|
17
18
|
readonly message: string;
|
|
19
|
+
}
|
|
20
|
+
/** The shell cancelled a navigation of the frame to `url` (P080): the content's word. */
|
|
21
|
+
| {
|
|
22
|
+
readonly type: "navigationBlocked";
|
|
23
|
+
readonly url: string;
|
|
18
24
|
} | {
|
|
19
25
|
readonly type: "annotation";
|
|
20
26
|
readonly report: AnnotationReport;
|
|
@@ -32,9 +38,10 @@ export interface BridgeOptions {
|
|
|
32
38
|
readonly confirm?: Confirm;
|
|
33
39
|
/**
|
|
34
40
|
* Asked before a `consent`-gated call (P079). The host's, made to ask once per display by the
|
|
35
|
-
* caller (`createHost` keeps the answer across the display's frames).
|
|
41
|
+
* caller (`createHost` keeps the answer across the display's frames). A `Refused` refuses every
|
|
42
|
+
* such call with it, asking nothing (P080).
|
|
36
43
|
*/
|
|
37
|
-
readonly consent?: Consent;
|
|
44
|
+
readonly consent?: Consent | Refused;
|
|
38
45
|
/** The host's cache, for reads that may be answered stale (`CallOptions.stale`, P079). */
|
|
39
46
|
readonly cached?: DataCache;
|
|
40
47
|
/** Whether the embedding page has user activation now; undefined where it can't tell. */
|
|
@@ -47,8 +54,9 @@ export interface BridgeOptions {
|
|
|
47
54
|
export declare function linkTarget(value: unknown): string | null;
|
|
48
55
|
/**
|
|
49
56
|
* The host's `consent`, asked once (P079): the first call asks, every later one gets that answer,
|
|
50
|
-
* for as long as the returned function is kept (`createHost` keeps one per display). A
|
|
51
|
-
*
|
|
57
|
+
* for as long as the returned function is kept (`createHost` keeps one per display). A `Refused`
|
|
58
|
+
* it throws is an answer, kept and thrown again at every call (P080); anything else it throws is
|
|
59
|
+
* no answer: thrown for that call, and the next asks again.
|
|
52
60
|
*/
|
|
53
61
|
export declare function onceConsent(consent: Consent): Consent;
|
|
54
62
|
export declare function createBridge(options: BridgeOptions): HostFunctionBridge;
|
package/dist/bridge/bridge.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { MAX_COPY_CHARS, capabilitySpec, } from "../config/capabilities.js";
|
|
2
2
|
import { parseReport } from "../annotate/validate.js";
|
|
3
3
|
import { effectiveGates } from "../compile/policy.js";
|
|
4
|
+
import { blockedNavigationMessage, withoutSealedAddresses } from "./navigation.js";
|
|
5
|
+
import { defaultReason, isRefused, pendingReason, reasonOf, } from "./refusal.js";
|
|
4
6
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
5
7
|
const MAX_URL = 4_096;
|
|
6
8
|
/** An http(s) URL without credentials in it (`https://bank.example@evil.example` reads as a lie). */
|
|
@@ -72,10 +74,21 @@ const VALIDATORS = {
|
|
|
72
74
|
...(structuredContent === undefined ? {} : { structuredContent }),
|
|
73
75
|
};
|
|
74
76
|
},
|
|
75
|
-
reportError: (args) => {
|
|
77
|
+
reportError: (args, config) => {
|
|
78
|
+
// A navigation the shell cancelled (P080): Porthole words it, naming the address without its
|
|
79
|
+
// query; the address itself goes to the host whole.
|
|
80
|
+
// A frame's sealed files' address never reaches the host from here (P083): `./` instead.
|
|
81
|
+
const blocked = isRecord(args) ? args.navigationBlocked : undefined;
|
|
82
|
+
if (blocked !== undefined) {
|
|
83
|
+
if (typeof blocked !== "string" || blocked === "" || blocked.length > MAX_URL) {
|
|
84
|
+
return null;
|
|
85
|
+
}
|
|
86
|
+
const url = withoutSealedAddresses(blocked);
|
|
87
|
+
return { message: blockedNavigationMessage(url, config), navigationBlocked: url };
|
|
88
|
+
}
|
|
76
89
|
const message = isRecord(args) ? args.message : undefined;
|
|
77
90
|
return typeof message === "string" && message !== ""
|
|
78
|
-
? { message: message.slice(0, 2_000) }
|
|
91
|
+
? { message: withoutSealedAddresses(message).slice(0, 2_000) }
|
|
79
92
|
: null;
|
|
80
93
|
},
|
|
81
94
|
copyText: (args) => {
|
|
@@ -100,19 +113,30 @@ const VALIDATORS = {
|
|
|
100
113
|
};
|
|
101
114
|
/**
|
|
102
115
|
* The host's `consent`, asked once (P079): the first call asks, every later one gets that answer,
|
|
103
|
-
* for as long as the returned function is kept (`createHost` keeps one per display). A
|
|
104
|
-
*
|
|
116
|
+
* for as long as the returned function is kept (`createHost` keeps one per display). A `Refused`
|
|
117
|
+
* it throws is an answer, kept and thrown again at every call (P080); anything else it throws is
|
|
118
|
+
* no answer: thrown for that call, and the next asks again.
|
|
105
119
|
*/
|
|
106
120
|
export function onceConsent(consent) {
|
|
107
121
|
let answer = null;
|
|
108
|
-
return (request) =>
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
122
|
+
return async (request) => {
|
|
123
|
+
const asked = (answer ??= Promise.resolve()
|
|
124
|
+
.then(() => consent(request))
|
|
125
|
+
.then(
|
|
126
|
+
// Only a real yes: anything else a host's function gives is a no (fail closed).
|
|
127
|
+
(allowed) => allowed === true, (error) => {
|
|
128
|
+
if (isRefused(error)) {
|
|
129
|
+
return error;
|
|
130
|
+
}
|
|
131
|
+
answer = null;
|
|
132
|
+
throw error;
|
|
133
|
+
}));
|
|
134
|
+
const given = await asked;
|
|
135
|
+
if (typeof given !== "boolean") {
|
|
136
|
+
throw given;
|
|
137
|
+
}
|
|
138
|
+
return given;
|
|
139
|
+
};
|
|
116
140
|
}
|
|
117
141
|
export function createBridge(options) {
|
|
118
142
|
const { config, display, handlers, onEvent } = options;
|
|
@@ -120,9 +144,14 @@ export function createBridge(options) {
|
|
|
120
144
|
const calls = new Map();
|
|
121
145
|
let declines = 0;
|
|
122
146
|
let muted = false;
|
|
123
|
-
const refuse = (capability, refusal, message) => {
|
|
147
|
+
const refuse = (capability, refusal, message, reason) => {
|
|
124
148
|
onEvent({ type: "refused", capability, refusal });
|
|
125
|
-
return {
|
|
149
|
+
return {
|
|
150
|
+
ok: false,
|
|
151
|
+
refusal,
|
|
152
|
+
...(message === undefined ? {} : { message }),
|
|
153
|
+
reason: reason ?? defaultReason(capability, refusal),
|
|
154
|
+
};
|
|
126
155
|
};
|
|
127
156
|
const withinRate = (capability, perMinute) => {
|
|
128
157
|
const at = now();
|
|
@@ -162,22 +191,23 @@ export function createBridge(options) {
|
|
|
162
191
|
}
|
|
163
192
|
}
|
|
164
193
|
if (gates.includes("consent")) {
|
|
165
|
-
|
|
194
|
+
const consent = options.consent;
|
|
195
|
+
if (consent === undefined) {
|
|
166
196
|
return refuse(capability, "no-consent");
|
|
167
197
|
}
|
|
168
|
-
|
|
198
|
+
// The host's policy, known before any call: every one refused with its reason (P080).
|
|
199
|
+
if (isRefused(consent)) {
|
|
200
|
+
return refuse(capability, "denied", undefined, reasonOf(consent));
|
|
201
|
+
}
|
|
202
|
+
let answer = false;
|
|
169
203
|
try {
|
|
170
|
-
|
|
171
|
-
capability,
|
|
172
|
-
args,
|
|
173
|
-
display,
|
|
174
|
-
});
|
|
175
|
-
allowed = answer === true;
|
|
204
|
+
answer = await consent({ capability, args, display });
|
|
176
205
|
}
|
|
177
|
-
catch {
|
|
178
|
-
|
|
206
|
+
catch (error) {
|
|
207
|
+
// A Refused is the host's no, with its reason; any other failure is no answer yet.
|
|
208
|
+
return refuse(capability, "denied", undefined, isRefused(error) ? reasonOf(error) : pendingReason(capability));
|
|
179
209
|
}
|
|
180
|
-
if (
|
|
210
|
+
if (answer !== true) {
|
|
181
211
|
return refuse(capability, "denied");
|
|
182
212
|
}
|
|
183
213
|
}
|
|
@@ -224,7 +254,11 @@ export function createBridge(options) {
|
|
|
224
254
|
onEvent({ type: "annotation", report: args });
|
|
225
255
|
}
|
|
226
256
|
else {
|
|
227
|
-
|
|
257
|
+
const report = args;
|
|
258
|
+
if (report.navigationBlocked !== undefined) {
|
|
259
|
+
onEvent({ type: "navigationBlocked", url: report.navigationBlocked });
|
|
260
|
+
}
|
|
261
|
+
onEvent({ type: "error", message: report.message });
|
|
228
262
|
}
|
|
229
263
|
return { ok: true, value: undefined };
|
|
230
264
|
}
|
|
@@ -255,7 +289,8 @@ export function createBridge(options) {
|
|
|
255
289
|
return { ok: true, value: value };
|
|
256
290
|
}
|
|
257
291
|
catch (error) {
|
|
258
|
-
|
|
292
|
+
// A host's Refused tells content its reason (P080); any other error stays the host's.
|
|
293
|
+
return refuse(capability, "failed", error instanceof Error ? error.message : String(error), isRefused(error) ? reasonOf(error) : undefined);
|
|
259
294
|
}
|
|
260
295
|
}
|
|
261
296
|
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
export declare const withoutSealedAddresses: (text: string) => string;
|
|
3
|
+
/** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
|
|
4
|
+
export declare function addressWithoutQuery(url: string): string;
|
|
5
|
+
/** What the content's errors say about a navigation the shell cancelled. */
|
|
6
|
+
export declare function blockedNavigationMessage(url: string, config: PortholeConfig): string;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A navigation the shell cancelled (P079), as the host is told it (P080): the address, whole, on
|
|
3
|
+
* the `navigationBlocked` event (the host's to keep), and a sentence for the content's errors
|
|
4
|
+
* (`contentError`, which a host may give the agent that wrote it) that names the address without
|
|
5
|
+
* its query or fragment, where a viewer's data would be.
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* A frame's sealed files' address (P083) is its access: whatever content says, the host is told
|
|
9
|
+
* it as `./`, the page's own files (the shell says it so already; content may not).
|
|
10
|
+
*/
|
|
11
|
+
const SEALED = /(?:https?:\/\/[^\s"'<>/]+)?\/__porthole\/f\/[A-Za-z0-9_-]{20,}\//gu;
|
|
12
|
+
export const withoutSealedAddresses = (text) => text.replace(SEALED, "./");
|
|
13
|
+
/** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
|
|
14
|
+
export function addressWithoutQuery(url) {
|
|
15
|
+
// A page's own file (P084), as the shell names it: its path, without query or fragment.
|
|
16
|
+
if (url.startsWith("./")) {
|
|
17
|
+
const path = url.split(/[?#]/u)[0] ?? "./";
|
|
18
|
+
return path === url ? path : `${path}?…`;
|
|
19
|
+
}
|
|
20
|
+
let parsed;
|
|
21
|
+
try {
|
|
22
|
+
parsed = new URL(url);
|
|
23
|
+
}
|
|
24
|
+
catch {
|
|
25
|
+
return "another address";
|
|
26
|
+
}
|
|
27
|
+
if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
|
|
28
|
+
return `a ${parsed.protocol} address`;
|
|
29
|
+
}
|
|
30
|
+
const rest = parsed.search !== "" || parsed.hash !== "" ? "?…" : "";
|
|
31
|
+
return `${parsed.origin}${parsed.pathname}${rest}`;
|
|
32
|
+
}
|
|
33
|
+
/** What the content's errors say about a navigation the shell cancelled. */
|
|
34
|
+
export function blockedNavigationMessage(url, config) {
|
|
35
|
+
const links = config.capabilities.openLink === undefined
|
|
36
|
+
? ""
|
|
37
|
+
: config.mode === "mcp-app"
|
|
38
|
+
? " Open links with ui/open-link (a new tab)."
|
|
39
|
+
: " Open links with openLink(url) or an <a href> (a new tab).";
|
|
40
|
+
return `It tried to navigate its frame to ${addressWithoutQuery(url)}, and was stopped: content never leaves its page.${links}`;
|
|
41
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import type { CapabilityName } from "../config/capabilities.ts";
|
|
2
|
+
import type { Refusal } from "./types.ts";
|
|
3
|
+
/**
|
|
4
|
+
* Why a call was refused, as content is told (P080): a code it can branch on and a sentence it can
|
|
5
|
+
* show the person viewing it. Carried in a refused request's JSON-RPC error, as its `data`; the
|
|
6
|
+
* shell's globals reject with an error that has both (`error.code`, `error.message`).
|
|
7
|
+
*
|
|
8
|
+
* - `consent_required`: the viewer hasn't allowed it yet (their answer is still to come).
|
|
9
|
+
* - `denied`: the viewer (or the person asked to confirm) said no.
|
|
10
|
+
* - `rate_limited`: too many calls this minute.
|
|
11
|
+
* - `not_allowed`: the host doesn't let this content have it, here or at all (a URI it doesn't
|
|
12
|
+
* serve, a page where data never runs).
|
|
13
|
+
* - `failed`: the host tried and couldn't.
|
|
14
|
+
*/
|
|
15
|
+
export declare const REFUSAL_CODES: readonly ["consent_required", "denied", "rate_limited", "not_allowed", "failed"];
|
|
16
|
+
export type RefusalCode = (typeof REFUSAL_CODES)[number];
|
|
17
|
+
/** What content is told about a refusal: the JSON-RPC error's `data`. */
|
|
18
|
+
export interface RefusalReason {
|
|
19
|
+
readonly code: RefusalCode;
|
|
20
|
+
/** A sentence for the person viewing the content: the host's, else Porthole's. */
|
|
21
|
+
readonly message: string;
|
|
22
|
+
}
|
|
23
|
+
export declare function isRefusalCode(value: unknown): value is RefusalCode;
|
|
24
|
+
/**
|
|
25
|
+
* A refusal the host gives, with the reason content is told (P080). Throw it from a handler (this
|
|
26
|
+
* URI isn't one you serve: `not_allowed`; the viewer didn't allow this kind of data: `denied`), or
|
|
27
|
+
* from a `consent` function (kept as the display's answer, as `false` is). Or pass one as
|
|
28
|
+
* `HostOptions.consent` itself: every `consent`-gated call is refused with it, and those
|
|
29
|
+
* capabilities need no handler (a page where data never runs).
|
|
30
|
+
*
|
|
31
|
+
* Any other error a handler throws is `failed` with Porthole's words: its message stays the host's.
|
|
32
|
+
*/
|
|
33
|
+
export declare class Refused extends Error {
|
|
34
|
+
readonly code: RefusalCode;
|
|
35
|
+
/** `message`: a sentence for the viewer; absent, Porthole's for the code. */
|
|
36
|
+
constructor(code: RefusalCode, message?: string);
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Whether `value` is a `Refused`: by class, or by shape where two copies of Porthole meet (a
|
|
40
|
+
* host's bundle and a library's).
|
|
41
|
+
*/
|
|
42
|
+
export declare function isRefused(value: unknown): value is Refused;
|
|
43
|
+
/** The reason a host's `Refused` gives content. */
|
|
44
|
+
export declare function reasonOf(refused: Refused): RefusalReason;
|
|
45
|
+
/** What content is told about a refusal Porthole made (the host gave no `Refused`). */
|
|
46
|
+
export declare function defaultReason(capability: CapabilityName, refusal: Refusal): RefusalReason;
|
|
47
|
+
/** What content is told about a refused call: the bridge's reason, else Porthole's for it. */
|
|
48
|
+
export declare function reasonFor(capability: CapabilityName, outcome: {
|
|
49
|
+
readonly refusal: Refusal;
|
|
50
|
+
readonly reason?: RefusalReason;
|
|
51
|
+
}): RefusalReason;
|
|
52
|
+
/** A consent function that failed (threw, rejected): not an answer, so asked again at the next. */
|
|
53
|
+
export declare function pendingReason(capability: CapabilityName): RefusalReason;
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Why a call was refused, as content is told (P080): a code it can branch on and a sentence it can
|
|
3
|
+
* show the person viewing it. Carried in a refused request's JSON-RPC error, as its `data`; the
|
|
4
|
+
* shell's globals reject with an error that has both (`error.code`, `error.message`).
|
|
5
|
+
*
|
|
6
|
+
* - `consent_required`: the viewer hasn't allowed it yet (their answer is still to come).
|
|
7
|
+
* - `denied`: the viewer (or the person asked to confirm) said no.
|
|
8
|
+
* - `rate_limited`: too many calls this minute.
|
|
9
|
+
* - `not_allowed`: the host doesn't let this content have it, here or at all (a URI it doesn't
|
|
10
|
+
* serve, a page where data never runs).
|
|
11
|
+
* - `failed`: the host tried and couldn't.
|
|
12
|
+
*/
|
|
13
|
+
export const REFUSAL_CODES = [
|
|
14
|
+
"consent_required",
|
|
15
|
+
"denied",
|
|
16
|
+
"rate_limited",
|
|
17
|
+
"not_allowed",
|
|
18
|
+
"failed",
|
|
19
|
+
];
|
|
20
|
+
/** The most a refusal's message carries to content. */
|
|
21
|
+
const MAX_MESSAGE = 500;
|
|
22
|
+
export function isRefusalCode(value) {
|
|
23
|
+
return typeof value === "string" && REFUSAL_CODES.includes(value);
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* A refusal the host gives, with the reason content is told (P080). Throw it from a handler (this
|
|
27
|
+
* URI isn't one you serve: `not_allowed`; the viewer didn't allow this kind of data: `denied`), or
|
|
28
|
+
* from a `consent` function (kept as the display's answer, as `false` is). Or pass one as
|
|
29
|
+
* `HostOptions.consent` itself: every `consent`-gated call is refused with it, and those
|
|
30
|
+
* capabilities need no handler (a page where data never runs).
|
|
31
|
+
*
|
|
32
|
+
* Any other error a handler throws is `failed` with Porthole's words: its message stays the host's.
|
|
33
|
+
*/
|
|
34
|
+
export class Refused extends Error {
|
|
35
|
+
code;
|
|
36
|
+
/** `message`: a sentence for the viewer; absent, Porthole's for the code. */
|
|
37
|
+
constructor(code, message) {
|
|
38
|
+
if (!isRefusalCode(code)) {
|
|
39
|
+
throw new TypeError(`Refused: code must be one of ${REFUSAL_CODES.join(", ")}`);
|
|
40
|
+
}
|
|
41
|
+
super(message === undefined || message.trim() === "" ? DEFAULT_MESSAGES[code] : message);
|
|
42
|
+
this.name = "Refused";
|
|
43
|
+
this.code = code;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Whether `value` is a `Refused`: by class, or by shape where two copies of Porthole meet (a
|
|
48
|
+
* host's bundle and a library's).
|
|
49
|
+
*/
|
|
50
|
+
export function isRefused(value) {
|
|
51
|
+
return (value instanceof Refused ||
|
|
52
|
+
(value instanceof Error &&
|
|
53
|
+
value.name === "Refused" &&
|
|
54
|
+
isRefusalCode(value.code)));
|
|
55
|
+
}
|
|
56
|
+
/** The reason a host's `Refused` gives content. */
|
|
57
|
+
export function reasonOf(refused) {
|
|
58
|
+
const message = refused.message.trim();
|
|
59
|
+
return {
|
|
60
|
+
code: refused.code,
|
|
61
|
+
message: (message === "" ? DEFAULT_MESSAGES[refused.code] : message).slice(0, MAX_MESSAGE),
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
/** Porthole's sentence for each code, where the host gave none. */
|
|
65
|
+
const DEFAULT_MESSAGES = {
|
|
66
|
+
consent_required: "This needs your permission first.",
|
|
67
|
+
denied: "You didn't allow this.",
|
|
68
|
+
rate_limited: "Too many requests: try again in a minute.",
|
|
69
|
+
not_allowed: "This isn't available here.",
|
|
70
|
+
failed: "The app couldn't do this.",
|
|
71
|
+
};
|
|
72
|
+
/** Where a data capability's words differ: they name the data. */
|
|
73
|
+
const DATA_MESSAGES = {
|
|
74
|
+
consent_required: "Reading this data needs your permission first.",
|
|
75
|
+
denied: "You didn't allow this to read your data.",
|
|
76
|
+
rate_limited: "Too many data requests: try again in a minute.",
|
|
77
|
+
not_allowed: "This data isn't available here.",
|
|
78
|
+
failed: "The app couldn't get this data.",
|
|
79
|
+
};
|
|
80
|
+
/** Each refusal's code, as content is told it. */
|
|
81
|
+
const CODES = {
|
|
82
|
+
"not-declared": "not_allowed",
|
|
83
|
+
invalid: "not_allowed",
|
|
84
|
+
"no-user-activation": "not_allowed",
|
|
85
|
+
"no-confirm": "not_allowed",
|
|
86
|
+
declined: "denied",
|
|
87
|
+
redirected: "denied",
|
|
88
|
+
muted: "denied",
|
|
89
|
+
"no-consent": "not_allowed",
|
|
90
|
+
denied: "denied",
|
|
91
|
+
"rate-limited": "rate_limited",
|
|
92
|
+
failed: "failed",
|
|
93
|
+
};
|
|
94
|
+
/** Refusals whose own words say more than their code's. */
|
|
95
|
+
const OWN_MESSAGES = {
|
|
96
|
+
"no-user-activation": "This needs a click.",
|
|
97
|
+
invalid: "The app can't take this request.",
|
|
98
|
+
muted: "You declined this too often: it isn't asked again until it runs again.",
|
|
99
|
+
};
|
|
100
|
+
/** What content is told about a refusal Porthole made (the host gave no `Refused`). */
|
|
101
|
+
export function defaultReason(capability, refusal) {
|
|
102
|
+
const code = CODES[refusal];
|
|
103
|
+
const data = capability === "readData" || capability === "subscribeData";
|
|
104
|
+
return {
|
|
105
|
+
code,
|
|
106
|
+
message: OWN_MESSAGES[refusal] ?? (data ? DATA_MESSAGES : DEFAULT_MESSAGES)[code],
|
|
107
|
+
};
|
|
108
|
+
}
|
|
109
|
+
/** What content is told about a refused call: the bridge's reason, else Porthole's for it. */
|
|
110
|
+
export function reasonFor(capability, outcome) {
|
|
111
|
+
const reason = outcome.reason ?? defaultReason(capability, outcome.refusal);
|
|
112
|
+
return { code: reason.code, message: reason.message };
|
|
113
|
+
}
|
|
114
|
+
/** A consent function that failed (threw, rejected): not an answer, so asked again at the next. */
|
|
115
|
+
export function pendingReason(capability) {
|
|
116
|
+
const data = capability === "readData" || capability === "subscribeData";
|
|
117
|
+
return {
|
|
118
|
+
code: "consent_required",
|
|
119
|
+
message: (data ? DATA_MESSAGES : DEFAULT_MESSAGES).consent_required,
|
|
120
|
+
};
|
|
121
|
+
}
|
package/dist/bridge/types.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { CapabilityArgs, CapabilityName, CapabilityResults, HandledCapability } from "../config/capabilities.ts";
|
|
2
2
|
import type { InstanceRef } from "../isolation/types.ts";
|
|
3
|
+
import type { RefusalReason } from "./refusal.ts";
|
|
3
4
|
/**
|
|
4
5
|
* The host-function bridge (ARCHITECTURE § Framework layer): carries a capability call from the
|
|
5
6
|
* frame to the host's handler and its result back, checking at the boundary that the capability
|
|
@@ -36,6 +37,9 @@ export type CapabilityHandlers = {
|
|
|
36
37
|
* Asked once per display before its first call of a `consent`-gated capability (P079): may this
|
|
37
38
|
* content have them (read the viewer's data)? The request is that first call. A host remembers
|
|
38
39
|
* the answer where it likes (per viewer, per widget); Porthole keeps it for the display's life.
|
|
40
|
+
* `false` is a no (content is told `denied`); a thrown `Refused` is a no with its reason, kept
|
|
41
|
+
* the same way (P080); anything else it throws is no answer yet (`consent_required`), and the next
|
|
42
|
+
* call asks again.
|
|
39
43
|
*/
|
|
40
44
|
export type Consent = (request: ConfirmRequest) => boolean | Promise<boolean>;
|
|
41
45
|
/**
|
|
@@ -111,7 +115,10 @@ export type CallOutcome<T> =
|
|
|
111
115
|
} | {
|
|
112
116
|
readonly ok: false;
|
|
113
117
|
readonly refusal: Refusal;
|
|
118
|
+
/** What the host's handler threw: the host's own words, never sent to content. */
|
|
114
119
|
readonly message?: string;
|
|
120
|
+
/** What content is told (P080): the host's `Refused`, else Porthole's for the refusal. */
|
|
121
|
+
readonly reason?: RefusalReason;
|
|
115
122
|
};
|
|
116
123
|
/** What an adapter adds to a call, beyond what the content sent. */
|
|
117
124
|
export interface CallOptions {
|
package/dist/check/check.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
2
|
-
import { type
|
|
2
|
+
import { type FileContents, type FileFinding } from "./files.ts";
|
|
3
3
|
import { type CheckCall } from "./instrument.ts";
|
|
4
4
|
export type { CheckCall } from "./instrument.ts";
|
|
5
5
|
/**
|
|
@@ -34,7 +34,15 @@ export interface CheckDriver {
|
|
|
34
34
|
export interface CheckOptions {
|
|
35
35
|
readonly config: PortholeConfig;
|
|
36
36
|
/** The content as the agent would send it: a fragment, or a whole document. */
|
|
37
|
-
readonly content
|
|
37
|
+
readonly content?: string;
|
|
38
|
+
/**
|
|
39
|
+
* A page that comes with files (P081), in place of `content`: every file by its path. The whole
|
|
40
|
+
* set is served, as people's browsers get it, and its entry is run and measured. Needs a served
|
|
41
|
+
* artifact config and a driver that serves (`playwrightDriver`).
|
|
42
|
+
*/
|
|
43
|
+
readonly files?: FileContents;
|
|
44
|
+
/** The page a set opens at (default `index.html`). */
|
|
45
|
+
readonly entry?: string;
|
|
38
46
|
readonly driver: CheckDriver;
|
|
39
47
|
/** Widths, px. Default: the manual's phone and desktop widths (`config.layout`). */
|
|
40
48
|
readonly widths?: readonly number[];
|
|
@@ -92,7 +100,8 @@ export interface CheckReport {
|
|
|
92
100
|
* refuses, overflow or cut, no lint error.
|
|
93
101
|
*/
|
|
94
102
|
readonly ok: boolean;
|
|
95
|
-
|
|
103
|
+
/** What the lint found (for a page with files, each finding names its file, `path`). */
|
|
104
|
+
readonly lint: readonly FileFinding[];
|
|
96
105
|
readonly runs: readonly CheckRun[];
|
|
97
106
|
/** One short summary for the agent: each problem once, with where it happened. */
|
|
98
107
|
readonly text: string;
|
package/dist/check/check.js
CHANGED
|
@@ -2,6 +2,9 @@ import { presets } from "../presets/presets.js";
|
|
|
2
2
|
import { createServer } from "../server/server.js";
|
|
3
3
|
import { CHECK_CONTENT_DOMAIN, CHECK_ORIGIN } from "./drivers.js";
|
|
4
4
|
import { lintContent } from "./lint.js";
|
|
5
|
+
import { lintFiles, whereOf } from "./files.js";
|
|
6
|
+
import { DEFAULT_ENTRY, servesFiles } from "../files/paths.js";
|
|
7
|
+
import { sha256 } from "../server/crypto.js";
|
|
5
8
|
// The check page's script, imported as a module so a bundler takes it in (P075): no file is
|
|
6
9
|
// looked up beside this one at run time.
|
|
7
10
|
import PAGE_SCRIPT from "./page-source.js";
|
|
@@ -21,9 +24,42 @@ function checkedAs(config) {
|
|
|
21
24
|
: opaque;
|
|
22
25
|
}
|
|
23
26
|
const escapeScript = (code) => code.replace(/<\/script/giu, "<\\/script");
|
|
27
|
+
/** A set's own files named by their path, as the agent wrote them, not the frame's address. */
|
|
28
|
+
const ownPaths = (text) => text.replace(/https:\/\/[a-z0-9.-]+\/__porthole\/f\/[\w-]+\//gu, "");
|
|
29
|
+
const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
|
|
30
|
+
/** A set's files as the check's server stores them, its entry instrumented (P081). */
|
|
31
|
+
function checkedFiles(files, entry, page) {
|
|
32
|
+
const bytes = (body) => typeof body === "string" ? new TextEncoder().encode(body) : body;
|
|
33
|
+
const served = new Map(Object.entries(files).map(([path, body]) => [path, path === entry ? bytes(page) : bytes(body)]));
|
|
34
|
+
return {
|
|
35
|
+
files: Object.fromEntries([...served].map(([path, body]) => [
|
|
36
|
+
path,
|
|
37
|
+
{ size: body.byteLength, sha256: hex(sha256(body)) },
|
|
38
|
+
])),
|
|
39
|
+
entry,
|
|
40
|
+
read: (path) => Promise.resolve(served.get(path) ?? null),
|
|
41
|
+
};
|
|
42
|
+
}
|
|
24
43
|
export async function checkPage(options) {
|
|
25
44
|
const { config } = options;
|
|
26
|
-
const
|
|
45
|
+
const entry = options.entry ?? DEFAULT_ENTRY;
|
|
46
|
+
const files = options.files;
|
|
47
|
+
if ((files === undefined) === (options.content === undefined)) {
|
|
48
|
+
throw new TypeError("checkPage takes content, or files: one of them");
|
|
49
|
+
}
|
|
50
|
+
if (files !== undefined && !servesFiles(config)) {
|
|
51
|
+
throw new TypeError("A page with files is checked under a served artifact config");
|
|
52
|
+
}
|
|
53
|
+
const entryText = () => {
|
|
54
|
+
const body = files?.[entry];
|
|
55
|
+
return body === undefined
|
|
56
|
+
? ""
|
|
57
|
+
: typeof body === "string"
|
|
58
|
+
? body
|
|
59
|
+
: new TextDecoder().decode(body);
|
|
60
|
+
};
|
|
61
|
+
const written = files === undefined ? (options.content ?? "") : entryText();
|
|
62
|
+
const lint = files === undefined ? lintContent(config, written) : lintFiles(config, files, { entry });
|
|
27
63
|
if (config.mode === "url") {
|
|
28
64
|
return {
|
|
29
65
|
ok: true,
|
|
@@ -40,8 +76,12 @@ export async function checkPage(options) {
|
|
|
40
76
|
const script = options.page ?? PAGE_SCRIPT;
|
|
41
77
|
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>`;
|
|
42
78
|
// Its inline scripts named, so an error says the line in the content as written (P074).
|
|
43
|
-
const { content, scriptLines } = namedScripts(
|
|
79
|
+
const { content, scriptLines } = namedScripts(written);
|
|
44
80
|
const session = await options.driver.open();
|
|
81
|
+
if (files !== undefined && session.serve === undefined) {
|
|
82
|
+
await session.close();
|
|
83
|
+
throw new TypeError("A page with files is checked served: this driver can't serve (no serve)");
|
|
84
|
+
}
|
|
45
85
|
// A served config runs served, on a content origin the driver answers, under Porthole's own
|
|
46
86
|
// server: its CSP in headers, its shell, its storage and cookies (P074). Else opaque.
|
|
47
87
|
const servedHere = config.isolation === "domain" && config.mode !== "mcp-app" && session.serve !== undefined;
|
|
@@ -52,7 +92,11 @@ export async function checkPage(options) {
|
|
|
52
92
|
secret: crypto.getRandomValues(new Uint8Array(32)),
|
|
53
93
|
hostOrigins: [CHECK_ORIGIN],
|
|
54
94
|
configs: { check: servedConfig },
|
|
55
|
-
artifacts: {
|
|
95
|
+
artifacts: {
|
|
96
|
+
get: () => Promise.resolve(files === undefined
|
|
97
|
+
? { html: instrumented(content) }
|
|
98
|
+
: checkedFiles(files, entry, instrumented(content))),
|
|
99
|
+
},
|
|
56
100
|
})
|
|
57
101
|
: null;
|
|
58
102
|
const handler = async (request) => {
|
|
@@ -122,10 +166,10 @@ export async function checkPage(options) {
|
|
|
122
166
|
data?.scrollWidth !== undefined &&
|
|
123
167
|
data.clientWidth !== null &&
|
|
124
168
|
data.scrollWidth > data.clientWidth + 1,
|
|
125
|
-
errors: unique(data?.errors ?? []),
|
|
126
|
-
blocked: uniqueBy(data?.blocked ?? [], (each) => `${each.url} ${each.directive}`),
|
|
127
|
-
failedLoads: uniqueBy(data?.failedLoads ?? [], (each) => each.url),
|
|
128
|
-
console: uniqueBy(data?.console ?? [], (each) => `${each.level} ${each.text}`),
|
|
169
|
+
errors: unique((data?.errors ?? []).map(ownPaths)),
|
|
170
|
+
blocked: uniqueBy((data?.blocked ?? []).map((each) => ({ ...each, url: ownPaths(each.url) })), (each) => `${each.url} ${each.directive}`),
|
|
171
|
+
failedLoads: uniqueBy((data?.failedLoads ?? []).map((each) => ({ ...each, url: ownPaths(each.url) })), (each) => each.url),
|
|
172
|
+
console: uniqueBy((data?.console ?? []).map((each) => ({ ...each, text: ownPaths(each.text) })), (each) => `${each.level} ${each.text}`),
|
|
129
173
|
calls: uniqueBy(data?.calls ?? [], (each) => `${each.capability} ${each.outcome}`),
|
|
130
174
|
...(screenshot === undefined ? {} : { screenshot }),
|
|
131
175
|
});
|
|
@@ -211,7 +255,9 @@ function summary(config, lint, runs, most) {
|
|
|
211
255
|
}
|
|
212
256
|
}
|
|
213
257
|
const lines = [
|
|
214
|
-
...lint.map((each) =>
|
|
258
|
+
...lint.map((each) => each.path === undefined
|
|
259
|
+
? `${each.severity === "error" ? "Error" : "Warning"}${each.line === undefined ? "" : ` (line ${each.line})`}: ${each.message}`
|
|
260
|
+
: `${each.severity === "error" ? "Error" : "Warning"} (${whereOf(each).replace(/: $/u, "")}): ${each.message}`),
|
|
215
261
|
...[...where].map(([problem, at]) => `${problem} (at ${at.length === runs.length ? "every width and scheme" : at.join(", ")}).`),
|
|
216
262
|
];
|
|
217
263
|
const ran = `${[...new Set(runs.map((run) => `${run.width} px`))].join(" and ")}, ${[...new Set(runs.map((run) => run.scheme))].join(" and ")}`;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
import { type Finding } from "./lint.ts";
|
|
3
|
+
/**
|
|
4
|
+
* What can be told about a page that comes with files (P081), without running it: each page
|
|
5
|
+
* linted as a page is, the set held to the path rules and limits, and every relative reference
|
|
6
|
+
* looked up in the set. Errors are what certainly fails (`admitFiles` refuses them); the rest
|
|
7
|
+
* are warnings. Pure: any runtime.
|
|
8
|
+
*/
|
|
9
|
+
/** A finding about one file of the set (`path`), or about the set as a whole. */
|
|
10
|
+
export interface FileFinding extends Omit<Finding, "rule"> {
|
|
11
|
+
readonly rule: Finding["rule"] | "files" | "missing-file" | "root-path" | "file-type";
|
|
12
|
+
readonly path?: string;
|
|
13
|
+
}
|
|
14
|
+
/** A set's files, by path: text, or bytes. */
|
|
15
|
+
export type FileContents = Readonly<Record<string, string | Uint8Array>>;
|
|
16
|
+
/**
|
|
17
|
+
* Lints a page that comes with files (P081): the set (paths, limits, its entry), each page as
|
|
18
|
+
* `lintContent` lints a page, each relative reference looked up in the set (a leading `/`, which
|
|
19
|
+
* names the address's root rather than the version, is an error in a page's markup), and each
|
|
20
|
+
* file whose extension the server doesn't know (a download).
|
|
21
|
+
*/
|
|
22
|
+
export declare function lintFiles(config: PortholeConfig, files: FileContents, options?: {
|
|
23
|
+
readonly entry?: string;
|
|
24
|
+
}): FileFinding[];
|
|
25
|
+
/** Where a finding is, for the agent: `about.html line 3: `. */
|
|
26
|
+
export declare const whereOf: (finding: FileFinding) => string;
|