@botiverse/porthole 0.4.1 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/dist/bridge/bridge.d.ts +24 -2
- package/dist/bridge/bridge.js +102 -17
- package/dist/bridge/navigation.d.ts +11 -0
- package/dist/bridge/navigation.js +30 -0
- package/dist/bridge/refusal.d.ts +53 -0
- package/dist/bridge/refusal.js +121 -0
- package/dist/bridge/types.d.ts +51 -6
- package/dist/check/lint.js +2 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +10 -0
- package/dist/compile/policy.d.ts +5 -0
- package/dist/compile/policy.js +18 -1
- package/dist/config/capabilities.d.ts +30 -2
- package/dist/config/capabilities.js +13 -0
- package/dist/config/schema.d.ts +7 -0
- package/dist/config/validate.js +14 -3
- package/dist/conformance/harness/page.js +1 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.d.ts +1 -1
- package/dist/guide/guide.js +58 -8
- package/dist/host/create-host.js +18 -3
- package/dist/host/types.d.ts +25 -1
- package/dist/index.d.ts +5 -3
- package/dist/index.js +4 -1
- package/dist/libraries/files.generated.d.ts +1 -0
- package/dist/libraries/files.generated.js +8 -0
- package/dist/libraries/libraries.d.ts +36 -0
- package/dist/libraries/libraries.js +40 -0
- package/dist/mcp/adapter.js +49 -5
- package/dist/presets/presets.d.ts +15 -0
- package/dist/presets/presets.js +27 -2
- package/dist/protocol/live-data.d.ts +27 -0
- package/dist/protocol/live-data.js +98 -0
- package/dist/protocol/mcp-apps.d.ts +15 -0
- package/dist/protocol/mcp-apps.js +17 -0
- package/dist/protocol/shell-adapter.js +49 -4
- package/dist/react/dialog.js +2 -0
- package/dist/react/frame.d.ts +30 -1
- package/dist/react/frame.js +63 -1
- package/dist/server/libraries.d.ts +7 -0
- package/dist/server/libraries.js +27 -0
- package/dist/server/server.js +2 -1
- package/dist/shell/runtime.d.ts +5 -1
- package/dist/shell/runtime.js +196 -6
- package/docs/ADOPTING.md +89 -3
- package/docs/DECISIONS.md +221 -0
- package/docs/DESIGN.md +28 -10
- package/package.json +3 -1
- package/src/bridge/bridge.ts +136 -16
- package/src/bridge/navigation.ts +34 -0
- package/src/bridge/refusal.ts +151 -0
- package/src/bridge/types.ts +57 -4
- package/src/check/lint.ts +2 -1
- package/src/check/page.ts +12 -0
- package/src/compile/policy.ts +19 -1
- package/src/config/capabilities.ts +26 -1
- package/src/config/schema.ts +7 -0
- package/src/config/validate.ts +21 -3
- package/src/conformance/harness/page.ts +1 -0
- package/src/displays/displays.ts +1 -1
- package/src/guide/guide.ts +71 -7
- package/src/host/create-host.ts +19 -3
- package/src/host/types.ts +23 -1
- package/src/index.ts +22 -0
- package/src/libraries/files.generated.ts +8 -0
- package/src/libraries/libraries.ts +64 -0
- package/src/mcp/adapter.ts +63 -5
- package/src/presets/presets.ts +46 -3
- package/src/protocol/live-data.ts +138 -0
- package/src/protocol/mcp-apps.ts +19 -0
- package/src/protocol/shell-adapter.ts +50 -5
- package/src/react/dialog.tsx +2 -0
- package/src/react/frame.tsx +93 -0
- package/src/server/libraries.ts +28 -0
- package/src/server/server.ts +2 -1
- package/src/shell/runtime.ts +196 -6
|
@@ -0,0 +1,34 @@
|
|
|
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
|
+
/** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
|
|
11
|
+
export function addressWithoutQuery(url: string): string {
|
|
12
|
+
let parsed: URL;
|
|
13
|
+
try {
|
|
14
|
+
parsed = new URL(url);
|
|
15
|
+
} catch {
|
|
16
|
+
return "another address";
|
|
17
|
+
}
|
|
18
|
+
if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
|
|
19
|
+
return `a ${parsed.protocol} address`;
|
|
20
|
+
}
|
|
21
|
+
const rest = parsed.search !== "" || parsed.hash !== "" ? "?…" : "";
|
|
22
|
+
return `${parsed.origin}${parsed.pathname}${rest}`;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** What the content's errors say about a navigation the shell cancelled. */
|
|
26
|
+
export function blockedNavigationMessage(url: string, config: PortholeConfig): string {
|
|
27
|
+
const links =
|
|
28
|
+
config.capabilities.openLink === undefined
|
|
29
|
+
? ""
|
|
30
|
+
: config.mode === "mcp-app"
|
|
31
|
+
? " Open links with ui/open-link (a new tab)."
|
|
32
|
+
: " Open links with openLink(url) or an <a href> (a new tab).";
|
|
33
|
+
return `It tried to navigate its frame to ${addressWithoutQuery(url)}, and was stopped: content never leaves its page.${links}`;
|
|
34
|
+
}
|
|
@@ -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
|
|
@@ -23,12 +24,43 @@ export interface CallContext {
|
|
|
23
24
|
|
|
24
25
|
export type CapabilityHandler<N extends CapabilityName> = (
|
|
25
26
|
args: CapabilityArgs[N],
|
|
26
|
-
context: CallContext,
|
|
27
|
+
context: N extends "subscribeData" ? SubscriptionContext : CallContext,
|
|
27
28
|
) => CapabilityResults[N] | Promise<CapabilityResults[N]>;
|
|
28
29
|
|
|
30
|
+
/**
|
|
31
|
+
* A subscription's context (`subscribeData`, P079): how the host tells the content its resource
|
|
32
|
+
* changed, and when to stop.
|
|
33
|
+
*/
|
|
34
|
+
export interface SubscriptionContext extends CallContext {
|
|
35
|
+
/**
|
|
36
|
+
* The resource changed: the content is told (`notifications/resources/updated`) and reads it
|
|
37
|
+
* again. Pass the new `resources/read` result to answer that read without another call to
|
|
38
|
+
* `readData`.
|
|
39
|
+
*/
|
|
40
|
+
readonly changed: (result?: unknown) => void;
|
|
41
|
+
/** Aborted when the content unsubscribes, its frame stops, or the display is destroyed. */
|
|
42
|
+
readonly signal: AbortSignal;
|
|
43
|
+
}
|
|
44
|
+
|
|
29
45
|
/** The host's handlers: one for each declared capability served by a handler. */
|
|
30
46
|
export type CapabilityHandlers = { readonly [N in HandledCapability]?: CapabilityHandler<N> };
|
|
31
47
|
|
|
48
|
+
/**
|
|
49
|
+
* Asked once per display before its first call of a `consent`-gated capability (P079): may this
|
|
50
|
+
* content have them (read the viewer's data)? The request is that first call. A host remembers
|
|
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.
|
|
55
|
+
*/
|
|
56
|
+
export type Consent = (request: ConfirmRequest) => boolean | Promise<boolean>;
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* What the host last had for a resource (P079), answered at once, marked stale, to a read of a
|
|
60
|
+
* resource the content subscribes to; the fresh result follows as an update. Undefined: none.
|
|
61
|
+
*/
|
|
62
|
+
export type DataCache = (args: CapabilityArgs["readData"], context: CallContext) => unknown;
|
|
63
|
+
|
|
32
64
|
/**
|
|
33
65
|
* The display a confirmation is for, as the host named it: its id and title, and the instance the
|
|
34
66
|
* host gave it, served or opaque (P076, P077), so a host can word its dialog from its own records.
|
|
@@ -87,13 +119,34 @@ export type Refusal =
|
|
|
87
119
|
| "redirected"
|
|
88
120
|
/** The display was muted after too many declines (until it runs again). */
|
|
89
121
|
| "muted"
|
|
122
|
+
/** It is `consent`-gated and there is no `consent` function. */
|
|
123
|
+
| "no-consent"
|
|
124
|
+
/** The host's `consent` said no (for this display's life). */
|
|
125
|
+
| "denied"
|
|
90
126
|
| "rate-limited"
|
|
91
127
|
/** The host's handler threw or rejected. */
|
|
92
128
|
| "failed";
|
|
93
129
|
|
|
94
130
|
export type CallOutcome<T> =
|
|
95
|
-
|
|
96
|
-
| { readonly ok:
|
|
131
|
+
/** `stale`: a `readData` answered from the host's cache (`DataCache`). */
|
|
132
|
+
| { readonly ok: true; readonly value: T; readonly stale?: true }
|
|
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
|
+
};
|
|
141
|
+
|
|
142
|
+
/** What an adapter adds to a call, beyond what the content sent. */
|
|
143
|
+
export interface CallOptions {
|
|
144
|
+
readonly userActivated?: boolean;
|
|
145
|
+
/** `subscribeData`: the subscription's channel back and its end (`SubscriptionContext`). */
|
|
146
|
+
readonly subscription?: Pick<SubscriptionContext, "changed" | "signal">;
|
|
147
|
+
/** `readData`: the host's cache may answer, marked stale (the content subscribes to it). */
|
|
148
|
+
readonly stale?: boolean;
|
|
149
|
+
}
|
|
97
150
|
|
|
98
151
|
/** What adapters call; one per display. */
|
|
99
152
|
export interface HostFunctionBridge {
|
|
@@ -101,7 +154,7 @@ export interface HostFunctionBridge {
|
|
|
101
154
|
call<N extends CapabilityName>(
|
|
102
155
|
capability: N,
|
|
103
156
|
args: unknown,
|
|
104
|
-
options?:
|
|
157
|
+
options?: CallOptions,
|
|
105
158
|
): Promise<CallOutcome<CapabilityResults[N]>>;
|
|
106
159
|
declared(capability: CapabilityName): boolean;
|
|
107
160
|
}
|
package/src/check/lint.ts
CHANGED
|
@@ -3,6 +3,7 @@ import {
|
|
|
3
3
|
declaredCapabilities,
|
|
4
4
|
egressOrigins,
|
|
5
5
|
type EgressKind,
|
|
6
|
+
librarySources,
|
|
6
7
|
} from "../compile/policy.ts";
|
|
7
8
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
8
9
|
import { sizeWords } from "../guide/limits.ts";
|
|
@@ -217,7 +218,7 @@ export function lintContent(config: PortholeConfig, content: string): Finding[]
|
|
|
217
218
|
add(
|
|
218
219
|
"egress",
|
|
219
220
|
"warning",
|
|
220
|
-
`Nothing loads from ${origin} here (${kind}): ${kind === "script" || kind === "style" ? "write it inline, or use a library from an allowed CDN" : kind === "connect" ? "the content can't call it; work from data in the content" : "put it inline as a data: URL"}.`,
|
|
221
|
+
`Nothing loads from ${origin} here (${kind}): ${kind === "script" && librarySources(config).length > 0 ? "write it inline, or use one of the libraries served here (the manual's Libraries)" : kind === "script" || kind === "style" ? "write it inline, or use a library from an allowed CDN" : kind === "connect" && config.capabilities.readData !== undefined ? "the content can't call it; read the app's data with readData" : kind === "connect" ? "the content can't call it; work from data in the content" : "put it inline as a data: URL"}.`,
|
|
221
222
|
match.index,
|
|
222
223
|
);
|
|
223
224
|
}
|
package/src/check/page.ts
CHANGED
|
@@ -4,6 +4,7 @@ import {
|
|
|
4
4
|
isCapabilityName,
|
|
5
5
|
type HandledCapability,
|
|
6
6
|
} from "../config/capabilities.ts";
|
|
7
|
+
import { addressWithoutQuery } from "../bridge/navigation.ts";
|
|
7
8
|
import { createHost } from "../host/create-host.ts";
|
|
8
9
|
import type { PlatformHost } from "../platform/types.ts";
|
|
9
10
|
import { webPlatform } from "../platform/web.ts";
|
|
@@ -35,6 +36,9 @@ const DECLINED: { readonly [N in HandledCapability]: () => unknown } = {
|
|
|
35
36
|
readData: () => {
|
|
36
37
|
throw new Error("The host declined the read");
|
|
37
38
|
},
|
|
39
|
+
subscribeData: () => {
|
|
40
|
+
throw new Error("The host declined the subscription");
|
|
41
|
+
},
|
|
38
42
|
};
|
|
39
43
|
|
|
40
44
|
/**
|
|
@@ -166,6 +170,8 @@ const check = {
|
|
|
166
170
|
handlers: declining(Object.keys(spec.config.capabilities), calls),
|
|
167
171
|
platform: NOBODY,
|
|
168
172
|
confirm: () => Promise.resolve("declined"),
|
|
173
|
+
// A viewer who doesn't allow a live widget their data (P079): its calls are refused.
|
|
174
|
+
consent: () => false,
|
|
169
175
|
// A served config's instance, issued by the check's own server on this page's origin.
|
|
170
176
|
locator: {
|
|
171
177
|
locate: async (instance) =>
|
|
@@ -204,6 +210,12 @@ const check = {
|
|
|
204
210
|
calls.push({ capability, outcome: refusal });
|
|
205
211
|
}
|
|
206
212
|
});
|
|
213
|
+
// A navigation the shell stopped (P080): the content tried to leave its page.
|
|
214
|
+
display.on("navigationBlocked", ({ url }) => {
|
|
215
|
+
run.data.errors.push(
|
|
216
|
+
`It tried to navigate its frame to ${addressWithoutQuery(url)}, and was stopped: content never leaves its page`,
|
|
217
|
+
);
|
|
218
|
+
});
|
|
207
219
|
display.on("outcome", (outcome) => {
|
|
208
220
|
run.data.outcome = outcome.state === "blocked" ? `blocked: ${outcome.reason}` : outcome.state;
|
|
209
221
|
});
|
package/src/compile/policy.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { CAPABILITIES, type CapabilityName, type Gate } from "../config/capabilities.ts";
|
|
2
2
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
3
|
+
import { LIBRARY_PATH } from "../libraries/libraries.ts";
|
|
3
4
|
|
|
4
5
|
/**
|
|
5
6
|
* The frame's policies, derived from the config: its CSP (in the shell's `<meta>` for opaque
|
|
@@ -46,6 +47,16 @@ export function allEgressOrigins(config: PortholeConfig): string[] {
|
|
|
46
47
|
return unique(kinds.flatMap((kind) => egressOrigins(config, kind)));
|
|
47
48
|
}
|
|
48
49
|
|
|
50
|
+
/**
|
|
51
|
+
* Where Porthole's vendored libraries load from (`egress.libraries`, P079): their path on the
|
|
52
|
+
* content origins, so the frame's own, path-limited (nothing else served there runs as a script).
|
|
53
|
+
*/
|
|
54
|
+
export function librarySources(config: PortholeConfig): string[] {
|
|
55
|
+
return config.egress.libraries === true && config.isolation === "domain"
|
|
56
|
+
? config.contentOrigins.map((origin) => `${origin}${LIBRARY_PATH}`)
|
|
57
|
+
: [];
|
|
58
|
+
}
|
|
59
|
+
|
|
49
60
|
const list = (sources: readonly string[]): string[] =>
|
|
50
61
|
sources.length === 0 ? ["'none'"] : [...sources];
|
|
51
62
|
|
|
@@ -65,7 +76,14 @@ export function frameCspDirectives(config: PortholeConfig): CspDirective[] {
|
|
|
65
76
|
const https = (kind: "img" | "media" | "font") => (anyHttps(config, kind) ? ["https:"] : []);
|
|
66
77
|
return [
|
|
67
78
|
["default-src", "'none'"],
|
|
68
|
-
[
|
|
79
|
+
[
|
|
80
|
+
"script-src",
|
|
81
|
+
"'unsafe-inline'",
|
|
82
|
+
"'unsafe-eval'",
|
|
83
|
+
"blob:",
|
|
84
|
+
...origins("script"),
|
|
85
|
+
...librarySources(config),
|
|
86
|
+
],
|
|
69
87
|
["style-src", "'unsafe-inline'", ...origins("style")],
|
|
70
88
|
["font-src", "data:", ...https("font"), ...origins("font")],
|
|
71
89
|
["img-src", "data:", "blob:", ...https("img"), ...origins("img")],
|
|
@@ -16,6 +16,7 @@ export const CAPABILITY_NAMES = [
|
|
|
16
16
|
"downloadFile",
|
|
17
17
|
"callTool",
|
|
18
18
|
"readData",
|
|
19
|
+
"subscribeData",
|
|
19
20
|
"setModelContext",
|
|
20
21
|
"reportError",
|
|
21
22
|
"resize",
|
|
@@ -34,10 +35,15 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
|
|
|
34
35
|
* - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
|
|
35
36
|
* goes only if they accept. No `confirm` function means the call is refused (fail closed).
|
|
36
37
|
* - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
|
|
38
|
+
* - `consent` (P079): the host's `consent` function is asked once per display, before the first
|
|
39
|
+
* call of any of its consent-gated capabilities, whether this content may have them (a viewer
|
|
40
|
+
* allowing a widget to read their data). A no refuses every such call for the display's life;
|
|
41
|
+
* no `consent` function refuses them all (fail closed).
|
|
37
42
|
*/
|
|
38
43
|
export type Gate =
|
|
39
44
|
| "user-activation"
|
|
40
45
|
| "confirm"
|
|
46
|
+
| "consent"
|
|
41
47
|
| { readonly rateLimit: { readonly perMinute: number } };
|
|
42
48
|
|
|
43
49
|
export interface CapabilitySpec {
|
|
@@ -86,8 +92,20 @@ export const CAPABILITIES = {
|
|
|
86
92
|
readData: {
|
|
87
93
|
defaultGates: [rate(120)],
|
|
88
94
|
served: "handler",
|
|
95
|
+
global: "readData",
|
|
89
96
|
request: { method: "resources/read", sdk: "app.readServerResource" },
|
|
90
97
|
},
|
|
98
|
+
/**
|
|
99
|
+
* Live data (P079): content subscribes to a resource and the host tells it when it changed
|
|
100
|
+
* (MCP `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`);
|
|
101
|
+
* it then reads it again (`readData`, which it needs). The App SDK has no method for it.
|
|
102
|
+
*/
|
|
103
|
+
subscribeData: {
|
|
104
|
+
defaultGates: [rate(60)],
|
|
105
|
+
served: "handler",
|
|
106
|
+
global: "subscribeData",
|
|
107
|
+
request: { method: "resources/subscribe" },
|
|
108
|
+
},
|
|
91
109
|
setModelContext: {
|
|
92
110
|
defaultGates: [rate(30)],
|
|
93
111
|
served: "handler",
|
|
@@ -124,11 +142,16 @@ export interface CapabilityArgs {
|
|
|
124
142
|
readonly arguments: Readonly<Record<string, unknown>>;
|
|
125
143
|
};
|
|
126
144
|
readonly readData: { readonly uri: string };
|
|
145
|
+
readonly subscribeData: { readonly uri: string };
|
|
127
146
|
readonly setModelContext: {
|
|
128
147
|
readonly content?: readonly unknown[];
|
|
129
148
|
readonly structuredContent?: Readonly<Record<string, unknown>>;
|
|
130
149
|
};
|
|
131
|
-
|
|
150
|
+
/**
|
|
151
|
+
* `navigationBlocked`: the address a navigation of the frame went to when the shell cancelled it
|
|
152
|
+
* (P080), the content's word; `message` is then Porthole's, which names it without its query.
|
|
153
|
+
*/
|
|
154
|
+
readonly reportError: { readonly message: string; readonly navigationBlocked?: string };
|
|
132
155
|
readonly resize: { readonly height: number; readonly width?: number };
|
|
133
156
|
readonly copyText: { readonly text: string };
|
|
134
157
|
/** What the frame reported, once checked (`AnnotationReport`). */
|
|
@@ -144,7 +167,9 @@ export interface CapabilityResults {
|
|
|
144
167
|
/** Whether the download started. */
|
|
145
168
|
readonly downloadFile: boolean;
|
|
146
169
|
readonly callTool: unknown;
|
|
170
|
+
/** An MCP `resources/read` result (`{ contents }`), as the host answers it. */
|
|
147
171
|
readonly readData: unknown;
|
|
172
|
+
readonly subscribeData: undefined;
|
|
148
173
|
readonly setModelContext: undefined;
|
|
149
174
|
readonly reportError: undefined;
|
|
150
175
|
readonly resize: undefined;
|
package/src/config/schema.ts
CHANGED
|
@@ -67,6 +67,13 @@ export interface EgressConfig {
|
|
|
67
67
|
* address and a visit signal reach any site, and data can leave in the URL.
|
|
68
68
|
*/
|
|
69
69
|
readonly anyHttps?: readonly PassiveKind[];
|
|
70
|
+
/**
|
|
71
|
+
* Porthole's own copies of a few libraries (`VENDORED_LIBRARIES`: Chart.js, D3), served from the
|
|
72
|
+
* frame's own origin under `/__porthole/lib/` (P079): domain isolation only. They open no
|
|
73
|
+
* channel out: the requests reach the content server, which serves fixed files, so a display
|
|
74
|
+
* with no network of its own (`presets.liveWidget`) still draws charts.
|
|
75
|
+
*/
|
|
76
|
+
readonly libraries?: boolean;
|
|
70
77
|
}
|
|
71
78
|
|
|
72
79
|
/** What `EgressConfig.anyHttps` may open: content that runs nothing (P059). */
|
package/src/config/validate.ts
CHANGED
|
@@ -258,12 +258,12 @@ function positive(value: unknown, path: string, max = Number.MAX_SAFE_INTEGER):
|
|
|
258
258
|
}
|
|
259
259
|
|
|
260
260
|
function gate(value: unknown, path: string): asserts value is Gate {
|
|
261
|
-
if (value === "user-activation" || value === "confirm") {
|
|
261
|
+
if (value === "user-activation" || value === "confirm" || value === "consent") {
|
|
262
262
|
return;
|
|
263
263
|
}
|
|
264
264
|
const limit = isObject(value) && isObject(value.rateLimit) ? value.rateLimit : null;
|
|
265
265
|
if (limit === null || Object.keys(value as object).length !== 1) {
|
|
266
|
-
fail(path, 'must be "user-activation", "confirm" or { rateLimit: { perMinute } }');
|
|
266
|
+
fail(path, 'must be "user-activation", "confirm", "consent" or { rateLimit: { perMinute } }');
|
|
267
267
|
return;
|
|
268
268
|
}
|
|
269
269
|
only(limit, ["perMinute"], `${path}.rateLimit`);
|
|
@@ -335,7 +335,7 @@ export function validateConfig(input: unknown): PortholeConfig {
|
|
|
335
335
|
|
|
336
336
|
const egress = object(config.egress, "config.egress");
|
|
337
337
|
const kinds = ["connect", "script", "style", "img", "font", "media"];
|
|
338
|
-
only(egress, [...kinds, "anyHttps"], "config.egress");
|
|
338
|
+
only(egress, [...kinds, "anyHttps", "libraries"], "config.egress");
|
|
339
339
|
for (const kind of kinds) {
|
|
340
340
|
sources(egress[kind], `config.egress.${kind}`);
|
|
341
341
|
}
|
|
@@ -356,6 +356,24 @@ export function validateConfig(input: unknown): PortholeConfig {
|
|
|
356
356
|
}
|
|
357
357
|
}
|
|
358
358
|
|
|
359
|
+
if (egress.libraries !== undefined) {
|
|
360
|
+
if (typeof egress.libraries !== "boolean") {
|
|
361
|
+
fail("config.egress.libraries", "must be true or false");
|
|
362
|
+
}
|
|
363
|
+
if (egress.libraries && config.isolation !== "domain") {
|
|
364
|
+
fail(
|
|
365
|
+
"config.egress.libraries",
|
|
366
|
+
"Porthole's libraries are served from the frame's own origin: domain isolation only",
|
|
367
|
+
);
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
if (capabilities.subscribeData !== undefined && capabilities.readData === undefined) {
|
|
371
|
+
fail(
|
|
372
|
+
"config.capabilities.subscribeData",
|
|
373
|
+
"needs readData: content reads a resource again when it is told it changed",
|
|
374
|
+
);
|
|
375
|
+
}
|
|
376
|
+
|
|
359
377
|
const theme = object(config.theme, "config.theme");
|
|
360
378
|
only(theme, ["variables", "event", "documents"], "config.theme");
|
|
361
379
|
if (
|
|
@@ -84,6 +84,7 @@ function recorder(calls: RecordedCall[]): CapabilityHandlers {
|
|
|
84
84
|
downloadFile: record("downloadFile", true),
|
|
85
85
|
callTool: record("callTool", { content: [] }),
|
|
86
86
|
readData: record("readData", { contents: [] }),
|
|
87
|
+
subscribeData: record("subscribeData", undefined),
|
|
87
88
|
setModelContext: record("setModelContext", undefined),
|
|
88
89
|
copyText: record("copyText", true),
|
|
89
90
|
};
|
package/src/displays/displays.ts
CHANGED
|
@@ -22,7 +22,7 @@ import { presets, type PresetOptions, type UrlPresetOptions } from "../presets/p
|
|
|
22
22
|
|
|
23
23
|
export type DisplayKind =
|
|
24
24
|
| {
|
|
25
|
-
readonly preset: "inlineWidget" | "artifact" | "mcpApp";
|
|
25
|
+
readonly preset: "inlineWidget" | "liveWidget" | "artifact" | "mcpApp";
|
|
26
26
|
readonly options?: PresetOptions;
|
|
27
27
|
/** Options added when served on content origins (domain isolation): storage, egress. */
|
|
28
28
|
readonly served?: Omit<PresetOptions, "isolation" | "contentOrigins">;
|