@botiverse/porthole 0.3.4 → 0.4.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 +2 -0
- package/dist/check/lint.js +17 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +14 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +40 -12
- package/dist/presets/presets.d.ts +3 -2
- package/dist/presets/presets.js +7 -2
- package/docs/ADOPTING.md +43 -0
- package/docs/DECISIONS.md +52 -0
- package/docs/DESIGN.md +6 -3
- package/package.json +1 -1
- package/src/check/lint.ts +27 -0
- package/src/check/page.ts +16 -0
- package/src/guide/guide.ts +49 -12
- package/src/presets/presets.ts +7 -2
package/dist/guide/guide.d.ts
CHANGED
|
@@ -12,6 +12,8 @@ export type BuiltInTopic = (typeof BUILT_IN_TOPICS)[number];
|
|
|
12
12
|
export type GuideTopic = BuiltInTopic | (string & {});
|
|
13
13
|
/** What the manual calls `https:` (any https site), where a config opens passive kinds to it. */
|
|
14
14
|
export declare const ANY_HTTPS_SITE = "any https site";
|
|
15
|
+
/** The copy of Plotly's map shapes (topojson) to give it, on jsDelivr (P078). */
|
|
16
|
+
export declare const PLOTLY_TOPOJSON_URL = "https://cdn.jsdelivr.net/npm/plotly.js@3.4.0/dist/topojson/";
|
|
15
17
|
/** The manual for `topics`, in the order asked (all built-in topics by default). */
|
|
16
18
|
export declare function generateGuide(config: PortholeConfig, topics?: readonly GuideTopic[]): string;
|
|
17
19
|
/** The description of the host's show tool, for the agent's tool list. */
|
package/dist/guide/guide.js
CHANGED
|
@@ -39,6 +39,13 @@ const KIND_WORDS = {
|
|
|
39
39
|
};
|
|
40
40
|
/** What the manual calls `https:` (any https site), where a config opens passive kinds to it. */
|
|
41
41
|
export const ANY_HTTPS_SITE = "any https site";
|
|
42
|
+
/** Kinds in words, as a list: "fonts, images, audio and video" (media's two words are two items). */
|
|
43
|
+
const kindsInWords = (kinds) => {
|
|
44
|
+
const words = kinds.flatMap((kind) => kind === "media" ? ["audio", "video"] : [KIND_WORDS[kind]]);
|
|
45
|
+
return words.length === 1
|
|
46
|
+
? (words[0] ?? "")
|
|
47
|
+
: `${words.slice(0, -1).join(", ")} and ${words.at(-1)}`;
|
|
48
|
+
};
|
|
42
49
|
/** The sources content may load `kind` from, as the manual names them: origins, any https site. */
|
|
43
50
|
const sourcesFor = (config, kind) => [
|
|
44
51
|
...(anyHttps(config, kind) ? [ANY_HTTPS_SITE] : []),
|
|
@@ -60,20 +67,44 @@ function network(config) {
|
|
|
60
67
|
byOrigin.set(origin, [...(byOrigin.get(origin) ?? []), kind]);
|
|
61
68
|
}
|
|
62
69
|
}
|
|
70
|
+
// Any https site last, the widest: "…; fonts, images, audio and video from any https site" (P059).
|
|
71
|
+
const anywhere = byOrigin.get(ANY_HTTPS_SITE);
|
|
72
|
+
byOrigin.delete(ANY_HTTPS_SITE);
|
|
63
73
|
const groups = new Map();
|
|
64
74
|
for (const [origin, each] of byOrigin) {
|
|
65
|
-
const
|
|
66
|
-
const key = words.length === 1
|
|
67
|
-
? (words[0] ?? "")
|
|
68
|
-
: `${words.slice(0, -1).join(", ")} and ${words.at(-1)}`;
|
|
75
|
+
const key = kindsInWords(each);
|
|
69
76
|
groups.set(key, [...(groups.get(key) ?? []), origin]);
|
|
70
77
|
}
|
|
71
|
-
const parts = [
|
|
78
|
+
const parts = [
|
|
79
|
+
...[...groups].map(([words, origins]) => `${words} from ${origins.join(", ")}`),
|
|
80
|
+
...(anywhere === undefined ? [] : [`${kindsInWords(anywhere)} from ${ANY_HTTPS_SITE}`]),
|
|
81
|
+
];
|
|
72
82
|
return `Network: only ${parts.join("; ")}. Anything else fails.`;
|
|
73
83
|
}
|
|
74
84
|
/** Whether a whole document takes the theme only when it declares support (ThemeConfig.documents). */
|
|
75
85
|
const optsIn = (config) => config.mode === "artifact" && (config.theme.documents ?? "declared") === "declared";
|
|
76
86
|
const loadsScripts = (config) => egressOrigins(config, "script").length > 0;
|
|
87
|
+
/** The copy of Plotly's map shapes (topojson) to give it, on jsDelivr (P078). */
|
|
88
|
+
export const PLOTLY_TOPOJSON_URL = "https://cdn.jsdelivr.net/npm/plotly.js@3.4.0/dist/topojson/";
|
|
89
|
+
/**
|
|
90
|
+
* Libraries with CDNs of their own, where the config opens them for scripts (P078): how to load
|
|
91
|
+
* each, pinned, and what it needs that the sandbox closes. Verified in the sandbox, each preset.
|
|
92
|
+
*/
|
|
93
|
+
function ownCdns(config) {
|
|
94
|
+
const scripts = egressOrigins(config, "script");
|
|
95
|
+
const said = [];
|
|
96
|
+
if (scripts.includes("https://cdn.tailwindcss.com")) {
|
|
97
|
+
said.push('- Tailwind: <script src="https://cdn.tailwindcss.com/3.4.17"></script> (the Play CDN builds the CSS as the page runs; its console warning about production is expected).');
|
|
98
|
+
}
|
|
99
|
+
if (scripts.includes("https://code.jquery.com")) {
|
|
100
|
+
said.push('- jQuery: <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>.');
|
|
101
|
+
}
|
|
102
|
+
if (scripts.includes("https://cdn.plot.ly")) {
|
|
103
|
+
const shapes = egressOrigins(config, "connect").includes("https://cdn.jsdelivr.net");
|
|
104
|
+
said.push(`- Plotly: <script src="https://cdn.plot.ly/plotly-3.4.0.min.js"></script>. Its maps (scattergeo, choropleth) fetch their shapes from cdn.plot.ly as they draw, which is closed here: ${shapes ? `give them the copy on jsDelivr, Plotly.newPlot(box, data, layout, { topojsonURL: "${PLOTLY_TOPOJSON_URL}" }).` : "they don't draw; use a scatter or a table."}`);
|
|
105
|
+
}
|
|
106
|
+
return said;
|
|
107
|
+
}
|
|
77
108
|
function widget(c) {
|
|
78
109
|
const { config, noun } = c;
|
|
79
110
|
const { layout, limits } = config;
|
|
@@ -96,7 +127,7 @@ function widget(c) {
|
|
|
96
127
|
? null
|
|
97
128
|
: "- No position: fixed: the frame grows with its content, so a fixed element covers it.", "", "The sandbox:", ...stated.filter((limit) => limit.topic === "sandbox").map((limit) => `- ${limit.text}`), `Keep it under ${sizeWords(limits.maxBytes)}.`, loadsScripts(config)
|
|
98
129
|
? "\nLibraries: pin an exact version at least two weeks old (chart.js@4.4.1 in its URL), never @latest or a range, so the code can't be swapped under you and draws the same every time."
|
|
99
|
-
: null, "", themeless
|
|
130
|
+
: null, ...ownCdns(config), "", themeless
|
|
100
131
|
? `Colors: these variables hold the app's palette; use them, or colors of your own. Give the ${noun} its own background.`
|
|
101
132
|
: optsIn(config)
|
|
102
133
|
? `Colors, for a ${noun} that declares light and dark: every color from these variables, never hard-coded, so both work; its own background then stays transparent (it sits on the app's surface).`
|
|
@@ -246,12 +277,9 @@ export function generateToolDescription(config) {
|
|
|
246
277
|
const origins = [
|
|
247
278
|
...new Set(["script", "style", "font", "img", "media", "connect"].flatMap((kind) => egressOrigins(config, kind))),
|
|
248
279
|
];
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
const fromAnywhere = passive.length === 0
|
|
253
|
-
? ""
|
|
254
|
-
: `${passive.length === 1 ? passive[0] : `${passive.slice(0, -1).join(", ")} and ${passive.at(-1)}`} from ${ANY_HTTPS_SITE}`;
|
|
280
|
+
// The same words, in the same order, as the manual's Network line.
|
|
281
|
+
const passive = ["font", "img", "media"].filter((kind) => anyHttps(config, kind));
|
|
282
|
+
const fromAnywhere = passive.length === 0 ? "" : `${kindsInWords(passive)} from ${ANY_HTTPS_SITE}`;
|
|
255
283
|
const net = origins.length === 0 && fromAnywhere === ""
|
|
256
284
|
? "with no network (nothing loads from outside)"
|
|
257
285
|
: origins.length === 0
|
|
@@ -48,8 +48,9 @@ export interface UrlPresetOptions {
|
|
|
48
48
|
}
|
|
49
49
|
/**
|
|
50
50
|
* Library CDNs a host may open with one line (`egress: LIBRARY_CDNS`): read-only package caches
|
|
51
|
-
* for scripts, styles, fonts, images and data, plus Google Fonts
|
|
52
|
-
*
|
|
51
|
+
* for scripts, styles, fonts, images and data, plus Google Fonts, and three libraries' own CDNs
|
|
52
|
+
* for their scripts only (Tailwind's Play CDN, jQuery, Plotly; P078). Not on by default: every
|
|
53
|
+
* preset starts with egress closed.
|
|
53
54
|
*/
|
|
54
55
|
export declare const LIBRARY_CDNS: EgressConfig;
|
|
55
56
|
export declare const presets: {
|
package/dist/presets/presets.js
CHANGED
|
@@ -2,8 +2,9 @@ import { validateConfig } from "../config/validate.js";
|
|
|
2
2
|
import { DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES } from "../theme/variables.js";
|
|
3
3
|
/**
|
|
4
4
|
* Library CDNs a host may open with one line (`egress: LIBRARY_CDNS`): read-only package caches
|
|
5
|
-
* for scripts, styles, fonts, images and data, plus Google Fonts
|
|
6
|
-
*
|
|
5
|
+
* for scripts, styles, fonts, images and data, plus Google Fonts, and three libraries' own CDNs
|
|
6
|
+
* for their scripts only (Tailwind's Play CDN, jQuery, Plotly; P078). Not on by default: every
|
|
7
|
+
* preset starts with egress closed.
|
|
7
8
|
*/
|
|
8
9
|
export const LIBRARY_CDNS = {
|
|
9
10
|
script: [
|
|
@@ -11,6 +12,10 @@ export const LIBRARY_CDNS = {
|
|
|
11
12
|
"https://cdn.jsdelivr.net",
|
|
12
13
|
"https://unpkg.com",
|
|
13
14
|
"https://esm.sh",
|
|
15
|
+
// Libraries' own CDNs, scripts only (P078): Tailwind's Play CDN, jQuery, Plotly.
|
|
16
|
+
"https://cdn.tailwindcss.com",
|
|
17
|
+
"https://code.jquery.com",
|
|
18
|
+
"https://cdn.plot.ly",
|
|
14
19
|
],
|
|
15
20
|
style: [
|
|
16
21
|
"https://cdnjs.cloudflare.com",
|
package/docs/ADOPTING.md
CHANGED
|
@@ -42,6 +42,49 @@ manual tells the agent so (the page scrolls itself; `position: fixed` works). `M
|
|
|
42
42
|
and `<PortholeFrame fill>` are deprecated: they size the frame but leave the manual saying the
|
|
43
43
|
height follows the content.
|
|
44
44
|
|
|
45
|
+
### Choosing egress
|
|
46
|
+
|
|
47
|
+
Egress is what content may load and send out: scripts, styles, fonts, images, audio and video, and
|
|
48
|
+
data (fetch, WebSocket). Every preset starts closed, and a kind opens more only through its
|
|
49
|
+
`options.egress`. There are three levels:
|
|
50
|
+
|
|
51
|
+
| Level | Config (`options`) | What it opens | The risk it re-opens | Typical host | The agent's manual says | Why | Tested by |
|
|
52
|
+
| --- | --- | --- | --- | --- | --- | --- | --- |
|
|
53
|
+
| **Closed** (the default) | nothing to write | Nothing from outside the frame: content runs on what it carries (inline code, `data:` and `blob:` URLs). | None. | Widgets that draw their own SVG and CSS; any host that hasn't decided yet. | `Network: none. Nothing loads from outside` (and `write everything inline`) | [P006](DECISIONS.md#p006--2026-10-11--egress-is-closed-by-default-including-channels-a-frame-csp-doesnt-cover--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted) | probes `1.connect`, `2.resources`, `3.webrtc`, `4.*` (nested frames), `5.*` (navigating out), `8.*` (resource hints), `10.self`; served `served.domain.egress` |
|
|
54
|
+
| **Library CDNs** (`LIBRARY_CDNS`, plus script hosts of your own) | `egress: LIBRARY_CDNS`; more script hosts: `egress: { ...LIBRARY_CDNS, script: [...LIBRARY_CDNS.script, "https://cdn.example.com"] }` | Scripts, styles, fonts, images and data from cdnjs, jsDelivr, unpkg and esm.sh; Google Fonts; scripts only from three libraries' own CDNs (Tailwind's Play CDN, jQuery, Plotly). Nothing else. | Code you don't control runs in the frame (a compromised or look-alike package), still inside the sandbox and egress; and a path requested from a CDN is a narrow channel out, read by the CDN's operator. The manual tells agents to pin versions. | Ferry's widgets, Raft Artifacts' pages: agents load Chart.js, ECharts, d3, Mermaid, Tailwind, jQuery, Plotly. | `scripts, styles, fonts, images and data (fetch, WebSocket) from https://cdnjs.cloudflare.com` …, `scripts from https://cdn.tailwindcss.com, https://code.jquery.com, https://cdn.plot.ly` and `pin an exact version` | [P078](DECISIONS.md#p078--2026-10-13--library_cdns-adds-tailwinds-jquerys-and-plotlys-own-cdns-for-scripts-only--accepted), [P022](DECISIONS.md#p022--2026-10-11--every-preset-starts-with-egress-closed-library-cdns-are-a-one-line-opt-in--accepted), [P048](DECISIONS.md#p048--2026-10-11--artifact-pages-reach-library-cdns-only-by-the-hosts-config--accepted) | `leak/cdn.spec.ts` (a CDN library loads only when the config opens it, opaque and served; another origin never; the libraries' own CDNs serve scripts and nothing else); probes `1.connect`, `2.resources` (an allowed origin loads, no other does) |
|
|
55
|
+
| **Passive from any https site** (`anyHttps`, on top of either) | `egress: { ...LIBRARY_CDNS, anyHttps: ["img"] }`; closed but for them: `egress: { anyHttps: ["img"] }` | The passive kinds you name (`img`, `media`, `font`) from any https site. Never scripts, styles, data, workers or frames, and never `http:`: a config naming another kind is refused. | Any site an image names learns that someone viewed the content, and from which address; content can send data out in an image URL to a server of its choosing (the channel P006 closes); whoever owns an image controls what it shows, inside the frame. | A host showing content that already exists, with hotlinked media: Raft's HTML attachment previews, reports whose `<img>` point at other sites (the case P059 was written for). | `images from any https site` (`fonts, images, audio and video from any https site` for all three) | [P059](DECISIONS.md#p059--2026-10-11--passive-content-may-load-from-any-https-site-by-the-hosts-explicit-choice--accepted), [P062](DECISIONS.md#p062--2026-10-11--serveddomainegress-holds-a-host-to-its-own-configs-egress--accepted) | `leak/cdn.spec.ts` (a hotlinked image loads; a script, a stylesheet and a fetch to the same site never reach it; without the flag, nothing does); served `served.domain.egress` (the image must reach an https canary; scripts, styles, fetches and frames never), `leak/served/any-https.spec.ts` |
|
|
56
|
+
|
|
57
|
+
How to decide: **start closed; add `LIBRARY_CDNS` if agents use libraries; add passive `anyHttps`
|
|
58
|
+
only for existing content with hotlinks**, and only the kinds it hotlinks (usually `img`). An
|
|
59
|
+
agent writing new content can inline what it shows, so agent-made pages never need `anyHttps`.
|
|
60
|
+
|
|
61
|
+
```js
|
|
62
|
+
import { defineDisplays, LIBRARY_CDNS } from "@botiverse/porthole";
|
|
63
|
+
|
|
64
|
+
export const displays = defineDisplays({
|
|
65
|
+
// Closed: nothing to write.
|
|
66
|
+
widget: { preset: "inlineWidget" },
|
|
67
|
+
// Library CDNs (and, if you need one, a script host of your own).
|
|
68
|
+
artifact: { preset: "artifact", options: { egress: { ...LIBRARY_CDNS, script: [...(LIBRARY_CDNS.script ?? []), "https://cdn.example.com"] } } },
|
|
69
|
+
// Existing pages with hotlinked images: Library CDNs, and images from any https site.
|
|
70
|
+
attachment: { preset: "artifact", options: { egress: { ...LIBRARY_CDNS, anyHttps: ["img"] } } },
|
|
71
|
+
});
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- Each kind's documents name it as their preset (`document.preset: "attachment"`); `egress` is
|
|
75
|
+
the kind's whole policy, so kinds that differ in egress are kinds of their own.
|
|
76
|
+
- The libraries' own CDNs serve scripts only (P078). Plotly's maps fetch their shapes from
|
|
77
|
+
`cdn.plot.ly`, which stays closed, so the manual gives agents the copy on jsDelivr
|
|
78
|
+
(`topojsonURL`); Tailwind's Play CDN builds its CSS in the page and needs nothing more.
|
|
79
|
+
- Origins are exact (`https://cdn.example.com`), or `https://*.` a domain of your own; a wildcard
|
|
80
|
+
over a public suffix (`*.com`, `*.github.io`) is refused.
|
|
81
|
+
- An opaque frame also inherits your page's CSP ([P058](DECISIONS.md#p058--2026-10-11--an-opaque-frame-is-as-closed-as-its-page-the-suite-says-when-a-case-cant-be-observed--accepted)): where your page closes images or
|
|
82
|
+
fetches, opaque content is that closed whatever its egress opens (see "The page's CSP"). A
|
|
83
|
+
served frame has only its own policy.
|
|
84
|
+
- `checkPage` and `lintContent` tell the agent when its content reaches past the kind's egress, by
|
|
85
|
+
directive. The manual names exactly the origins the CSP allows (`test/agreement.test.ts`), and
|
|
86
|
+
DESIGN.md § "Egress hardening, each with its test" is the long form.
|
|
87
|
+
|
|
45
88
|
## 3. Opaque displays: the page only
|
|
46
89
|
|
|
47
90
|
```js
|
package/docs/DECISIONS.md
CHANGED
|
@@ -2160,3 +2160,55 @@ its origin is named from it.
|
|
|
2160
2160
|
opaque (failing on 0.3.3 for opaque); for an opaque frame, the instance is in none of the frame's
|
|
2161
2161
|
attributes, its document, its address or name, nor any message its page heard.
|
|
2162
2162
|
|
|
2163
|
+
## P078 · 2026-10-13 · LIBRARY_CDNS adds Tailwind's, jQuery's and Plotly's own CDNs, for scripts only · Accepted
|
|
2164
|
+
|
|
2165
|
+
**Decision.** `LIBRARY_CDNS.script` adds `https://cdn.tailwindcss.com` (Tailwind's Play CDN),
|
|
2166
|
+
`https://code.jquery.com` and `https://cdn.plot.ly` (#11). Scripts only: none of them is in
|
|
2167
|
+
`style`, `img`, `font` or `connect`. They are the class P048 opened: a library's own CDN, serving
|
|
2168
|
+
versioned static files, whose access logs a content author can't read. Agent-made pages load them
|
|
2169
|
+
often (Claude's artifacts allow them too), and one list serves every host, so the manual reads
|
|
2170
|
+
the same everywhere: Raft's HTML attachment previews and Artifacts, and Ferry. Raft Artifacts'
|
|
2171
|
+
own list of these hosts (`PAGE_SCRIPT_HOSTS`) can go.
|
|
2172
|
+
|
|
2173
|
+
**Existing hosts widen on upgrade.** Every host that passes `LIBRARY_CDNS` (Ferry's widgets, Raft
|
|
2174
|
+
Artifacts) gets the three when it takes 0.4.0, with no change of its own. That is acceptable:
|
|
2175
|
+
- The risk is P048's, unchanged in kind. Code the host doesn't control runs in the frame, still
|
|
2176
|
+
in the sandbox and under egress. A requested path is a narrow channel out whose reader is the
|
|
2177
|
+
CDN's operator. These hosts serve scripts and nothing else, so no data comes back from them.
|
|
2178
|
+
- A host that passes `LIBRARY_CDNS` has chosen "read-only public library CDNs", and these are
|
|
2179
|
+
that.
|
|
2180
|
+
- A host that wants the old list writes it out: `egress: { ...LIBRARY_CDNS, script: [its four] }`.
|
|
2181
|
+
- The minor version (0.4.0) says a preset's list widened.
|
|
2182
|
+
|
|
2183
|
+
**The manual** names the three in its Network line, as it names every origin it opens, and gives
|
|
2184
|
+
each a line under Libraries with a pinned URL: Tailwind 3.4.17, jQuery 3.7.1, Plotly 3.4.0.
|
|
2185
|
+
- **Plotly's maps** (scattergeo, choropleth) fetch their shapes (topojson) from `cdn.plot.ly` as
|
|
2186
|
+
they draw, which `connect-src` closes. The manual gives them the copy on jsDelivr, whose data
|
|
2187
|
+
`LIBRARY_CDNS` opens: `Plotly.newPlot(box, data, layout, { topojsonURL:
|
|
2188
|
+
"https://cdn.jsdelivr.net/npm/plotly.js@3.4.0/dist/topojson/" })`. That copy is byte for byte
|
|
2189
|
+
what `cdn.plot.ly/un/` serves to Plotly 4.1 today (checked). Where jsDelivr's data isn't open,
|
|
2190
|
+
the manual says the maps don't draw. Opening `connect` to `cdn.plot.ly` would be a decision of
|
|
2191
|
+
its own.
|
|
2192
|
+
- **Tailwind's Play CDN** builds its CSS as the page runs: it injects a `<style>`
|
|
2193
|
+
(`style-src 'unsafe-inline'`, which every preset has) and needs nothing the CSP closes, so the
|
|
2194
|
+
CSP doesn't change. Its console warning about production is expected, and the manual says so.
|
|
2195
|
+
- **`lintContent`** asks for a version in the path from these hosts: Tailwind's bare URL
|
|
2196
|
+
redirects to its latest, and `jquery-latest` and `plotly-latest` are moving names.
|
|
2197
|
+
|
|
2198
|
+
**Verified** against the real CDNs (`scripts/verify-libraries.ts`, 2026-10-13): the manual's own
|
|
2199
|
+
lines (Tailwind styling an element, jQuery running, a Plotly map drawing its land from the
|
|
2200
|
+
jsDelivr copy) under the inline widget, artifact (opaque and served) and MCP Apps presets, on
|
|
2201
|
+
Chromium, WebKit and Firefox: 45 of 45. Without `topojsonURL`, the map fails, and `checkPage`
|
|
2202
|
+
reports the `connect-src` block of `cdn.plot.ly/un/world_110m.json`.
|
|
2203
|
+
**Tested.** `leak/cdn.spec.ts` (routed, three engines): a script loads from each of the three, and a
|
|
2204
|
+
stylesheet, an image and a fetch never reach them, opaque and served. `test/policy.test.ts`: the
|
|
2205
|
+
hosts are in `script-src` only. `test/check.test.ts`: the manual's lines and the lint.
|
|
2206
|
+
**Also in 0.4.0: nobody clicks in a check.** Running the suite on Firefox showed that
|
|
2207
|
+
`checkPage`'s own evaluations in the page count as a gesture there, so a call on load that needs a
|
|
2208
|
+
click (`downloadFile`, and `sendPrompt` where the shell let it through) reached the host as if
|
|
2209
|
+
clicked, and was reported as a note instead of the refusal people's browsers give. The check page
|
|
2210
|
+
now mounts with a platform that reports no user activation: a call on load that needs a click is
|
|
2211
|
+
refused, and reported as a problem, on every engine (`leak/check.spec.ts`).
|
|
2212
|
+
**Revisit when** a host needs one of them for anything but scripts, or Raft's trace of blocked
|
|
2213
|
+
loads (its follow-up) proposes more hosts, such as mirrors reachable from mainland China.
|
|
2214
|
+
|
package/docs/DESIGN.md
CHANGED
|
@@ -581,7 +581,8 @@ What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the
|
|
|
581
581
|
Apps view (as a page with the view's egress) and a driver without `serve` run opaque. Each
|
|
582
582
|
inline script is named (`//# sourceURL=porthole-script-<n>`) and its first line recorded, so an
|
|
583
583
|
error's line is the content's own line, as lint numbers it. Every host function the config
|
|
584
|
-
declares is answered as a host that declines (`confirm` says no; each handler answers no
|
|
584
|
+
declares is answered as a host that declines (`confirm` says no; each handler answers no; no
|
|
585
|
+
call comes from a click, P078), and
|
|
585
586
|
each call the host sees is reported (`run.calls`): refused by a gate whatever the person says (no
|
|
586
587
|
click, bad arguments, too often) a problem, declined or answered a note. A global the shell
|
|
587
588
|
refuses itself without a click (`sendPrompt`) rejects in the content, so it shows as an error. The report's `text` names each
|
|
@@ -748,7 +749,9 @@ absent.
|
|
|
748
749
|
|
|
749
750
|
## Egress hardening, each with its test
|
|
750
751
|
|
|
751
|
-
Closed by default; opened only to origins the config declares.
|
|
752
|
+
Closed by default; opened only to origins the config declares. For a host choosing a level
|
|
753
|
+
(closed, library CDNs, passive media from any https site), ADOPTING.md § "Choosing egress" is the
|
|
754
|
+
summary; this section is the long form. The leak suite
|
|
752
755
|
(`src/conformance/probes.ts`, run by `pnpm test:leak` against the reference host)
|
|
753
756
|
attempts each channel from inside the content, as an agent's code would, and asserts
|
|
754
757
|
with an out-of-band oracle that nothing left: an HTTP canary that also counts raw TCP
|
|
@@ -819,7 +822,7 @@ for that to lapse and click with raw input.
|
|
|
819
822
|
|------|-----------|-------|------------------|
|
|
820
823
|
| The host's check (P050) | `authorize.check` after a ticket or cookie verifies, before anything is served; a deny is a 403 page saying `denied` and the host's code, and the display's `outcome` says so even after `loaded` | `leak/served/authorize.spec.ts`: a revoked subject's ticket (a page, an app); a framed app's next request and reload mid-session (Chromium, Firefox: WebKit keeps no framed cookie, P025); a framed page's next load; an app and a page in a tab | `authorize` → every case but WebKit's framed page (`session` either way) |
|
|
821
824
|
| Url-mode delegation (P049) | `allow` from `permissions`, `""` by default | `leak/served/permissions.spec.ts`: full screen follows it on all three; clipboard writes on Chromium only (WebKit and Firefox let any frame write in a click) | `url-permissions` → the default case (all three) |
|
|
822
|
-
| Library CDNs for artifacts (P048) | `egress: LIBRARY_CDNS` in the host's artifact config; closed by default (P022) | `leak/cdn.spec.ts`: opaque and served, a CDN library loads only when opened; another origin never | — (the CSP of rows 1–2) |
|
|
825
|
+
| Library CDNs for artifacts (P048, P078) | `egress: LIBRARY_CDNS` in the host's artifact config; closed by default (P022); Tailwind's, jQuery's and Plotly's own CDNs for scripts only | `leak/cdn.spec.ts`: opaque and served, a CDN library loads only when opened; another origin never; a stylesheet, an image and a fetch never reach the libraries' own CDNs | — (the CSP of rows 1–2) |
|
|
823
826
|
| Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
|
|
824
827
|
|
|
825
828
|
### The clipboard, and copy buttons
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"bin": {
|
package/src/check/lint.ts
CHANGED
|
@@ -84,6 +84,24 @@ const REACHES: readonly { readonly kind: EgressKind; readonly pattern: RegExp }[
|
|
|
84
84
|
const CDN_PACKAGE =
|
|
85
85
|
/^https:\/\/(?:cdn\.jsdelivr\.net\/npm|unpkg\.com|esm\.sh)\/((?:@[^/]+\/)?[^/@]+)(@[^/]*)?/u;
|
|
86
86
|
|
|
87
|
+
/**
|
|
88
|
+
* Libraries' own CDNs (P078): the version is in the path (`/3.4.17`, `jquery-3.7.1.min.js`,
|
|
89
|
+
* `plotly-3.4.0.min.js`); without it the host serves its latest (Tailwind redirects to it).
|
|
90
|
+
*/
|
|
91
|
+
const OWN_CDN: readonly {
|
|
92
|
+
readonly name: string;
|
|
93
|
+
readonly host: RegExp;
|
|
94
|
+
readonly pinned: RegExp;
|
|
95
|
+
}[] = [
|
|
96
|
+
{
|
|
97
|
+
name: "Tailwind",
|
|
98
|
+
host: /^https:\/\/cdn\.tailwindcss\.com(?:[/?#]|$)/u,
|
|
99
|
+
pinned: /^\/\d+\.\d+\.\d+/u,
|
|
100
|
+
},
|
|
101
|
+
{ name: "jQuery", host: /^https:\/\/code\.jquery\.com\//u, pinned: /\d+\.\d+\.\d+/u },
|
|
102
|
+
{ name: "Plotly", host: /^https:\/\/cdn\.plot\.ly\/plotly/u, pinned: /\d+\.\d+\.\d+/u },
|
|
103
|
+
];
|
|
104
|
+
|
|
87
105
|
export function lintContent(config: PortholeConfig, content: string): Finding[] {
|
|
88
106
|
if (config.mode === "url") {
|
|
89
107
|
return [];
|
|
@@ -203,6 +221,15 @@ export function lintContent(config: PortholeConfig, content: string): Finding[]
|
|
|
203
221
|
match.index,
|
|
204
222
|
);
|
|
205
223
|
}
|
|
224
|
+
const own = OWN_CDN.find((each) => each.host.test(address));
|
|
225
|
+
if (own !== undefined && kind === "script" && !own.pinned.test(new URL(address).pathname)) {
|
|
226
|
+
add(
|
|
227
|
+
"unpinned",
|
|
228
|
+
"warning",
|
|
229
|
+
`Pin an exact version of ${own.name} (its version in the URL's path), never its latest: the code then can't change under the ${it}.`,
|
|
230
|
+
match.index,
|
|
231
|
+
);
|
|
232
|
+
}
|
|
206
233
|
const pinned = CDN_PACKAGE.exec(address);
|
|
207
234
|
if (pinned !== null && (pinned[2] === undefined || !/^@\d+\.\d+\.\d+/u.test(pinned[2]))) {
|
|
208
235
|
add(
|
package/src/check/page.ts
CHANGED
|
@@ -5,6 +5,8 @@ import {
|
|
|
5
5
|
type HandledCapability,
|
|
6
6
|
} from "../config/capabilities.ts";
|
|
7
7
|
import { createHost } from "../host/create-host.ts";
|
|
8
|
+
import type { PlatformHost } from "../platform/types.ts";
|
|
9
|
+
import { webPlatform } from "../platform/web.ts";
|
|
8
10
|
import type { DisplayHandle } from "../host/types.ts";
|
|
9
11
|
import type { FrameLocation } from "../isolation/types.ts";
|
|
10
12
|
import {
|
|
@@ -35,6 +37,19 @@ const DECLINED: { readonly [N in HandledCapability]: () => unknown } = {
|
|
|
35
37
|
},
|
|
36
38
|
};
|
|
37
39
|
|
|
40
|
+
/**
|
|
41
|
+
* The web platform, with no person on the page: no call comes from a click (P078). The driver's
|
|
42
|
+
* own evaluations count as gestures in some engines (Firefox), which would let a call on load
|
|
43
|
+
* through a host's gesture check; nobody clicks in a check.
|
|
44
|
+
*/
|
|
45
|
+
const NOBODY: PlatformHost = {
|
|
46
|
+
name: "web, unattended",
|
|
47
|
+
createSurface(container, spec) {
|
|
48
|
+
const surface = webPlatform.createSurface(container, spec);
|
|
49
|
+
return { ...surface, userActivation: () => false };
|
|
50
|
+
},
|
|
51
|
+
};
|
|
52
|
+
|
|
38
53
|
/** A handler for each host function the config declares: it notes the call and answers no. */
|
|
39
54
|
function declining(capabilities: readonly string[], calls: CheckCall[]): CapabilityHandlers {
|
|
40
55
|
const handlers: Record<string, () => unknown> = {};
|
|
@@ -149,6 +164,7 @@ const check = {
|
|
|
149
164
|
// Every host function the config declares, answered as a host that declines (P074): a
|
|
150
165
|
// person asked to confirm says no, a handler says no, and each call is noted.
|
|
151
166
|
handlers: declining(Object.keys(spec.config.capabilities), calls),
|
|
167
|
+
platform: NOBODY,
|
|
152
168
|
confirm: () => Promise.resolve("declined"),
|
|
153
169
|
// A served config's instance, issued by the check's own server on this page's origin.
|
|
154
170
|
locator: {
|
package/src/guide/guide.ts
CHANGED
|
@@ -87,6 +87,16 @@ const KIND_WORDS: Readonly<Record<EgressKind, string>> = {
|
|
|
87
87
|
/** What the manual calls `https:` (any https site), where a config opens passive kinds to it. */
|
|
88
88
|
export const ANY_HTTPS_SITE = "any https site";
|
|
89
89
|
|
|
90
|
+
/** Kinds in words, as a list: "fonts, images, audio and video" (media's two words are two items). */
|
|
91
|
+
const kindsInWords = (kinds: readonly EgressKind[]): string => {
|
|
92
|
+
const words = kinds.flatMap((kind) =>
|
|
93
|
+
kind === "media" ? ["audio", "video"] : [KIND_WORDS[kind]],
|
|
94
|
+
);
|
|
95
|
+
return words.length === 1
|
|
96
|
+
? (words[0] ?? "")
|
|
97
|
+
: `${words.slice(0, -1).join(", ")} and ${words.at(-1)}`;
|
|
98
|
+
};
|
|
99
|
+
|
|
90
100
|
/** The sources content may load `kind` from, as the manual names them: origins, any https site. */
|
|
91
101
|
const sourcesFor = (config: PortholeConfig, kind: EgressKind): string[] => [
|
|
92
102
|
...(anyHttps(config, kind) ? [ANY_HTTPS_SITE] : []),
|
|
@@ -109,16 +119,18 @@ function network(config: PortholeConfig): string {
|
|
|
109
119
|
byOrigin.set(origin, [...(byOrigin.get(origin) ?? []), kind]);
|
|
110
120
|
}
|
|
111
121
|
}
|
|
122
|
+
// Any https site last, the widest: "…; fonts, images, audio and video from any https site" (P059).
|
|
123
|
+
const anywhere = byOrigin.get(ANY_HTTPS_SITE);
|
|
124
|
+
byOrigin.delete(ANY_HTTPS_SITE);
|
|
112
125
|
const groups = new Map<string, string[]>();
|
|
113
126
|
for (const [origin, each] of byOrigin) {
|
|
114
|
-
const
|
|
115
|
-
const key =
|
|
116
|
-
words.length === 1
|
|
117
|
-
? (words[0] ?? "")
|
|
118
|
-
: `${words.slice(0, -1).join(", ")} and ${words.at(-1)}`;
|
|
127
|
+
const key = kindsInWords(each);
|
|
119
128
|
groups.set(key, [...(groups.get(key) ?? []), origin]);
|
|
120
129
|
}
|
|
121
|
-
const parts = [
|
|
130
|
+
const parts = [
|
|
131
|
+
...[...groups].map(([words, origins]) => `${words} from ${origins.join(", ")}`),
|
|
132
|
+
...(anywhere === undefined ? [] : [`${kindsInWords(anywhere)} from ${ANY_HTTPS_SITE}`]),
|
|
133
|
+
];
|
|
122
134
|
return `Network: only ${parts.join("; ")}. Anything else fails.`;
|
|
123
135
|
}
|
|
124
136
|
|
|
@@ -129,6 +141,33 @@ const optsIn = (config: PortholeConfig): boolean =>
|
|
|
129
141
|
const loadsScripts = (config: PortholeConfig): boolean =>
|
|
130
142
|
egressOrigins(config, "script").length > 0;
|
|
131
143
|
|
|
144
|
+
/** The copy of Plotly's map shapes (topojson) to give it, on jsDelivr (P078). */
|
|
145
|
+
export const PLOTLY_TOPOJSON_URL = "https://cdn.jsdelivr.net/npm/plotly.js@3.4.0/dist/topojson/";
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Libraries with CDNs of their own, where the config opens them for scripts (P078): how to load
|
|
149
|
+
* each, pinned, and what it needs that the sandbox closes. Verified in the sandbox, each preset.
|
|
150
|
+
*/
|
|
151
|
+
function ownCdns(config: PortholeConfig): string[] {
|
|
152
|
+
const scripts = egressOrigins(config, "script");
|
|
153
|
+
const said: string[] = [];
|
|
154
|
+
if (scripts.includes("https://cdn.tailwindcss.com")) {
|
|
155
|
+
said.push(
|
|
156
|
+
'- Tailwind: <script src="https://cdn.tailwindcss.com/3.4.17"></script> (the Play CDN builds the CSS as the page runs; its console warning about production is expected).',
|
|
157
|
+
);
|
|
158
|
+
}
|
|
159
|
+
if (scripts.includes("https://code.jquery.com")) {
|
|
160
|
+
said.push('- jQuery: <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>.');
|
|
161
|
+
}
|
|
162
|
+
if (scripts.includes("https://cdn.plot.ly")) {
|
|
163
|
+
const shapes = egressOrigins(config, "connect").includes("https://cdn.jsdelivr.net");
|
|
164
|
+
said.push(
|
|
165
|
+
`- Plotly: <script src="https://cdn.plot.ly/plotly-3.4.0.min.js"></script>. Its maps (scattergeo, choropleth) fetch their shapes from cdn.plot.ly as they draw, which is closed here: ${shapes ? `give them the copy on jsDelivr, Plotly.newPlot(box, data, layout, { topojsonURL: "${PLOTLY_TOPOJSON_URL}" }).` : "they don't draw; use a scatter or a table."}`,
|
|
166
|
+
);
|
|
167
|
+
}
|
|
168
|
+
return said;
|
|
169
|
+
}
|
|
170
|
+
|
|
132
171
|
function widget(c: Context): string {
|
|
133
172
|
const { config, noun } = c;
|
|
134
173
|
const { layout, limits } = config;
|
|
@@ -177,6 +216,7 @@ function widget(c: Context): string {
|
|
|
177
216
|
loadsScripts(config)
|
|
178
217
|
? "\nLibraries: pin an exact version at least two weeks old (chart.js@4.4.1 in its URL), never @latest or a range, so the code can't be swapped under you and draws the same every time."
|
|
179
218
|
: null,
|
|
219
|
+
...ownCdns(config),
|
|
180
220
|
"",
|
|
181
221
|
themeless
|
|
182
222
|
? `Colors: these variables hold the app's palette; use them, or colors of your own. Give the ${noun} its own background.`
|
|
@@ -416,13 +456,10 @@ export function generateToolDescription(config: PortholeConfig): string {
|
|
|
416
456
|
),
|
|
417
457
|
),
|
|
418
458
|
];
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
.map((kind) => KIND_WORDS[kind]);
|
|
459
|
+
// The same words, in the same order, as the manual's Network line.
|
|
460
|
+
const passive = (["font", "img", "media"] as const).filter((kind) => anyHttps(config, kind));
|
|
422
461
|
const fromAnywhere =
|
|
423
|
-
passive.length === 0
|
|
424
|
-
? ""
|
|
425
|
-
: `${passive.length === 1 ? passive[0] : `${passive.slice(0, -1).join(", ")} and ${passive.at(-1)}`} from ${ANY_HTTPS_SITE}`;
|
|
462
|
+
passive.length === 0 ? "" : `${kindsInWords(passive)} from ${ANY_HTTPS_SITE}`;
|
|
426
463
|
const net =
|
|
427
464
|
origins.length === 0 && fromAnywhere === ""
|
|
428
465
|
? "with no network (nothing loads from outside)"
|
package/src/presets/presets.ts
CHANGED
|
@@ -66,8 +66,9 @@ export interface UrlPresetOptions {
|
|
|
66
66
|
|
|
67
67
|
/**
|
|
68
68
|
* Library CDNs a host may open with one line (`egress: LIBRARY_CDNS`): read-only package caches
|
|
69
|
-
* for scripts, styles, fonts, images and data, plus Google Fonts
|
|
70
|
-
*
|
|
69
|
+
* for scripts, styles, fonts, images and data, plus Google Fonts, and three libraries' own CDNs
|
|
70
|
+
* for their scripts only (Tailwind's Play CDN, jQuery, Plotly; P078). Not on by default: every
|
|
71
|
+
* preset starts with egress closed.
|
|
71
72
|
*/
|
|
72
73
|
export const LIBRARY_CDNS: EgressConfig = {
|
|
73
74
|
script: [
|
|
@@ -75,6 +76,10 @@ export const LIBRARY_CDNS: EgressConfig = {
|
|
|
75
76
|
"https://cdn.jsdelivr.net",
|
|
76
77
|
"https://unpkg.com",
|
|
77
78
|
"https://esm.sh",
|
|
79
|
+
// Libraries' own CDNs, scripts only (P078): Tailwind's Play CDN, jQuery, Plotly.
|
|
80
|
+
"https://cdn.tailwindcss.com",
|
|
81
|
+
"https://code.jquery.com",
|
|
82
|
+
"https://cdn.plot.ly",
|
|
78
83
|
],
|
|
79
84
|
style: [
|
|
80
85
|
"https://cdnjs.cloudflare.com",
|