@botiverse/porthole 0.5.0 → 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/dist/bridge/bridge.d.ts +12 -4
- package/dist/bridge/bridge.js +58 -26
- 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 +7 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +5 -0
- package/dist/config/capabilities.d.ts +5 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/guide/guide.js +14 -4
- package/dist/host/create-host.js +15 -4
- package/dist/host/types.d.ts +15 -2
- package/dist/index.d.ts +2 -1
- package/dist/index.js +3 -1
- package/dist/mcp/adapter.js +22 -7
- package/dist/protocol/mcp-apps.d.ts +6 -0
- package/dist/protocol/mcp-apps.js +6 -0
- package/dist/protocol/shell-adapter.js +14 -2
- package/dist/react/frame.d.ts +19 -4
- package/dist/react/frame.js +37 -9
- package/dist/shell/runtime.js +34 -8
- package/docs/ADOPTING.md +39 -9
- package/docs/DECISIONS.md +92 -0
- package/docs/DESIGN.md +12 -7
- package/package.json +1 -1
- package/src/bridge/bridge.ts +70 -22
- package/src/bridge/navigation.ts +34 -0
- package/src/bridge/refusal.ts +151 -0
- package/src/bridge/types.ts +12 -1
- package/src/check/page.ts +7 -0
- package/src/config/capabilities.ts +5 -1
- package/src/guide/guide.ts +18 -4
- package/src/host/create-host.ts +16 -4
- package/src/host/types.ts +13 -2
- package/src/index.ts +9 -0
- package/src/mcp/adapter.ts +26 -6
- package/src/protocol/mcp-apps.ts +7 -0
- package/src/protocol/shell-adapter.ts +15 -2
- package/src/react/frame.tsx +53 -14
- package/src/shell/runtime.ts +34 -8
package/src/guide/guide.ts
CHANGED
|
@@ -382,7 +382,7 @@ function gateWords(gates: readonly Gate[], effect: string): string {
|
|
|
382
382
|
const sentences: string[] = [];
|
|
383
383
|
if (gates.includes("consent")) {
|
|
384
384
|
sentences.push(
|
|
385
|
-
"The first data call asks the person to allow it; if they don't, every one fails (show that the data isn't allowed, not an error).",
|
|
385
|
+
"The first data call asks the person to allow it; if they don't, every one fails with code denied (show that the data isn't allowed, not an error).",
|
|
386
386
|
);
|
|
387
387
|
}
|
|
388
388
|
if (gates.includes("confirm")) {
|
|
@@ -401,6 +401,20 @@ function gateWords(gates: readonly Gate[], effect: string): string {
|
|
|
401
401
|
return sentences.join(" ");
|
|
402
402
|
}
|
|
403
403
|
|
|
404
|
+
/**
|
|
405
|
+
* What a data refusal tells content (P080): the codes and the sentence, for the author to draw. With
|
|
406
|
+
* the shell's globals they are the error's own fields; without, the JSON-RPC error's data.
|
|
407
|
+
*/
|
|
408
|
+
function refusalWords(c: Context, global: boolean): string {
|
|
409
|
+
const where = global
|
|
410
|
+
? "The error's code says why"
|
|
411
|
+
: "A refusal is an error whose data is { code, message }; code says why";
|
|
412
|
+
return `${where}: consent_required (not allowed yet), denied (the person said no), rate_limited, not_allowed (not here: some places show the ${c.noun} without data) or failed; ${global ? "its" : ""} message is a sentence for the person. Draw the ${c.noun} without that data, with that sentence where it would be; don't retry in a loop.`.replace(
|
|
413
|
+
/ {2,}/gu,
|
|
414
|
+
" ",
|
|
415
|
+
);
|
|
416
|
+
}
|
|
417
|
+
|
|
404
418
|
const ENTRIES: { readonly [N in CapabilityName]: (c: Context, gates: readonly Gate[]) => string } =
|
|
405
419
|
{
|
|
406
420
|
sendPrompt: (c, gates) =>
|
|
@@ -417,11 +431,11 @@ const ENTRIES: { readonly [N in CapabilityName]: (c: Context, gates: readonly Ga
|
|
|
417
431
|
`- Tools: the MCP Apps request tools/call (with the App SDK, app.callServerTool). ${gateWords(gates, "the call")}`,
|
|
418
432
|
readData: (c, gates) =>
|
|
419
433
|
c.global("readData")
|
|
420
|
-
? `- readData(uri): reads the app's data at uri (a resource the app names), as the person viewing the ${c.noun} may see it, and returns a promise of it: JSON parsed, else text. ${gateWords(gates, "the request")} It rejects when the app refuses or fails
|
|
421
|
-
: `- Data: the MCP Apps request resources/read (with the App SDK, app.readServerResource). ${gateWords(gates, "the request")}`,
|
|
434
|
+
? `- readData(uri): reads the app's data at uri (a resource the app names), as the person viewing the ${c.noun} may see it, and returns a promise of it: JSON parsed, else text. ${gateWords(gates, "the request")} It rejects when the app refuses or fails. ${refusalWords(c, true)}`
|
|
435
|
+
: `- Data: the MCP Apps request resources/read (with the App SDK, app.readServerResource). ${gateWords(gates, "the request")} ${refusalWords(c, false)}`,
|
|
422
436
|
subscribeData: (c, gates) =>
|
|
423
437
|
c.global("subscribeData")
|
|
424
|
-
? `- subscribeData(uri, onData, onError): keeps the ${c.noun} current. It calls onData(value, { stale }) with the data at uri now, and again each time it changes; the first value may be the app's last copy (stale: true), with the current one right after. It returns a function that stops it. onError(error) hears a refusal. ${gateWords(gates, "the request")} Draw from onData every time; don't poll.`
|
|
438
|
+
? `- subscribeData(uri, onData, onError): keeps the ${c.noun} current. It calls onData(value, { stale }) with the data at uri now, and again each time it changes; the first value may be the app's last copy (stale: true), with the current one right after. It returns a function that stops it. onError(error) hears a refusal, with the same code and message as readData's. ${gateWords(gates, "the request")} Draw from onData every time; don't poll.`
|
|
425
439
|
: `- Live data: the MCP request resources/subscribe with { uri }; the app then sends notifications/resources/updated with { uri } each time it changes: read it again (resources/read). resources/unsubscribe stops it. ${gateWords(gates, "the request")}`,
|
|
426
440
|
setModelContext: (_c, gates) =>
|
|
427
441
|
`- Context for the agent: the MCP Apps request ui/update-model-context (with the App SDK, app.updateModelContext). ${gateWords(gates, "it")}`,
|
package/src/host/create-host.ts
CHANGED
|
@@ -8,7 +8,8 @@ import { annotateMode, checkMarks, parseReport } from "../annotate/validate.ts";
|
|
|
8
8
|
import { createBridge, onceConsent, type BridgeEvent } from "../bridge/bridge.ts";
|
|
9
9
|
import type { HostFunctionBridge } from "../bridge/types.ts";
|
|
10
10
|
import { compile } from "../compile/compile.ts";
|
|
11
|
-
import { declaredCapabilities } from "../compile/policy.ts";
|
|
11
|
+
import { declaredCapabilities, effectiveGates } from "../compile/policy.ts";
|
|
12
|
+
import { isRefused } from "../bridge/refusal.ts";
|
|
12
13
|
import { capabilitySpec } from "../config/capabilities.ts";
|
|
13
14
|
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
14
15
|
import { locateServed } from "./locate.ts";
|
|
@@ -79,10 +80,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
79
80
|
compiled,
|
|
80
81
|
mount(container: HTMLElement, mount: MountOptions): DisplayHandle<C> {
|
|
81
82
|
const handlers = { ...options.handlers, ...mount.handlers };
|
|
83
|
+
// A host whose consent is a Refused refuses every consent-gated call before its handler:
|
|
84
|
+
// those need none (P080).
|
|
85
|
+
const refusesAll = isRefused(options.consent);
|
|
82
86
|
const missing = declaredCapabilities(config).filter(
|
|
83
87
|
(name) =>
|
|
84
88
|
capabilitySpec(name).served === "handler" &&
|
|
85
|
-
(handlers as Record<string, unknown>)[name] === undefined
|
|
89
|
+
(handlers as Record<string, unknown>)[name] === undefined &&
|
|
90
|
+
!(refusesAll && effectiveGates(config, name).includes("consent")),
|
|
86
91
|
);
|
|
87
92
|
if (missing.length > 0) {
|
|
88
93
|
throw new TypeError(`No handler for the declared capabilities: ${missing.join(", ")}`);
|
|
@@ -117,8 +122,12 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
117
122
|
let destroyed = false;
|
|
118
123
|
let restarts = 0;
|
|
119
124
|
let generation = 0;
|
|
120
|
-
// The viewer's answer for this display (P079): asked once, kept across its frames
|
|
121
|
-
|
|
125
|
+
// The viewer's answer for this display (P079): asked once, kept across its frames; or the
|
|
126
|
+
// host's refusal of them all (P080).
|
|
127
|
+
const consent =
|
|
128
|
+
options.consent === undefined || isRefused(options.consent)
|
|
129
|
+
? options.consent
|
|
130
|
+
: onceConsent(options.consent);
|
|
122
131
|
let abort: AbortController | null = null;
|
|
123
132
|
let outcomeWatch: OutcomeWatch | null = null;
|
|
124
133
|
let themeFrame: number | null = null;
|
|
@@ -291,6 +300,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
291
300
|
});
|
|
292
301
|
return;
|
|
293
302
|
}
|
|
303
|
+
case "navigationBlocked":
|
|
304
|
+
emit("navigationBlocked", { url: event.url });
|
|
305
|
+
return;
|
|
294
306
|
case "error":
|
|
295
307
|
contentError(event.message);
|
|
296
308
|
return;
|
package/src/host/types.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
|
|
2
|
+
import type { Refused } from "../bridge/refusal.ts";
|
|
2
3
|
import type { Confirm, CapabilityHandlers, Consent, DataCache, Refusal } from "../bridge/types.ts";
|
|
3
4
|
import type { CompiledConfig } from "../compile/compile.ts";
|
|
4
5
|
import type { CapabilityName } from "../config/capabilities.ts";
|
|
@@ -22,9 +23,11 @@ export interface HostOptions<C extends AdapterConnection = ShellConnection> {
|
|
|
22
23
|
/**
|
|
23
24
|
* Whether a display may make its `consent`-gated calls (read the viewer's data, P079): asked
|
|
24
25
|
* once per display, before the first, and kept for the display's life (its reloads too).
|
|
25
|
-
* Absent: those calls are refused.
|
|
26
|
+
* Absent: those calls are refused. A `Refused` instead of a function refuses every one with its
|
|
27
|
+
* reason, asking nothing, and those capabilities need no handler (a page where live data must
|
|
28
|
+
* not run, P080).
|
|
26
29
|
*/
|
|
27
|
-
readonly consent?: Consent;
|
|
30
|
+
readonly consent?: Consent | Refused;
|
|
28
31
|
/**
|
|
29
32
|
* What the host last had for a resource (P079): a read of one the content subscribes to is
|
|
30
33
|
* answered with it at once, marked stale, then with the handler's fresh result.
|
|
@@ -154,6 +157,14 @@ export interface DisplayEvents {
|
|
|
154
157
|
readonly error: { readonly message: string; readonly source: "content" | "host" };
|
|
155
158
|
/** The content navigated its frame away; the frame was started again from its content. */
|
|
156
159
|
readonly navigated: undefined;
|
|
160
|
+
/**
|
|
161
|
+
* The shell stopped the content navigating its frame to `url` (P079, P080): the address whole,
|
|
162
|
+
* as the content gave it (its word: untrusted, may carry data in its query). Only where the
|
|
163
|
+
* config declares `reportError` (it counts as one of the run's reports), and only in frames with
|
|
164
|
+
* an origin of their own (served): an opaque frame's navigations get no events. A
|
|
165
|
+
* `contentError` follows, naming the address without its query or fragment.
|
|
166
|
+
*/
|
|
167
|
+
readonly navigationBlocked: { readonly url: string };
|
|
157
168
|
/** A call didn't run. */
|
|
158
169
|
readonly refused: { readonly capability: CapabilityName; readonly refusal: Refusal };
|
|
159
170
|
/** Too many declines: the display stops asking until it runs again. */
|
package/src/index.ts
CHANGED
|
@@ -122,10 +122,19 @@ export {
|
|
|
122
122
|
MCP_APPS_METHODS,
|
|
123
123
|
MCP_APPS_PROTOCOL_VERSION,
|
|
124
124
|
MCP_APPS_STYLE_VARIABLES,
|
|
125
|
+
NAVIGATION_BLOCKED_METHOD,
|
|
125
126
|
PORTHOLE_STYLES,
|
|
126
127
|
STALE_META,
|
|
127
128
|
type HostContext,
|
|
128
129
|
} from "./protocol/mcp-apps.ts";
|
|
130
|
+
// Why a call was refused, as content is told it, and the host's own refusals (P080).
|
|
131
|
+
export {
|
|
132
|
+
REFUSAL_CODES,
|
|
133
|
+
Refused,
|
|
134
|
+
isRefused,
|
|
135
|
+
type RefusalCode,
|
|
136
|
+
type RefusalReason,
|
|
137
|
+
} from "./bridge/refusal.ts";
|
|
129
138
|
export type {
|
|
130
139
|
CallContext,
|
|
131
140
|
CallOptions,
|
package/src/mcp/adapter.ts
CHANGED
|
@@ -14,8 +14,13 @@ import {
|
|
|
14
14
|
MCP_APPS_PROTOCOL_VERSION,
|
|
15
15
|
type HostContext,
|
|
16
16
|
} from "../protocol/mcp-apps.ts";
|
|
17
|
-
import {
|
|
17
|
+
import {
|
|
18
|
+
COPY_TEXT_METHOD,
|
|
19
|
+
MCP_APPS_STYLE_VARIABLES,
|
|
20
|
+
NAVIGATION_BLOCKED_METHOD,
|
|
21
|
+
} from "../protocol/mcp-apps.ts";
|
|
18
22
|
import { liveData } from "../protocol/live-data.ts";
|
|
23
|
+
import { reasonFor } from "../bridge/refusal.ts";
|
|
19
24
|
|
|
20
25
|
/**
|
|
21
26
|
* The MCP Apps adapter (P004, P007): the host side of the protocol for full MCP Apps views, written
|
|
@@ -190,12 +195,13 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
|
|
|
190
195
|
refuse(request.id, JSON_RPC_ERRORS.internal, `${request.method} failed`);
|
|
191
196
|
return;
|
|
192
197
|
}
|
|
193
|
-
reply(request, outcome, result);
|
|
198
|
+
reply(request, capability, outcome, result);
|
|
194
199
|
}
|
|
195
200
|
|
|
196
201
|
/** Answers a request with a capability's outcome. */
|
|
197
202
|
function reply(
|
|
198
203
|
request: JsonRpcRequest,
|
|
204
|
+
capability: CapabilityName,
|
|
199
205
|
outcome: CallOutcome<unknown>,
|
|
200
206
|
result: (value: unknown) => unknown,
|
|
201
207
|
): void {
|
|
@@ -204,8 +210,17 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
|
|
|
204
210
|
} else if (outcome.refusal === "not-declared") {
|
|
205
211
|
refuse(request.id, JSON_RPC_ERRORS.methodNotFound, `${request.method} isn't offered here`);
|
|
206
212
|
} else {
|
|
207
|
-
// The spec's "implementation-defined" error for a refused request
|
|
208
|
-
|
|
213
|
+
// The spec's "implementation-defined" error for a refused request, with why in its data
|
|
214
|
+
// (`{ code, message }`, P080).
|
|
215
|
+
send({
|
|
216
|
+
jsonrpc: "2.0",
|
|
217
|
+
id: request.id,
|
|
218
|
+
error: {
|
|
219
|
+
code: -32_000,
|
|
220
|
+
message: `${request.method} refused (${outcome.refusal})`,
|
|
221
|
+
data: reasonFor(capability, outcome),
|
|
222
|
+
},
|
|
223
|
+
});
|
|
209
224
|
}
|
|
210
225
|
}
|
|
211
226
|
|
|
@@ -275,7 +290,7 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
|
|
|
275
290
|
invalid("needs a uri");
|
|
276
291
|
return;
|
|
277
292
|
}
|
|
278
|
-
reply(request, await live.read(params.uri), (value) =>
|
|
293
|
+
reply(request, "readData", await live.read(params.uri), (value) =>
|
|
279
294
|
isRecord(value) ? value : { contents: [] },
|
|
280
295
|
);
|
|
281
296
|
return;
|
|
@@ -298,7 +313,7 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
|
|
|
298
313
|
answer(request.id, {});
|
|
299
314
|
return;
|
|
300
315
|
}
|
|
301
|
-
reply(request, await live.subscribe(params.uri), () => ({}));
|
|
316
|
+
reply(request, "subscribeData", await live.subscribe(params.uri), () => ({}));
|
|
302
317
|
return;
|
|
303
318
|
case MCP_APPS_METHODS.updateModelContext:
|
|
304
319
|
if (
|
|
@@ -388,6 +403,11 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
|
|
|
388
403
|
});
|
|
389
404
|
}
|
|
390
405
|
return;
|
|
406
|
+
case NAVIGATION_BLOCKED_METHOD:
|
|
407
|
+
// The shell, hardening the view's frame, stopped a navigation (P080): an error report,
|
|
408
|
+
// with its address.
|
|
409
|
+
void bridge.call("reportError", { navigationBlocked: params.url });
|
|
410
|
+
return;
|
|
391
411
|
case MCP_APPS_METHODS.requestTeardown:
|
|
392
412
|
session.emit({ type: "teardown-requested" });
|
|
393
413
|
return;
|
package/src/protocol/mcp-apps.ts
CHANGED
|
@@ -133,6 +133,13 @@ export const COPY_TEXT_METHOD = "porthole/copy-text";
|
|
|
133
133
|
*/
|
|
134
134
|
export const STALE_META = "porthole/stale";
|
|
135
135
|
|
|
136
|
+
/**
|
|
137
|
+
* Porthole's own notification from the shell (P080): it cancelled a navigation of the frame to
|
|
138
|
+
* `{ url }` (P079). The content's word, sent only where `reportError` is declared, and counted as
|
|
139
|
+
* one of its reports; the host's adapter carries it into `reportError`.
|
|
140
|
+
*/
|
|
141
|
+
export const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
|
|
142
|
+
|
|
136
143
|
/** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
|
|
137
144
|
export const SHELL_LOGGER = "porthole";
|
|
138
145
|
|
|
@@ -8,8 +8,10 @@ import {
|
|
|
8
8
|
type JsonRpcRequest,
|
|
9
9
|
type JsonRpcResponse,
|
|
10
10
|
} from "./jsonrpc.ts";
|
|
11
|
+
import { reasonFor, type RefusalReason } from "../bridge/refusal.ts";
|
|
11
12
|
import {
|
|
12
13
|
COPY_TEXT_METHOD,
|
|
14
|
+
NAVIGATION_BLOCKED_METHOD,
|
|
13
15
|
MCP_APPS_METHODS as M,
|
|
14
16
|
MCP_APPS_PROTOCOL_VERSION,
|
|
15
17
|
type HostContext,
|
|
@@ -67,7 +69,7 @@ const REQUESTS: Readonly<
|
|
|
67
69
|
function answer(
|
|
68
70
|
capability: CapabilityName,
|
|
69
71
|
outcome: CallOutcome<unknown>,
|
|
70
|
-
): { result: unknown } | { error: { code: number; message: string } } {
|
|
72
|
+
): { result: unknown } | { error: { code: number; message: string; data?: RefusalReason } } {
|
|
71
73
|
const flagged =
|
|
72
74
|
capability === "sendPrompt" ||
|
|
73
75
|
capability === "openLink" ||
|
|
@@ -76,7 +78,14 @@ function answer(
|
|
|
76
78
|
if (!outcome.ok) {
|
|
77
79
|
return flagged
|
|
78
80
|
? { result: { isError: true } }
|
|
79
|
-
: {
|
|
81
|
+
: {
|
|
82
|
+
// Why, in the error's data (`{ code, message }`, P080).
|
|
83
|
+
error: {
|
|
84
|
+
code: -32000,
|
|
85
|
+
message: `Refused (${outcome.refusal})`,
|
|
86
|
+
data: reasonFor(capability, outcome),
|
|
87
|
+
},
|
|
88
|
+
};
|
|
80
89
|
}
|
|
81
90
|
if (flagged) {
|
|
82
91
|
return { result: outcome.value === true ? {} : { isError: true } };
|
|
@@ -236,6 +245,10 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
|
|
|
236
245
|
});
|
|
237
246
|
}
|
|
238
247
|
return;
|
|
248
|
+
case NAVIGATION_BLOCKED_METHOD:
|
|
249
|
+
// The shell stopped a navigation (P080): an error report, with its address.
|
|
250
|
+
void bridge.call("reportError", { navigationBlocked: params.url });
|
|
251
|
+
return;
|
|
239
252
|
case M.requestTeardown:
|
|
240
253
|
session.emit({ type: "teardown-requested" });
|
|
241
254
|
return;
|
package/src/react/frame.tsx
CHANGED
|
@@ -27,6 +27,7 @@ import type {
|
|
|
27
27
|
Proceed,
|
|
28
28
|
Refusal,
|
|
29
29
|
} from "../bridge/types.ts";
|
|
30
|
+
import { isRefused, reasonOf, Refused, type RefusalReason } from "../bridge/refusal.ts";
|
|
30
31
|
import type { CapabilityName } from "../config/capabilities.ts";
|
|
31
32
|
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
32
33
|
import { writeClipboard } from "../host/clipboard.ts";
|
|
@@ -65,6 +66,8 @@ interface PageState {
|
|
|
65
66
|
readonly confirm?: Confirm;
|
|
66
67
|
/** The provider's consent and cache (P079), read when a frame asks. */
|
|
67
68
|
readonly consent?: Consent;
|
|
69
|
+
/** The provider's consent is a `Refused` (P080): its reason, by value. */
|
|
70
|
+
readonly refusesAll?: RefusalReason;
|
|
68
71
|
readonly cached?: DataCache;
|
|
69
72
|
readonly hostInfo?: { readonly name: string; readonly version: string };
|
|
70
73
|
readonly nonce?: string;
|
|
@@ -127,9 +130,10 @@ export interface PortholeProviderProps {
|
|
|
127
130
|
readonly confirm?: Confirm;
|
|
128
131
|
/**
|
|
129
132
|
* Whether a frame below may make its `consent`-gated calls (read the viewer's data, P079):
|
|
130
|
-
* asked once per display, before the first. Omitted: those calls are refused.
|
|
133
|
+
* asked once per display, before the first. Omitted: those calls are refused. A `Refused`
|
|
134
|
+
* refuses them all with its reason, and their handlers may be left out (P080).
|
|
131
135
|
*/
|
|
132
|
-
readonly consent?: Consent;
|
|
136
|
+
readonly consent?: Consent | Refused;
|
|
133
137
|
/** What the host last had for a resource, answered stale first (P079). */
|
|
134
138
|
readonly cached?: DataCache;
|
|
135
139
|
/** How the host names itself in the handshake. */
|
|
@@ -204,7 +208,15 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
|
|
|
204
208
|
ownConsent.current = props.consent;
|
|
205
209
|
ownCached.current = props.cached;
|
|
206
210
|
});
|
|
207
|
-
const consent = useCallback<Consent>((request) =>
|
|
211
|
+
const consent = useCallback<Consent>((request) => {
|
|
212
|
+
const given = ownConsent.current;
|
|
213
|
+
if (isRefused(given)) {
|
|
214
|
+
throw given;
|
|
215
|
+
}
|
|
216
|
+
return given?.(request) ?? false;
|
|
217
|
+
}, []);
|
|
218
|
+
// A Refused for every frame below, by value (an inline one starts nothing again).
|
|
219
|
+
const refusesAll = useByValue(isRefused(props.consent) ? reasonOf(props.consent) : undefined);
|
|
208
220
|
const cached = useCallback<DataCache>((args, context) => ownCached.current?.(args, context), []);
|
|
209
221
|
const consents = props.consent !== undefined;
|
|
210
222
|
const caches = props.cached !== undefined;
|
|
@@ -284,6 +296,7 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
|
|
|
284
296
|
confirm,
|
|
285
297
|
copyText,
|
|
286
298
|
...(consents ? { consent } : {}),
|
|
299
|
+
...(refusesAll === undefined ? {} : { refusesAll }),
|
|
287
300
|
...(caches ? { cached } : {}),
|
|
288
301
|
...(hostInfo === undefined ? {} : { hostInfo }),
|
|
289
302
|
...(locates ? { locate } : {}),
|
|
@@ -301,6 +314,7 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
|
|
|
301
314
|
copyText,
|
|
302
315
|
consents,
|
|
303
316
|
consent,
|
|
317
|
+
refusesAll,
|
|
304
318
|
caches,
|
|
305
319
|
cached,
|
|
306
320
|
hostInfo,
|
|
@@ -401,8 +415,11 @@ export interface PortholeFrameProps {
|
|
|
401
415
|
readonly handlers?: CapabilityHandlers;
|
|
402
416
|
/** Who confirms this frame's gated calls, over the provider's. */
|
|
403
417
|
readonly confirm?: Confirm;
|
|
404
|
-
/**
|
|
405
|
-
|
|
418
|
+
/**
|
|
419
|
+
* Whether this frame may make its `consent`-gated calls, over the provider's (P079). A `Refused`
|
|
420
|
+
* refuses them all with its reason, and their handlers may be left out (P080).
|
|
421
|
+
*/
|
|
422
|
+
readonly consent?: Consent | Refused;
|
|
406
423
|
/** This frame's data cache, over the provider's (P079). */
|
|
407
424
|
readonly cached?: DataCache;
|
|
408
425
|
/** Bump to run the content again from the start. */
|
|
@@ -436,6 +453,12 @@ export interface PortholeFrameProps {
|
|
|
436
453
|
readonly onError?: (message: string, source: "content" | "host") => void;
|
|
437
454
|
/** The content navigated its frame away; it was started again (or stopped, after a few). */
|
|
438
455
|
readonly onNavigated?: () => void;
|
|
456
|
+
/**
|
|
457
|
+
* The shell stopped the content navigating its frame to `url` (P080): the address whole, the
|
|
458
|
+
* content's word. Served frames only, where the config declares `reportError`; `onContentError`
|
|
459
|
+
* hears it too, without the address's query.
|
|
460
|
+
*/
|
|
461
|
+
readonly onNavigationBlocked?: (blocked: { readonly url: string }) => void;
|
|
439
462
|
readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
|
|
440
463
|
/** Too many declines: the display stops asking until it runs again. */
|
|
441
464
|
readonly onMuted?: () => void;
|
|
@@ -642,6 +665,10 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
642
665
|
const config = useByValue(frame.config);
|
|
643
666
|
const instance = useByValue(frame.instance);
|
|
644
667
|
const fills = config.mode === "url" || frame.fill === true || config.layout.kind === "fill";
|
|
668
|
+
// A consent that refuses everything (P080), this frame's or else the provider's, by value: a
|
|
669
|
+
// display made with it needs no data handlers, so a change makes the display again.
|
|
670
|
+
const ownRefusal = useByValue(isRefused(frame.consent) ? reasonOf(frame.consent) : undefined);
|
|
671
|
+
const refusesAll = frame.consent === undefined ? page.refusesAll : ownRefusal;
|
|
645
672
|
|
|
646
673
|
// The latest props, read when the display calls back (never during render).
|
|
647
674
|
const latest = useEffectEvent(() => frame);
|
|
@@ -691,6 +718,9 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
691
718
|
case "navigated":
|
|
692
719
|
frame.onNavigated?.();
|
|
693
720
|
return;
|
|
721
|
+
case "navigationBlocked":
|
|
722
|
+
frame.onNavigationBlocked?.(detail as DisplayEvents["navigationBlocked"]);
|
|
723
|
+
return;
|
|
694
724
|
case "refused": {
|
|
695
725
|
const { capability, refusal } = detail as DisplayEvents["refused"];
|
|
696
726
|
frame.onRefused?.(capability, refusal);
|
|
@@ -767,15 +797,22 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
767
797
|
),
|
|
768
798
|
}
|
|
769
799
|
: {}),
|
|
770
|
-
...(
|
|
771
|
-
? {
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
800
|
+
...(refusesAll !== undefined
|
|
801
|
+
? { consent: new Refused(refusesAll.code, refusesAll.message) }
|
|
802
|
+
: asksConsent
|
|
803
|
+
? {
|
|
804
|
+
consent: (request: ConfirmRequest) => {
|
|
805
|
+
const given = latest().consent ?? pageConsent ?? (() => false);
|
|
806
|
+
if (isRefused(given)) {
|
|
807
|
+
throw given;
|
|
808
|
+
}
|
|
809
|
+
return given({
|
|
810
|
+
...request,
|
|
811
|
+
display: { ...request.display, id: latest().displayId, title: latest().title },
|
|
812
|
+
});
|
|
813
|
+
},
|
|
814
|
+
}
|
|
815
|
+
: {}),
|
|
779
816
|
...(caches
|
|
780
817
|
? {
|
|
781
818
|
cached: (args: { readonly uri: string }, context: CallContext) =>
|
|
@@ -805,6 +842,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
805
842
|
"resize",
|
|
806
843
|
"error",
|
|
807
844
|
"navigated",
|
|
845
|
+
"navigationBlocked",
|
|
808
846
|
"refused",
|
|
809
847
|
"muted",
|
|
810
848
|
"outcome",
|
|
@@ -839,6 +877,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
839
877
|
pageConfirm,
|
|
840
878
|
pageConsent,
|
|
841
879
|
pageCached,
|
|
880
|
+
refusesAll,
|
|
842
881
|
hostInfo,
|
|
843
882
|
locate,
|
|
844
883
|
nonce,
|
package/src/shell/runtime.ts
CHANGED
|
@@ -85,7 +85,9 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
85
85
|
// own getters, kept now, so content can neither stop it nor lie to it. Same-document ones (an
|
|
86
86
|
// anchor) go on, and so do reloads: the same address, on the frame's own origin (or none, in a
|
|
87
87
|
// srcdoc frame), which history can change only within that origin. The host's own (a new
|
|
88
|
-
// frame) are none of this document's.
|
|
88
|
+
// frame) are none of this document's. Each one stopped is told to the host (P080), as an error
|
|
89
|
+
// report: below, once the shell can speak.
|
|
90
|
+
let navigationBlocked = (_url) => {};
|
|
89
91
|
const navigationApi = window.navigation;
|
|
90
92
|
const getterOf = (proto, name) => {
|
|
91
93
|
const descriptor = proto ? Object.getOwnPropertyDescriptor(proto, name) : undefined;
|
|
@@ -94,13 +96,17 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
94
96
|
const navigateProto = typeof NavigateEvent === "function" ? NavigateEvent.prototype : null;
|
|
95
97
|
const destinationOf = getterOf(navigateProto, "destination");
|
|
96
98
|
const navigationTypeOf = getterOf(navigateProto, "navigationType");
|
|
97
|
-
const
|
|
99
|
+
const destinationProto = typeof NavigationDestination === "function" ? NavigationDestination.prototype : null;
|
|
100
|
+
const sameDocumentOf = getterOf(destinationProto, "sameDocument");
|
|
101
|
+
const urlOf = getterOf(destinationProto, "url");
|
|
98
102
|
const preventNavigation = Event.prototype.preventDefault;
|
|
99
103
|
const applyOf = Reflect.apply;
|
|
100
104
|
if (navigationApi && typeof navigationApi.addEventListener === "function" && destinationOf !== null && sameDocumentOf !== null && navigationTypeOf !== null) {
|
|
101
105
|
navigationApi.addEventListener("navigate", (event) => {
|
|
102
|
-
|
|
106
|
+
const destination = applyOf(destinationOf, event, []);
|
|
107
|
+
if (!applyOf(sameDocumentOf, destination, []) && applyOf(navigationTypeOf, event, []) !== "reload") {
|
|
103
108
|
applyOf(preventNavigation, event, []);
|
|
109
|
+
navigationBlocked(urlOf === null ? "" : String(applyOf(urlOf, destination, [])));
|
|
104
110
|
}
|
|
105
111
|
}, true);
|
|
106
112
|
}
|
|
@@ -475,13 +481,27 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
475
481
|
reported += 1;
|
|
476
482
|
send({ method: "notifications/message", params: { level: "error", logger: "porthole", data: String(message).slice(0, 2000) } });
|
|
477
483
|
};
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
484
|
+
// Nothing secret is ever said from here, so any parent may hear it; what it hears is the
|
|
485
|
+
// content's word, which the host gates before it acts on it.
|
|
486
|
+
const post = (message) => {
|
|
487
|
+
if (window.parent !== window) {
|
|
482
488
|
window.parent.postMessage(Object.assign({ jsonrpc: "2.0" }, message), "*");
|
|
483
489
|
}
|
|
484
490
|
};
|
|
491
|
+
const send = (message) => {
|
|
492
|
+
if (plan.protocol === "shell") {
|
|
493
|
+
post(message);
|
|
494
|
+
}
|
|
495
|
+
};
|
|
496
|
+
// A navigation the guard above stopped (P080): one of the run's error reports, told even where
|
|
497
|
+
// the content speaks for itself (an MCP Apps view), in Porthole's own notification.
|
|
498
|
+
navigationBlocked = (url) => {
|
|
499
|
+
if (!declared("reportError") || reported >= plan.maxErrorReports || url === "") {
|
|
500
|
+
return;
|
|
501
|
+
}
|
|
502
|
+
reported += 1;
|
|
503
|
+
post({ method: "porthole/navigation-blocked", params: { url: url.slice(0, 4096) } });
|
|
504
|
+
};
|
|
485
505
|
|
|
486
506
|
// A parsed tree's scripts are held (each replaced by a numbered marker) and run later, in order,
|
|
487
507
|
// as the page's parser would run them: each made again, live, in its marker's place, and each
|
|
@@ -1020,7 +1040,13 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
1020
1040
|
if (waiting !== undefined) {
|
|
1021
1041
|
pending.delete(data.id);
|
|
1022
1042
|
if (data.error) {
|
|
1023
|
-
|
|
1043
|
+
// A refusal says why (P080): its code, and a sentence to show the person.
|
|
1044
|
+
const why = data.error.data !== null && typeof data.error.data === "object" ? data.error.data : {};
|
|
1045
|
+
const error = new Error(String(typeof why.message === "string" && why.message !== "" ? why.message : data.error.message || "refused"));
|
|
1046
|
+
if (typeof why.code === "string") {
|
|
1047
|
+
error.code = why.code;
|
|
1048
|
+
}
|
|
1049
|
+
waiting.reject(error);
|
|
1024
1050
|
} else {
|
|
1025
1051
|
waiting.resolve(data.result);
|
|
1026
1052
|
}
|