@botiverse/porthole 0.14.7 → 0.14.9
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/CHANGELOG.md +74 -0
- package/dist/bridge/bridge.d.ts +6 -0
- package/dist/bridge/bridge.js +5 -0
- package/dist/check/files.js +2 -0
- package/dist/check/lint.js +82 -3
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.d.ts +17 -6
- package/dist/compile/policy.js +22 -7
- package/dist/config/capabilities.d.ts +16 -2
- package/dist/config/capabilities.js +8 -0
- package/dist/config/schema.d.ts +13 -0
- package/dist/config/validate.js +15 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/kit.d.ts +5 -0
- package/dist/conformance/kit.js +21 -0
- package/dist/conformance/limits.js +10 -5
- package/dist/conformance/probes.js +139 -28
- package/dist/conformance/served.js +25 -4
- package/dist/find/types.d.ts +83 -0
- package/dist/find/types.js +29 -0
- package/dist/find/validate.d.ts +17 -0
- package/dist/find/validate.js +82 -0
- package/dist/guide/guide.js +2 -1
- package/dist/guide/limits.js +8 -1
- package/dist/host/create-host.js +249 -4
- package/dist/host/pass-on.js +3 -2
- package/dist/host/types.d.ts +51 -0
- package/dist/index.d.ts +4 -2
- package/dist/index.js +4 -1
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +6 -0
- package/dist/react/frame.d.ts +43 -0
- package/dist/react/frame.js +107 -3
- package/dist/react/view.js +2 -0
- package/dist/runtime/contract.d.ts +1 -1
- package/dist/runtime/contract.js +1 -1
- package/dist/server/files.js +4 -3
- package/dist/server/server.js +4 -1
- package/dist/shell/annotate.js +2 -95
- package/dist/shell/document.d.ts +3 -3
- package/dist/shell/document.js +5 -3
- package/dist/shell/find.d.ts +82 -0
- package/dist/shell/find.js +725 -0
- package/dist/shell/plan.d.ts +5 -0
- package/dist/shell/plan.js +2 -0
- package/dist/shell/runtime.d.ts +30 -1
- package/dist/shell/runtime.js +789 -105
- package/dist/shell/text.d.ts +17 -0
- package/dist/shell/text.js +140 -0
- package/docs/ADOPTING.md +103 -0
- package/docs/ARCHITECTURE.md +10 -3
- package/docs/DECISIONS.md +513 -1
- package/docs/DESIGN.md +40 -4
- package/docs/THREAT_MODEL.md +75 -6
- package/docs/insertion-entry-points.md +112 -0
- package/package.json +1 -1
- package/src/bridge/bridge.ts +7 -0
- package/src/check/files.ts +2 -0
- package/src/check/lint.ts +97 -8
- package/src/compile/policy.ts +23 -6
- package/src/config/capabilities.ts +13 -1
- package/src/config/schema.ts +13 -0
- package/src/config/validate.ts +16 -0
- package/src/conformance/kit.ts +22 -0
- package/src/conformance/limits.ts +10 -5
- package/src/conformance/probes.ts +149 -28
- package/src/conformance/served.ts +24 -4
- package/src/find/types.ts +86 -0
- package/src/find/validate.ts +101 -0
- package/src/guide/guide.ts +3 -1
- package/src/guide/limits.ts +9 -1
- package/src/host/create-host.ts +267 -4
- package/src/host/pass-on.ts +3 -2
- package/src/host/types.ts +52 -0
- package/src/index.ts +13 -0
- package/src/presets/presets.ts +15 -0
- package/src/react/frame.tsx +160 -1
- package/src/react/view.tsx +3 -0
- package/src/runtime/contract.ts +1 -1
- package/src/server/files.ts +8 -2
- package/src/server/server.ts +4 -1
- package/src/shell/annotate.ts +3 -95
- package/src/shell/document.ts +5 -3
- package/src/shell/find.ts +731 -0
- package/src/shell/plan.ts +7 -0
- package/src/shell/runtime.ts +792 -105
- package/src/shell/text.ts +140 -0
package/dist/compile/policy.d.ts
CHANGED
|
@@ -41,13 +41,24 @@ export declare function frameCspDirectives(config: PortholeConfig): CspDirective
|
|
|
41
41
|
/** The directives a page of a file set loads its own files under (P082): everything that loads. */
|
|
42
42
|
export declare const FILE_SET_DIRECTIVES: readonly ["script-src", "style-src", "font-src", "img-src", "media-src", "connect-src", "worker-src"];
|
|
43
43
|
/**
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
* `
|
|
44
|
+
* The directives a page of a file set opens to its version's own files under `config` (P082):
|
|
45
|
+
* `FILE_SET_DIRECTIVES`, and `frame-src` too where the config lets content frame its own files
|
|
46
|
+
* (`nestedFrames: "own"`, P128). Never `child-src`: every engine Porthole supports reads frames
|
|
47
|
+
* from `frame-src` (P038), and `child-src` is only its fallback (and workers', which have
|
|
48
|
+
* `worker-src`).
|
|
49
49
|
*/
|
|
50
|
-
export declare function
|
|
50
|
+
export declare function fileSetDirectives(config: PortholeConfig): readonly string[];
|
|
51
|
+
/**
|
|
52
|
+
* A served page's CSP when it comes with files (P082): the frame's, with its version's own files
|
|
53
|
+
* opened for each kind that loads (`opened`: `FILE_SET_DIRECTIVES` by default, a server's
|
|
54
|
+
* `fileSetDirectives(config)`), by `source`, the files' path on the content origin
|
|
55
|
+
* (`https://a-x.example-usercontent.com/v/3/`).
|
|
56
|
+
* Never `'self'`: the origin's other paths (other versions, Porthole's own) stay closed, and
|
|
57
|
+
* plugins, forms and `<base>` stay `'none'`, frames too unless the config opts into its own
|
|
58
|
+
* (P128: `frame-src` its version's path, never another origin). Opaque frames have no files, and
|
|
59
|
+
* keep P022's rule whole.
|
|
60
|
+
*/
|
|
61
|
+
export declare function fileSetCspDirectives(directives: readonly CspDirective[], source: string, opened?: readonly string[]): CspDirective[];
|
|
51
62
|
/**
|
|
52
63
|
* The directives a page opens its artifact's asset library to (P089), at `/_blob/` on its own
|
|
53
64
|
* origin: what loads without running, always; what runs (scripts, styles) only where uploads are
|
package/dist/compile/policy.js
CHANGED
|
@@ -108,17 +108,32 @@ export const FILE_SET_DIRECTIVES = [
|
|
|
108
108
|
"connect-src",
|
|
109
109
|
"worker-src",
|
|
110
110
|
];
|
|
111
|
+
/**
|
|
112
|
+
* The directives a page of a file set opens to its version's own files under `config` (P082):
|
|
113
|
+
* `FILE_SET_DIRECTIVES`, and `frame-src` too where the config lets content frame its own files
|
|
114
|
+
* (`nestedFrames: "own"`, P128). Never `child-src`: every engine Porthole supports reads frames
|
|
115
|
+
* from `frame-src` (P038), and `child-src` is only its fallback (and workers', which have
|
|
116
|
+
* `worker-src`).
|
|
117
|
+
*/
|
|
118
|
+
export function fileSetDirectives(config) {
|
|
119
|
+
return config.nestedFrames === "own"
|
|
120
|
+
? [...FILE_SET_DIRECTIVES, "frame-src"]
|
|
121
|
+
: FILE_SET_DIRECTIVES;
|
|
122
|
+
}
|
|
111
123
|
/**
|
|
112
124
|
* A served page's CSP when it comes with files (P082): the frame's, with its version's own files
|
|
113
|
-
* opened for each kind that loads (`FILE_SET_DIRECTIVES`
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
* `'
|
|
125
|
+
* opened for each kind that loads (`opened`: `FILE_SET_DIRECTIVES` by default, a server's
|
|
126
|
+
* `fileSetDirectives(config)`), by `source`, the files' path on the content origin
|
|
127
|
+
* (`https://a-x.example-usercontent.com/v/3/`).
|
|
128
|
+
* Never `'self'`: the origin's other paths (other versions, Porthole's own) stay closed, and
|
|
129
|
+
* plugins, forms and `<base>` stay `'none'`, frames too unless the config opts into its own
|
|
130
|
+
* (P128: `frame-src` its version's path, never another origin). Opaque frames have no files, and
|
|
131
|
+
* keep P022's rule whole.
|
|
117
132
|
*/
|
|
118
|
-
export function fileSetCspDirectives(directives, source) {
|
|
119
|
-
const
|
|
133
|
+
export function fileSetCspDirectives(directives, source, opened = FILE_SET_DIRECTIVES) {
|
|
134
|
+
const open = new Set(opened);
|
|
120
135
|
return directives.map(([name, ...sources]) => {
|
|
121
|
-
if (!
|
|
136
|
+
if (!open.has(name)) {
|
|
122
137
|
return [name, ...sources];
|
|
123
138
|
}
|
|
124
139
|
const kept = sources.filter((each) => each !== "'none'");
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { AnnotationReport } from "../annotate/types.ts";
|
|
2
|
+
import type { FindReport } from "../find/types.ts";
|
|
2
3
|
import type { DbRequest, DbResult } from "../runtime/db.ts";
|
|
3
4
|
import type { ArtifactInfo, ArtifactRequest, AssetInfo, AssetRequest, CommentRequest, PublishedVersion, UserInfo } from "../runtime/requests.ts";
|
|
4
5
|
/**
|
|
@@ -10,7 +11,7 @@ import type { ArtifactInfo, ArtifactRequest, AssetInfo, AssetRequest, CommentReq
|
|
|
10
11
|
* are on by default), and is served either by a handler the host passes or as an event the
|
|
11
12
|
* framework emits.
|
|
12
13
|
*/
|
|
13
|
-
export declare const CAPABILITY_NAMES: readonly ["sendPrompt", "openLink", "downloadFile", "callTool", "readData", "subscribeData", "setModelContext", "reportError", "resize", "copyText", "annotate", "user", "comments", "artifact", "assets", "db"];
|
|
14
|
+
export declare const CAPABILITY_NAMES: readonly ["sendPrompt", "openLink", "downloadFile", "callTool", "readData", "subscribeData", "setModelContext", "reportError", "resize", "copyText", "annotate", "find", "user", "comments", "artifact", "assets", "db"];
|
|
14
15
|
export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
|
|
15
16
|
/**
|
|
16
17
|
* What must hold before a call reaches the host's handler. A capability's gates all apply.
|
|
@@ -52,7 +53,7 @@ export interface CapabilitySpec {
|
|
|
52
53
|
/**
|
|
53
54
|
* How content reaches it without the shell's global: the MCP Apps request (or Porthole's own,
|
|
54
55
|
* `porthole/…`, where the standard has none), and the official App SDK's method for it, if any.
|
|
55
|
-
* Absent for what the shell does by itself (sizes, errors, annotations).
|
|
56
|
+
* Absent for what the shell does by itself (sizes, errors, annotations, find).
|
|
56
57
|
*/
|
|
57
58
|
readonly request?: {
|
|
58
59
|
readonly method: string;
|
|
@@ -171,6 +172,16 @@ export declare const CAPABILITIES: {
|
|
|
171
172
|
readonly defaultGates: readonly [Gate];
|
|
172
173
|
readonly served: "event";
|
|
173
174
|
};
|
|
175
|
+
/**
|
|
176
|
+
* Find in page (P131): the host's find bar asks the shell to find the person's words in the
|
|
177
|
+
* content and highlight them; the shell answers how many and which is current, and says when
|
|
178
|
+
* the person pressed the find shortcut in the frame. The query goes into the content's realm,
|
|
179
|
+
* which can read it; what the frame says back is the content's word: a find bar's numbers.
|
|
180
|
+
*/
|
|
181
|
+
readonly find: {
|
|
182
|
+
readonly defaultGates: readonly [Gate];
|
|
183
|
+
readonly served: "event";
|
|
184
|
+
};
|
|
174
185
|
/** Who is viewing (P087): answered from the viewer the host gave the display. */
|
|
175
186
|
readonly user: {
|
|
176
187
|
readonly defaultGates: readonly [Gate];
|
|
@@ -263,6 +274,8 @@ export interface CapabilityArgs {
|
|
|
263
274
|
};
|
|
264
275
|
/** What the frame reported, once checked (`AnnotationReport`). */
|
|
265
276
|
readonly annotate: AnnotationReport;
|
|
277
|
+
/** What the frame said unasked, once checked (`FindReport`): the shortcut, a changed count. */
|
|
278
|
+
readonly find: FindReport;
|
|
266
279
|
readonly user: Readonly<Record<string, never>>;
|
|
267
280
|
readonly comments: CommentRequest;
|
|
268
281
|
readonly artifact: ArtifactRequest;
|
|
@@ -288,6 +301,7 @@ export interface CapabilityResults {
|
|
|
288
301
|
/** Whether the text was copied. */
|
|
289
302
|
readonly copyText: boolean;
|
|
290
303
|
readonly annotate: undefined;
|
|
304
|
+
readonly find: undefined;
|
|
291
305
|
readonly user: UserInfo;
|
|
292
306
|
/** Whether the composer opened. Never a thread: content doesn't read comments (P090). */
|
|
293
307
|
readonly comments: boolean;
|
|
@@ -19,6 +19,7 @@ export const CAPABILITY_NAMES = [
|
|
|
19
19
|
"resize",
|
|
20
20
|
"copyText",
|
|
21
21
|
"annotate",
|
|
22
|
+
"find",
|
|
22
23
|
// The capability runtime's own (P085, `config.runtime`): reached through `porthole.use`.
|
|
23
24
|
"user",
|
|
24
25
|
"comments",
|
|
@@ -102,6 +103,13 @@ export const CAPABILITIES = {
|
|
|
102
103
|
* (it shares the realm): UI hints for the host, never permissions.
|
|
103
104
|
*/
|
|
104
105
|
annotate: { defaultGates: [rate(120)], served: "event" },
|
|
106
|
+
/**
|
|
107
|
+
* Find in page (P131): the host's find bar asks the shell to find the person's words in the
|
|
108
|
+
* content and highlight them; the shell answers how many and which is current, and says when
|
|
109
|
+
* the person pressed the find shortcut in the frame. The query goes into the content's realm,
|
|
110
|
+
* which can read it; what the frame says back is the content's word: a find bar's numbers.
|
|
111
|
+
*/
|
|
112
|
+
find: { defaultGates: [rate(120)], served: "event" },
|
|
105
113
|
/** Who is viewing (P087): answered from the viewer the host gave the display. */
|
|
106
114
|
user: { defaultGates: [rate(60)], served: "viewer", request: { method: "porthole/call" } },
|
|
107
115
|
/** Opens the host's comment composer at the page's anchor (P090): write-only. */
|
package/dist/config/schema.d.ts
CHANGED
|
@@ -249,6 +249,19 @@ export interface PortholeConfig {
|
|
|
249
249
|
* page has no storage of its own (an in-memory stand-in) and fetches nothing with a cookie.
|
|
250
250
|
*/
|
|
251
251
|
readonly nested?: true;
|
|
252
|
+
/**
|
|
253
|
+
* Which nested frames content may make (P128). `none` (default, and absent): the shell removes
|
|
254
|
+
* every frame-like element content adds, and the CSP's `frame-src` is `'none'`. `own`: an
|
|
255
|
+
* `<iframe>` of one of the page's own files (its `src` under its version's own address, P082)
|
|
256
|
+
* and a `srcdoc` one load and run; frames of other sites, `<frame>`, `<object>` and `<embed>`
|
|
257
|
+
* are still removed, and a served file set's `frame-src` opens its version's own path only.
|
|
258
|
+
* A weakening, opted into: a child frame is a realm of its own, where the shell's WebRTC
|
|
259
|
+
* removal, clipboard guards and navigation cancel never ran (a page of the set framed there has
|
|
260
|
+
* its own shell; a `srcdoc` frame, or the `about:blank` a new frame starts as, has none), so
|
|
261
|
+
* content reaches WebRTC and the clipboard's events there. Not for url mode, a live widget
|
|
262
|
+
* (no network of its own, P079) or a nested page (P111).
|
|
263
|
+
*/
|
|
264
|
+
readonly nestedFrames?: "none" | "own";
|
|
252
265
|
}
|
|
253
266
|
export interface StorageConfig {
|
|
254
267
|
/**
|
package/dist/config/validate.js
CHANGED
|
@@ -271,6 +271,7 @@ export function validateConfig(input, options = {}) {
|
|
|
271
271
|
"errors",
|
|
272
272
|
"runtime",
|
|
273
273
|
"nested",
|
|
274
|
+
"nestedFrames",
|
|
274
275
|
], "config");
|
|
275
276
|
if (!MODES.includes(config.mode)) {
|
|
276
277
|
fail("config.mode", `must be one of ${MODES.join(", ")}`);
|
|
@@ -563,6 +564,20 @@ export function validateConfig(input, options = {}) {
|
|
|
563
564
|
fail("config.nested", "a nested page can't load Porthole's libraries from its origin yet");
|
|
564
565
|
}
|
|
565
566
|
}
|
|
567
|
+
// A page's own nested frames (P128): opted into, never a default.
|
|
568
|
+
if (config.nestedFrames !== undefined) {
|
|
569
|
+
if (config.nestedFrames !== "none" && config.nestedFrames !== "own") {
|
|
570
|
+
fail("config.nestedFrames", 'must be "none" or "own", or left out');
|
|
571
|
+
}
|
|
572
|
+
if (config.nestedFrames === "own" && config.mode === "url") {
|
|
573
|
+
fail("config.nestedFrames", "url mode has no shell: its app's frames are its own");
|
|
574
|
+
}
|
|
575
|
+
// A nested page's frames have an opaque ancestor, which no frame-ancestors source matches:
|
|
576
|
+
// none of its own files would load in one. Not measured yet.
|
|
577
|
+
if (config.nestedFrames === "own" && config.nested === true) {
|
|
578
|
+
fail("config.nestedFrames", 'a nested page (P111) has no "own" frames yet: leave it out');
|
|
579
|
+
}
|
|
580
|
+
}
|
|
566
581
|
if (config.errors !== undefined) {
|
|
567
582
|
if (config.errors !== "agent" && config.errors !== "host" && config.errors !== "none") {
|
|
568
583
|
fail("config.errors", 'must be "agent", "host" or "none"');
|