@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.
@@ -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. */
@@ -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 words = each.map((kind) => KIND_WORDS[kind]);
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 = [...groups].map(([words, origins]) => `${words} from ${origins.join(", ")}`);
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
- const passive = ["img", "media", "font"]
250
- .filter((kind) => anyHttps(config, kind))
251
- .map((kind) => KIND_WORDS[kind]);
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. Not on by default: every preset
52
- * starts with egress closed.
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: {
@@ -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. Not on by default: every preset
6
- * starts with egress closed.
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), and
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. The leak suite
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.4",
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: {
@@ -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 words = each.map((kind) => KIND_WORDS[kind]);
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 = [...groups].map(([words, origins]) => `${words} from ${origins.join(", ")}`);
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
- const passive = (["img", "media", "font"] as const)
420
- .filter((kind) => anyHttps(config, kind))
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)"
@@ -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. Not on by default: every preset
70
- * starts with egress closed.
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",