@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/dist/check/page.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { capabilitySpec, isCapabilityName, } from "../config/capabilities.js";
|
|
2
|
+
import { addressWithoutQuery } from "../bridge/navigation.js";
|
|
2
3
|
import { createHost } from "../host/create-host.js";
|
|
3
4
|
import { webPlatform } from "../platform/web.js";
|
|
4
5
|
import { contentLine, instrumented, } from "./instrument.js";
|
|
@@ -150,6 +151,10 @@ const check = {
|
|
|
150
151
|
calls.push({ capability, outcome: refusal });
|
|
151
152
|
}
|
|
152
153
|
});
|
|
154
|
+
// A navigation the shell stopped (P080): the content tried to leave its page.
|
|
155
|
+
display.on("navigationBlocked", ({ url }) => {
|
|
156
|
+
run.data.errors.push(`It tried to navigate its frame to ${addressWithoutQuery(url)}, and was stopped: content never leaves its page`);
|
|
157
|
+
});
|
|
153
158
|
display.on("outcome", (outcome) => {
|
|
154
159
|
run.data.outcome = outcome.state === "blocked" ? `blocked: ${outcome.reason}` : outcome.state;
|
|
155
160
|
});
|
package/dist/check/tools.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
2
|
import { type Finding } from "./lint.ts";
|
|
3
|
+
import { type FileContents, type FileFinding } from "./files.ts";
|
|
3
4
|
/**
|
|
4
5
|
* The agent's tools, as a tool list names them (P073): a name, a description and a JSON Schema
|
|
5
6
|
* for each, from the config, so a host lists them in one line (an MCP server's `tools/list`, an
|
|
@@ -54,6 +55,28 @@ export type AdmitResult = {
|
|
|
54
55
|
export declare function admitContent(config: PortholeConfig, content: string, options?: {
|
|
55
56
|
readonly refuseOn?: "error" | "never";
|
|
56
57
|
}): AdmitResult;
|
|
58
|
+
export type AdmitFilesResult = {
|
|
59
|
+
readonly ok: true;
|
|
60
|
+
/** Warnings (and errors, with `refuseOn: "never"`), for the tool's answer. */
|
|
61
|
+
readonly findings: readonly FileFinding[];
|
|
62
|
+
/** One line for the agent, or null when there's nothing to say. */
|
|
63
|
+
readonly note: string | null;
|
|
64
|
+
} | {
|
|
65
|
+
readonly ok: false;
|
|
66
|
+
readonly findings: readonly FileFinding[];
|
|
67
|
+
/** What to tell the agent: what to change, and to call the tool again. */
|
|
68
|
+
readonly refusal: string;
|
|
69
|
+
};
|
|
70
|
+
/**
|
|
71
|
+
* A publish tool's check before it takes a page with files (P081): refuses only what certainly
|
|
72
|
+
* fails (a path or limit the server won't take, no entry, a page `admitContent` would refuse, a
|
|
73
|
+
* page's reference that starts with /); the rest, references to files that aren't in the set
|
|
74
|
+
* among them, are warnings. `refuseOn: "never"` refuses nothing.
|
|
75
|
+
*/
|
|
76
|
+
export declare function admitFiles(config: PortholeConfig, files: FileContents, options?: {
|
|
77
|
+
readonly entry?: string;
|
|
78
|
+
readonly refuseOn?: "error" | "never";
|
|
79
|
+
}): AdmitFilesResult;
|
|
57
80
|
/**
|
|
58
81
|
* What to tell the agent when its manual changes (a display kind flipped between served and
|
|
59
82
|
* opaque, P073): the lines that are new, or null when the manual reads the same.
|
package/dist/check/tools.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { BUILT_IN_TOPICS } from "../config/validate.js";
|
|
2
2
|
import { generateGuide, generateToolDescription } from "../guide/guide.js";
|
|
3
3
|
import { fragmentOf, lintContent } from "./lint.js";
|
|
4
|
+
import { lintFiles, whereOf } from "./files.js";
|
|
4
5
|
const noun = (config) => config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget";
|
|
5
6
|
/** The show tool's name: the config's `guide.toolName`, else `show_<noun>`. */
|
|
6
7
|
const showName = (config) => config.guide.toolName ?? `show_${noun(config)}`;
|
|
@@ -124,6 +125,30 @@ export function admitContent(config, content, options = {}) {
|
|
|
124
125
|
: `Shown. Fix these next time:\n${findings.map((each) => `- ${said(each)}`).join("\n")}`,
|
|
125
126
|
};
|
|
126
127
|
}
|
|
128
|
+
/**
|
|
129
|
+
* A publish tool's check before it takes a page with files (P081): refuses only what certainly
|
|
130
|
+
* fails (a path or limit the server won't take, no entry, a page `admitContent` would refuse, a
|
|
131
|
+
* page's reference that starts with /); the rest, references to files that aren't in the set
|
|
132
|
+
* among them, are warnings. `refuseOn: "never"` refuses nothing.
|
|
133
|
+
*/
|
|
134
|
+
export function admitFiles(config, files, options = {}) {
|
|
135
|
+
const findings = lintFiles(config, files, options.entry === undefined ? {} : { entry: options.entry });
|
|
136
|
+
const errors = findings.filter((each) => each.severity === "error");
|
|
137
|
+
if (errors.length > 0 && (options.refuseOn ?? "error") === "error") {
|
|
138
|
+
return {
|
|
139
|
+
ok: false,
|
|
140
|
+
findings,
|
|
141
|
+
refusal: `Not published. Change this, then publish again:\n${errors.map((each) => `- ${whereOf(each)}${each.message}`).join("\n")}`,
|
|
142
|
+
};
|
|
143
|
+
}
|
|
144
|
+
return {
|
|
145
|
+
ok: true,
|
|
146
|
+
findings,
|
|
147
|
+
note: findings.length === 0
|
|
148
|
+
? null
|
|
149
|
+
: `Published. Fix these next time:\n${findings.map((each) => `- ${whereOf(each)}${each.message}`).join("\n")}`,
|
|
150
|
+
};
|
|
151
|
+
}
|
|
127
152
|
/**
|
|
128
153
|
* What to tell the agent when its manual changes (a display kind flipped between served and
|
|
129
154
|
* opaque, P073): the lines that are new, or null when the manual reads the same.
|
package/dist/compile/policy.d.ts
CHANGED
|
@@ -31,6 +31,21 @@ export declare function librarySources(config: PortholeConfig): string[];
|
|
|
31
31
|
* whose app serves its own policy.
|
|
32
32
|
*/
|
|
33
33
|
export declare function frameCspDirectives(config: PortholeConfig): CspDirective[];
|
|
34
|
+
/** The directives a page of a file set loads its own files under (P082): everything that loads. */
|
|
35
|
+
export declare const FILE_SET_DIRECTIVES: readonly ["script-src", "style-src", "font-src", "img-src", "media-src", "connect-src", "worker-src"];
|
|
36
|
+
/**
|
|
37
|
+
* A served page's CSP when it comes with files (P082): the frame's, with its version's own files
|
|
38
|
+
* opened for each kind that loads (`FILE_SET_DIRECTIVES`), by `source`, the files' path on the
|
|
39
|
+
* content origin (`https://a-x.example-usercontent.com/v/3/`). Never `'self'`: the origin's other
|
|
40
|
+
* paths (other versions, Porthole's own) stay closed, and frames, plugins, forms and `<base>` stay
|
|
41
|
+
* `'none'`. Opaque frames have no files, and keep P022's rule whole.
|
|
42
|
+
*/
|
|
43
|
+
export declare function fileSetCspDirectives(directives: readonly CspDirective[], source: string): CspDirective[];
|
|
44
|
+
/**
|
|
45
|
+
* The CSP of a file of a set that is neither a page nor a script (P081): nothing loads from it,
|
|
46
|
+
* and opened as a document (an SVG, an XML file) it runs nothing, on an opaque origin.
|
|
47
|
+
*/
|
|
48
|
+
export declare const INERT_FILE_CSP = "default-src 'none'; sandbox";
|
|
34
49
|
export declare function serializeCsp(directives: readonly CspDirective[]): string;
|
|
35
50
|
/**
|
|
36
51
|
* The frame's `sandbox` tokens. Opaque: scripts only, so the frame is an opaque origin and gets
|
package/dist/compile/policy.js
CHANGED
|
@@ -76,6 +76,38 @@ export function frameCspDirectives(config) {
|
|
|
76
76
|
["webrtc", "'block'"],
|
|
77
77
|
];
|
|
78
78
|
}
|
|
79
|
+
/** The directives a page of a file set loads its own files under (P082): everything that loads. */
|
|
80
|
+
export const FILE_SET_DIRECTIVES = [
|
|
81
|
+
"script-src",
|
|
82
|
+
"style-src",
|
|
83
|
+
"font-src",
|
|
84
|
+
"img-src",
|
|
85
|
+
"media-src",
|
|
86
|
+
"connect-src",
|
|
87
|
+
"worker-src",
|
|
88
|
+
];
|
|
89
|
+
/**
|
|
90
|
+
* A served page's CSP when it comes with files (P082): the frame's, with its version's own files
|
|
91
|
+
* opened for each kind that loads (`FILE_SET_DIRECTIVES`), by `source`, the files' path on the
|
|
92
|
+
* content origin (`https://a-x.example-usercontent.com/v/3/`). Never `'self'`: the origin's other
|
|
93
|
+
* paths (other versions, Porthole's own) stay closed, and frames, plugins, forms and `<base>` stay
|
|
94
|
+
* `'none'`. Opaque frames have no files, and keep P022's rule whole.
|
|
95
|
+
*/
|
|
96
|
+
export function fileSetCspDirectives(directives, source) {
|
|
97
|
+
const opened = new Set(FILE_SET_DIRECTIVES);
|
|
98
|
+
return directives.map(([name, ...sources]) => {
|
|
99
|
+
if (!opened.has(name)) {
|
|
100
|
+
return [name, ...sources];
|
|
101
|
+
}
|
|
102
|
+
const kept = sources.filter((each) => each !== "'none'");
|
|
103
|
+
return [name, ...kept, source];
|
|
104
|
+
});
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* The CSP of a file of a set that is neither a page nor a script (P081): nothing loads from it,
|
|
108
|
+
* and opened as a document (an SVG, an XML file) it runs nothing, on an opaque origin.
|
|
109
|
+
*/
|
|
110
|
+
export const INERT_FILE_CSP = "default-src 'none'; sandbox";
|
|
79
111
|
export function serializeCsp(directives) {
|
|
80
112
|
return directives.map((directive) => directive.join(" ")).join("; ");
|
|
81
113
|
}
|
|
@@ -169,8 +169,13 @@ export interface CapabilityArgs {
|
|
|
169
169
|
readonly content?: readonly unknown[];
|
|
170
170
|
readonly structuredContent?: Readonly<Record<string, unknown>>;
|
|
171
171
|
};
|
|
172
|
+
/**
|
|
173
|
+
* `navigationBlocked`: the address a navigation of the frame went to when the shell cancelled it
|
|
174
|
+
* (P080), the content's word; `message` is then Porthole's, which names it without its query.
|
|
175
|
+
*/
|
|
172
176
|
readonly reportError: {
|
|
173
177
|
readonly message: string;
|
|
178
|
+
readonly navigationBlocked?: string;
|
|
174
179
|
};
|
|
175
180
|
readonly resize: {
|
|
176
181
|
readonly height: number;
|
package/dist/config/schema.d.ts
CHANGED
|
@@ -113,6 +113,14 @@ export interface Limits {
|
|
|
113
113
|
* when absent.
|
|
114
114
|
*/
|
|
115
115
|
readonly loadTimeoutMs?: number;
|
|
116
|
+
/**
|
|
117
|
+
* A served page's files (P081): the most a version holds (default 1000), the largest one,
|
|
118
|
+
* bytes (default 25 MiB), and all of them together, bytes (default 100 MiB: a host sets its
|
|
119
|
+
* own). The manual states them; `checkFileSet` and `lintFiles` hold a version to them.
|
|
120
|
+
*/
|
|
121
|
+
readonly maxFiles?: number;
|
|
122
|
+
readonly maxFileBytes?: number;
|
|
123
|
+
readonly maxVersionBytes?: number;
|
|
116
124
|
}
|
|
117
125
|
/**
|
|
118
126
|
* Sandbox tokens a url-mode frame may add to its baseline, by the host's choice (P037): a
|
package/dist/config/validate.js
CHANGED
|
@@ -366,13 +366,20 @@ export function validateConfig(input) {
|
|
|
366
366
|
"maxPromptChars",
|
|
367
367
|
"maxErrorReports",
|
|
368
368
|
];
|
|
369
|
-
|
|
369
|
+
const fileLimitNames = ["maxFiles", "maxFileBytes", "maxVersionBytes"];
|
|
370
|
+
only(limits, [...limitNames, "loadTimeoutMs", ...fileLimitNames], "config.limits");
|
|
370
371
|
for (const name of limitNames) {
|
|
371
372
|
positive(limits[name], `config.limits.${name}`);
|
|
372
373
|
}
|
|
373
374
|
if (limits.loadTimeoutMs !== undefined) {
|
|
374
375
|
positive(limits.loadTimeoutMs, "config.limits.loadTimeoutMs", 600_000);
|
|
375
376
|
}
|
|
377
|
+
// A served page's files (P081): optional, with fileLimits' defaults.
|
|
378
|
+
for (const name of fileLimitNames) {
|
|
379
|
+
if (limits[name] !== undefined) {
|
|
380
|
+
positive(limits[name], `config.limits.${name}`);
|
|
381
|
+
}
|
|
382
|
+
}
|
|
376
383
|
if (limits.minHeightPx > limits.maxHeightPx) {
|
|
377
384
|
fail("config.limits.minHeightPx", "must not exceed maxHeightPx");
|
|
378
385
|
}
|