@botiverse/porthole 0.6.0 → 0.8.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 -2
- package/THIRD_PARTY_NOTICES.md +421 -0
- package/dist/bridge/bounded-text.d.ts +34 -0
- package/dist/bridge/bounded-text.js +188 -0
- package/dist/bridge/bridge.d.ts +38 -5
- package/dist/bridge/bridge.js +469 -39
- package/dist/bridge/json-data.d.ts +28 -0
- package/dist/bridge/json-data.js +86 -0
- package/dist/bridge/navigation.d.ts +5 -0
- package/dist/bridge/navigation.js +7 -0
- package/dist/bridge/refusal.d.ts +5 -1
- package/dist/bridge/refusal.js +17 -0
- package/dist/bridge/types.d.ts +73 -5
- package/dist/check/check.d.ts +7 -0
- package/dist/check/check.js +1 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +4 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +16 -0
- package/dist/check/tools.js +2 -3
- package/dist/compile/compile.d.ts +6 -0
- package/dist/compile/compile.js +3 -1
- package/dist/compile/policy.d.ts +55 -0
- package/dist/compile/policy.js +157 -0
- package/dist/config/capabilities.d.ts +85 -7
- package/dist/config/capabilities.js +32 -2
- package/dist/config/schema.d.ts +35 -0
- package/dist/config/validate.d.ts +9 -3
- package/dist/config/validate.js +92 -8
- package/dist/config/warnings.d.ts +20 -0
- package/dist/config/warnings.js +25 -0
- package/dist/conformance/behavior.js +46 -1
- package/dist/conformance/cookies.d.ts +15 -0
- package/dist/conformance/cookies.js +80 -0
- package/dist/conformance/harness/page.d.ts +1 -0
- package/dist/conformance/harness/page.js +9 -2
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/host-kit.js +5 -1
- package/dist/conformance/index.d.ts +11 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/limits.js +38 -1
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +324 -0
- package/dist/conformance/served.d.ts +2 -0
- package/dist/conformance/served.js +737 -4
- package/dist/files/paths.js +4 -0
- package/dist/guide/gates.d.ts +9 -0
- package/dist/guide/gates.js +31 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +35 -33
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +210 -0
- package/dist/host/create-host.js +73 -37
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- package/dist/host/pages-of-set.d.ts +43 -0
- package/dist/host/pages-of-set.js +196 -0
- package/dist/host/types.d.ts +26 -1
- package/dist/index.d.ts +11 -4
- package/dist/index.js +11 -2
- package/dist/isolation/types.d.ts +8 -0
- package/dist/mcp/adapter.js +11 -15
- package/dist/node/index.d.ts +36 -4
- package/dist/node/index.js +402 -101
- package/dist/presets/presets.d.ts +22 -8
- package/dist/presets/presets.js +40 -8
- package/dist/protocol/live-data.d.ts +6 -2
- package/dist/protocol/live-data.js +20 -1
- package/dist/protocol/mcp-apps.d.ts +13 -2
- package/dist/protocol/mcp-apps.js +10 -2
- package/dist/protocol/message-text.d.ts +8 -0
- package/dist/protocol/message-text.js +29 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +116 -0
- package/dist/protocol/shell-adapter.js +64 -25
- package/dist/react/context-notice.d.ts +32 -0
- package/dist/react/context-notice.js +28 -0
- package/dist/react/dialog.js +91 -16
- package/dist/react/frame.d.ts +25 -1
- package/dist/react/frame.js +85 -2
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +2 -1
- package/dist/runtime/contract.d.ts +201 -0
- package/dist/runtime/contract.js +245 -0
- package/dist/runtime/db.d.ts +188 -0
- package/dist/runtime/db.js +502 -0
- package/dist/runtime/declaration.d.ts +100 -0
- package/dist/runtime/declaration.js +363 -0
- package/dist/runtime/levels.d.ts +33 -0
- package/dist/runtime/levels.js +41 -0
- package/dist/runtime/requests.d.ts +125 -0
- package/dist/runtime/requests.js +215 -0
- package/dist/runtime/segments.d.ts +8 -0
- package/dist/runtime/segments.js +14 -0
- package/dist/runtime/types.generated.d.ts +1 -0
- package/dist/runtime/types.generated.js +19 -0
- package/dist/server/files.d.ts +19 -1
- package/dist/server/files.js +115 -6
- package/dist/server/host.d.ts +24 -2
- package/dist/server/host.js +137 -2
- package/dist/server/index.d.ts +3 -2
- package/dist/server/index.js +2 -1
- package/dist/server/peer.d.ts +4 -0
- package/dist/server/peer.js +19 -0
- package/dist/server/proxy.d.ts +6 -0
- package/dist/server/proxy.js +12 -3
- package/dist/server/pseudonym.d.ts +9 -0
- package/dist/server/pseudonym.js +20 -0
- package/dist/server/server.d.ts +0 -5
- package/dist/server/server.js +318 -52
- package/dist/server/types.d.ts +74 -2
- package/dist/shell/document.d.ts +16 -0
- package/dist/shell/document.js +19 -2
- package/dist/shell/legacy.d.ts +21 -0
- package/dist/shell/legacy.js +63 -0
- package/dist/shell/plan.d.ts +17 -1
- package/dist/shell/plan.js +13 -2
- package/dist/shell/runtime.js +390 -56
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +205 -15
- package/docs/ARCHITECTURE.md +34 -5
- package/docs/DECISIONS.md +1867 -11
- package/docs/DESIGN.md +137 -17
- package/docs/THREAT_MODEL.md +616 -0
- package/package.json +16 -3
- package/src/bridge/bounded-text.ts +240 -0
- package/src/bridge/bridge.ts +601 -51
- package/src/bridge/json-data.ts +95 -0
- package/src/bridge/navigation.ts +10 -0
- package/src/bridge/refusal.ts +17 -0
- package/src/bridge/types.ts +76 -5
- package/src/check/check.ts +8 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +4 -2
- package/src/check/page.ts +16 -0
- package/src/check/tools.ts +2 -3
- package/src/compile/compile.ts +9 -1
- package/src/compile/policy.ts +177 -0
- package/src/config/capabilities.ts +71 -5
- package/src/config/schema.ts +35 -0
- package/src/config/validate.ts +141 -8
- package/src/config/warnings.ts +42 -0
- package/src/conformance/behavior.ts +54 -1
- package/src/conformance/cookies.ts +93 -0
- package/src/conformance/harness/page.ts +11 -2
- package/src/conformance/host-kit.ts +10 -1
- package/src/conformance/index.ts +17 -0
- package/src/conformance/limits.ts +39 -1
- package/src/conformance/runtime.ts +594 -0
- package/src/conformance/served.ts +888 -4
- package/src/files/paths.ts +4 -0
- package/src/guide/gates.ts +37 -0
- package/src/guide/guide.ts +61 -55
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +253 -0
- package/src/host/create-host.ts +88 -36
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/pages-of-set.ts +226 -0
- package/src/host/types.ts +33 -1
- package/src/index.ts +94 -0
- package/src/isolation/types.ts +8 -0
- package/src/mcp/adapter.ts +16 -20
- package/src/node/index.ts +507 -116
- package/src/presets/presets.ts +67 -17
- package/src/protocol/live-data.ts +31 -3
- package/src/protocol/mcp-apps.ts +11 -2
- package/src/protocol/message-text.ts +36 -0
- package/src/protocol/runtime-calls.ts +141 -0
- package/src/protocol/shell-adapter.ts +79 -26
- package/src/react/context-notice.tsx +95 -0
- package/src/react/dialog.tsx +108 -15
- package/src/react/frame.tsx +120 -0
- package/src/react/index.ts +8 -1
- package/src/runtime/contract.ts +339 -0
- package/src/runtime/db.ts +650 -0
- package/src/runtime/declaration.ts +516 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +355 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +138 -7
- package/src/server/host.ts +170 -3
- package/src/server/index.ts +4 -0
- package/src/server/peer.ts +21 -0
- package/src/server/proxy.ts +13 -3
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +370 -57
- package/src/server/types.ts +73 -2
- package/src/shell/document.ts +29 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +390 -56
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +27 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- package/types/runtime/v1/user.d.ts +19 -0
|
@@ -12,6 +12,7 @@
|
|
|
12
12
|
* one host app.
|
|
13
13
|
*/
|
|
14
14
|
import type { EgressConfig } from "../config/schema.ts";
|
|
15
|
+
import type { ViewerInfo } from "../runtime/levels.ts";
|
|
15
16
|
/**
|
|
16
17
|
* Which document a served frame loads. `preset` names the config it is served under (the server's
|
|
17
18
|
* `configs`); the artifact and the proxy default to their presets' names.
|
|
@@ -70,6 +71,11 @@ export interface FrameLocation {
|
|
|
70
71
|
* one that loaded. A host's own gateway may send the same message without this.
|
|
71
72
|
*/
|
|
72
73
|
readonly reports?: boolean;
|
|
74
|
+
/**
|
|
75
|
+
* Who is viewing, as the host's access decided at issue (P087: `Grant.level`, `Grant.user`):
|
|
76
|
+
* the display's bridge checks each runtime method's level against it.
|
|
77
|
+
*/
|
|
78
|
+
readonly viewer?: ViewerInfo;
|
|
73
79
|
}
|
|
74
80
|
/** The message a served page sends its host about loading (own-prefixed, P040). */
|
|
75
81
|
export declare const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
|
|
@@ -93,4 +99,6 @@ export type FrameSource = {
|
|
|
93
99
|
readonly url: string;
|
|
94
100
|
readonly origin: string;
|
|
95
101
|
readonly reports?: boolean;
|
|
102
|
+
/** The issue's viewer (`FrameLocation.viewer`), for the display's bridge. */
|
|
103
|
+
readonly viewer?: ViewerInfo;
|
|
96
104
|
};
|
package/dist/mcp/adapter.js
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
import { egressOrigins } from "../compile/policy.js";
|
|
2
2
|
import { JSON_RPC_ERRORS, parseJsonRpc, } from "../protocol/jsonrpc.js";
|
|
3
|
-
import { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, } from "../protocol/mcp-apps.js";
|
|
3
|
+
import { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MODEL_CONTEXT_OFFERED, } from "../protocol/mcp-apps.js";
|
|
4
4
|
import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES, NAVIGATION_BLOCKED_METHOD, } from "../protocol/mcp-apps.js";
|
|
5
5
|
import { liveData } from "../protocol/live-data.js";
|
|
6
|
+
import { messageText } from "../protocol/message-text.js";
|
|
6
7
|
import { reasonFor } from "../bridge/refusal.js";
|
|
7
8
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
8
9
|
/** Levels of `notifications/message` that are errors: they go to the host as `reportError`. */
|
|
@@ -32,12 +33,6 @@ export function viewHostContext(context, toolInfo) {
|
|
|
32
33
|
}
|
|
33
34
|
return out;
|
|
34
35
|
}
|
|
35
|
-
/** The text of a `ui/message`'s content: its text blocks, in order (the spec's examples send one). */
|
|
36
|
-
function messageText(content) {
|
|
37
|
-
const blocks = Array.isArray(content) ? content : [content];
|
|
38
|
-
const texts = blocks.flatMap((block) => isRecord(block) && block.type === "text" && typeof block.text === "string" ? [block.text] : []);
|
|
39
|
-
return texts.length === 0 ? null : texts.join("\n\n");
|
|
40
|
-
}
|
|
41
36
|
/** Whether the host page has a live user gesture (a gesture in a frame activates its ancestors). */
|
|
42
37
|
function hostActivation() {
|
|
43
38
|
const activation = globalThis
|
|
@@ -90,9 +85,7 @@ function connect(session, options) {
|
|
|
90
85
|
? { serverResources: declared("subscribeData") ? { subscribe: true } : {} }
|
|
91
86
|
: {}),
|
|
92
87
|
...(declared("sendPrompt") ? { message: { text: {} } } : {}),
|
|
93
|
-
...(declared("setModelContext")
|
|
94
|
-
? { updateModelContext: { text: {}, structuredContent: {} } }
|
|
95
|
-
: {}),
|
|
88
|
+
...(declared("setModelContext") ? { updateModelContext: MODEL_CONTEXT_OFFERED } : {}),
|
|
96
89
|
sandbox: {
|
|
97
90
|
csp: {
|
|
98
91
|
...(connectDomains.length > 0 ? { connectDomains } : {}),
|
|
@@ -154,7 +147,11 @@ function connect(session, options) {
|
|
|
154
147
|
answer(request.id, {});
|
|
155
148
|
return;
|
|
156
149
|
case MCP_APPS_METHODS.message: {
|
|
157
|
-
|
|
150
|
+
// Its text blocks, in order (the spec's examples send one), read bounded (P095).
|
|
151
|
+
const content = params.content;
|
|
152
|
+
const text = params.role === "user"
|
|
153
|
+
? messageText(Array.isArray(content) ? content : [content], "\n\n", session.compiled.config.limits.maxPromptChars)
|
|
154
|
+
: null;
|
|
158
155
|
if (text === null) {
|
|
159
156
|
invalid('needs role "user" and text content');
|
|
160
157
|
return;
|
|
@@ -277,11 +274,10 @@ function connect(session, options) {
|
|
|
277
274
|
return;
|
|
278
275
|
}
|
|
279
276
|
case MCP_APPS_METHODS.log:
|
|
277
|
+
// What the view said, as it came (S05, P095): the bridge reads it only within
|
|
278
|
+
// reportError's declaration and rate, into bounded text, and nothing in it throws here.
|
|
280
279
|
if (typeof params.level === "string" && ERROR_LEVELS.has(params.level)) {
|
|
281
|
-
|
|
282
|
-
void bridge.call("reportError", {
|
|
283
|
-
message: (typeof data === "string" ? data : (JSON.stringify(data) ?? "")).slice(0, 2_000),
|
|
284
|
-
});
|
|
280
|
+
void bridge.call("reportError", { message: params.data });
|
|
285
281
|
}
|
|
286
282
|
return;
|
|
287
283
|
case NAVIGATION_BLOCKED_METHOD:
|
package/dist/node/index.d.ts
CHANGED
|
@@ -8,6 +8,10 @@
|
|
|
8
8
|
* const server = http.createServer(porthole.request);
|
|
9
9
|
* server.on("upgrade", porthole.upgrade);
|
|
10
10
|
* server.listen(8080, () => content.start());
|
|
11
|
+
*
|
|
12
|
+
* Nothing a request does throws out of these listeners or ends the process (S01, P092): what fetch
|
|
13
|
+
* can't take is 405 or 400; what fails on the app's side (a handler, a listener, an answer Node
|
|
14
|
+
* can't write) is 500, and `onError` hears it.
|
|
11
15
|
*/
|
|
12
16
|
import type { IncomingMessage, Server, ServerResponse } from "node:http";
|
|
13
17
|
import type { Duplex } from "node:stream";
|
|
@@ -15,6 +19,12 @@ import type { ContentHost, HealthProbe } from "../server/host.ts";
|
|
|
15
19
|
import type { Access } from "../server/types.ts";
|
|
16
20
|
type RequestListener = (request: IncomingMessage, response: ServerResponse) => void;
|
|
17
21
|
type UpgradeListener = (request: IncomingMessage, socket: Duplex, head: Buffer) => void;
|
|
22
|
+
/**
|
|
23
|
+
* Hears what failed on the app's side while serving a request (its handler or listener threw or
|
|
24
|
+
* rejected, an answer Node can't write), once the client has its 500. Default: a process warning
|
|
25
|
+
* (`process.emitWarning`). Never the client's to read.
|
|
26
|
+
*/
|
|
27
|
+
export type NodeErrorListener = (error: unknown, request: IncomingMessage) => void;
|
|
18
28
|
export interface NodeHostOptions {
|
|
19
29
|
/** The app's own request listener (Express, Hono's `getRequestListener`, a router). */
|
|
20
30
|
readonly request: RequestListener;
|
|
@@ -22,6 +32,7 @@ export interface NodeHostOptions {
|
|
|
22
32
|
readonly upgrade?: UpgradeListener;
|
|
23
33
|
/** A url-mode app's WebSocket, once its cookie checks out (`ContentHost.access`). */
|
|
24
34
|
readonly appSocket?: (access: Access, request: IncomingMessage, socket: Duplex, head: Buffer) => void;
|
|
35
|
+
readonly onError?: NodeErrorListener;
|
|
25
36
|
}
|
|
26
37
|
export interface NodeHost {
|
|
27
38
|
readonly request: RequestListener;
|
|
@@ -29,16 +40,36 @@ export interface NodeHost {
|
|
|
29
40
|
}
|
|
30
41
|
/**
|
|
31
42
|
* The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). `signal`
|
|
32
|
-
* (`nodeHost` gives one, aborted when the client goes away) lets an upstream stop its work.
|
|
43
|
+
* (`nodeHost` gives one, aborted when the client goes away) lets an upstream stop its work. The
|
|
44
|
+
* body is read only as it is pulled; cancelled, the rest is dropped (bounded), not the connection.
|
|
45
|
+
* The socket's peer goes with it, for the issue endpoint's rate limit (P092).
|
|
46
|
+
* Throws where fetch can't take the request: a method it can't carry (`TRACE`), a Host or a
|
|
47
|
+
* target that is no URL. `nodeListener`, `nodeHost` and `nodeServer` answer those 405 and 400.
|
|
33
48
|
*/
|
|
34
49
|
export declare function toRequest(request: IncomingMessage, scheme: "https" | "http", signal?: AbortSignal): Request;
|
|
35
50
|
/**
|
|
36
51
|
* Writes a fetch `Response` to a Node response, cookies one header each (P070): it waits for the
|
|
37
52
|
* socket to drain before reading on (a slow client never makes it buffer the body), cancels the
|
|
38
|
-
* body when the client goes away (an event stream ends with the
|
|
39
|
-
* an error mid-body destroys the response rather than end it
|
|
53
|
+
* body when the client goes away, before the answer or during it (an event stream ends with the
|
|
54
|
+
* page that asked for it), and on an error mid-body destroys the response rather than end it
|
|
55
|
+
* looking complete. A HEAD gets the head and its body is cancelled. Never rejects (P092): an
|
|
56
|
+
* answer it can't write (no Response, a body already read, a header value fetch takes and Node
|
|
57
|
+
* doesn't) is a 500, and `onError` hears why. Once the answer is out, a request body no one read
|
|
58
|
+
* is dropped, bounded, before the connection closes.
|
|
59
|
+
*/
|
|
60
|
+
export declare function sendResponse(response: ServerResponse, answer: Response, onError?: (error: unknown) => void): Promise<void>;
|
|
61
|
+
export interface NodeListenerOptions {
|
|
62
|
+
/** The requests' URLs' scheme (default `http`; `https` behind a TLS edge). */
|
|
63
|
+
readonly scheme?: "https" | "http";
|
|
64
|
+
readonly onError?: NodeErrorListener;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* A fetch-style handler (Hono's `app.fetch`, the app's own) as a Node request listener: what
|
|
68
|
+
* `toRequest` can't convert is 405 or 400, what the handler throws or the answer's writing fails
|
|
69
|
+
* is 500 (`onError` hears it); nothing it does ends the process (S01, P092). The request's
|
|
70
|
+
* `signal` aborts when the client goes away before the answer is out.
|
|
40
71
|
*/
|
|
41
|
-
export declare function
|
|
72
|
+
export declare function nodeListener(app: (request: Request) => Response | Promise<Response>, options?: NodeListenerOptions): RequestListener;
|
|
42
73
|
export declare function nodeHost<V>(content: ContentHost<V>, app: NodeHostOptions): NodeHost;
|
|
43
74
|
/**
|
|
44
75
|
* The health gate's probe on Node: a GET over the real network (DNS, the edge, TLS with Node's
|
|
@@ -66,6 +97,7 @@ export interface NodeServerOptions {
|
|
|
66
97
|
readonly appSocket?: NodeHostOptions["appSocket"];
|
|
67
98
|
/** Whether the app's own requests came over https (behind a TLS edge): their URL's scheme. */
|
|
68
99
|
readonly scheme?: "https" | "http";
|
|
100
|
+
readonly onError?: NodeErrorListener;
|
|
69
101
|
}
|
|
70
102
|
/**
|
|
71
103
|
* The whole Node server (P072): the content domain to Porthole, everything else to the app, its
|