@botiverse/porthole 0.14.7 → 0.14.8

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.
Files changed (49) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/dist/check/files.js +2 -0
  3. package/dist/check/lint.js +82 -3
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/compile/policy.d.ts +17 -6
  6. package/dist/compile/policy.js +22 -7
  7. package/dist/config/schema.d.ts +13 -0
  8. package/dist/config/validate.js +15 -0
  9. package/dist/conformance/harness-source.js +1 -1
  10. package/dist/conformance/kit.d.ts +5 -0
  11. package/dist/conformance/kit.js +21 -0
  12. package/dist/conformance/limits.js +10 -5
  13. package/dist/conformance/probes.js +139 -28
  14. package/dist/conformance/served.js +25 -4
  15. package/dist/guide/limits.js +8 -1
  16. package/dist/host/create-host.js +35 -4
  17. package/dist/index.d.ts +1 -1
  18. package/dist/index.js +1 -1
  19. package/dist/presets/presets.d.ts +6 -0
  20. package/dist/presets/presets.js +6 -0
  21. package/dist/server/files.js +4 -3
  22. package/dist/server/server.js +4 -1
  23. package/dist/shell/plan.d.ts +5 -0
  24. package/dist/shell/plan.js +2 -0
  25. package/dist/shell/runtime.d.ts +30 -1
  26. package/dist/shell/runtime.js +785 -104
  27. package/docs/ADOPTING.md +20 -0
  28. package/docs/DECISIONS.md +294 -0
  29. package/docs/DESIGN.md +7 -4
  30. package/docs/THREAT_MODEL.md +30 -5
  31. package/docs/insertion-entry-points.md +95 -0
  32. package/package.json +1 -1
  33. package/src/check/files.ts +2 -0
  34. package/src/check/lint.ts +97 -8
  35. package/src/compile/policy.ts +23 -6
  36. package/src/config/schema.ts +13 -0
  37. package/src/config/validate.ts +16 -0
  38. package/src/conformance/kit.ts +22 -0
  39. package/src/conformance/limits.ts +10 -5
  40. package/src/conformance/probes.ts +149 -28
  41. package/src/conformance/served.ts +24 -4
  42. package/src/guide/limits.ts +9 -1
  43. package/src/host/create-host.ts +37 -4
  44. package/src/index.ts +1 -0
  45. package/src/presets/presets.ts +15 -0
  46. package/src/server/files.ts +8 -2
  47. package/src/server/server.ts +4 -1
  48. package/src/shell/plan.ts +7 -0
  49. package/src/shell/runtime.ts +788 -104
@@ -494,6 +494,28 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
494
494
  };
495
495
  };
496
496
 
497
+ // A frame's size is taken at most once an animation frame after its run's first, and only
498
+ // when it changed (P127): `resize` has no gate, and each one would reflow the host's page and
499
+ // tell its listeners.
500
+ let sizeFrame: number | null = null;
501
+ let pendingSize: DisplayEvents["resize"] | null = null;
502
+ let shownSize: DisplayEvents["resize"] | null = null;
503
+ const applySize = () => {
504
+ sizeFrame = null;
505
+ const size = pendingSize;
506
+ pendingSize = null;
507
+ if (
508
+ size === null ||
509
+ (shownSize !== null && size.height === shownSize.height && size.width === shownSize.width)
510
+ ) {
511
+ return;
512
+ }
513
+ shownSize = size;
514
+ height = size.height;
515
+ surface?.setHeight(size.height);
516
+ emit("resize", size);
517
+ };
518
+
497
519
  const onBridge = (event: BridgeEvent) => {
498
520
  switch (event.type) {
499
521
  case "resize": {
@@ -501,12 +523,16 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
501
523
  config.limits.maxHeightPx,
502
524
  Math.max(config.limits.minHeightPx, Math.ceil(event.height)),
503
525
  );
504
- height = next;
505
- surface?.setHeight(next);
506
- emit("resize", {
526
+ pendingSize = {
507
527
  height: next,
508
528
  ...(event.width === undefined ? {} : { width: event.width }),
509
- });
529
+ };
530
+ // A run's first size at once: until then its frame has no height of its own.
531
+ if (view === null || shownSize === null) {
532
+ applySize();
533
+ } else if (sizeFrame === null) {
534
+ sizeFrame = view.requestAnimationFrame(applySize);
535
+ }
510
536
  return;
511
537
  }
512
538
  case "navigationBlocked":
@@ -544,6 +570,13 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
544
570
  bridge?.close();
545
571
  bridge = null;
546
572
  handshaken = false;
573
+ // The next run's frame tells its own size, the same as this one's or not.
574
+ if (sizeFrame !== null) {
575
+ view?.cancelAnimationFrame(sizeFrame);
576
+ sizeFrame = null;
577
+ }
578
+ pendingSize = null;
579
+ shownSize = null;
547
580
  abort?.abort();
548
581
  abort = null;
549
582
  outcomeWatch?.stop();
package/src/index.ts CHANGED
@@ -197,6 +197,7 @@ export {
197
197
  assetCspDirectives,
198
198
  FILE_SET_DIRECTIVES,
199
199
  fileSetCspDirectives,
200
+ fileSetDirectives,
200
201
  INERT_FILE_CSP,
201
202
  type CspDirective,
202
203
  type EgressKind,
@@ -58,6 +58,12 @@ export interface PresetOptions {
58
58
  readonly runtime?: RuntimeVersion;
59
59
  /** Domain isolation, artifact pages: the page in an opaque child of Porthole's shell (P111). */
60
60
  readonly nested?: true;
61
+ /**
62
+ * `own` (P128): an `<iframe>` of one of the page's own files (a relative `src`) or a `srcdoc`
63
+ * one loads and runs, in a realm of its own that the shell's hardening doesn't reach
64
+ * (`PortholeConfig.nestedFrames`). `none` (default): every nested frame is removed.
65
+ */
66
+ readonly nestedFrames?: "none" | "own";
61
67
  }
62
68
 
63
69
  /** What a live widget may say about a capability (P103): anything but origins of its own. */
@@ -244,6 +250,7 @@ function build(
244
250
  ...(options.errors === undefined ? {} : { errors: options.errors }),
245
251
  ...(options.runtime === undefined ? {} : { runtime: options.runtime }),
246
252
  ...(options.nested === undefined ? {} : { nested: options.nested }),
253
+ ...(options.nestedFrames === undefined ? {} : { nestedFrames: options.nestedFrames }),
247
254
  });
248
255
  }
249
256
 
@@ -271,6 +278,14 @@ export const presets = {
271
278
  "a live widget has no network of its own: its egress stays closed (P079)",
272
279
  );
273
280
  }
281
+ // A child frame is a realm the shell's WebRTC removal never reached (P128): a network of its
282
+ // own, which a live widget never has.
283
+ if (options.nestedFrames === "own") {
284
+ throw new ConfigError(
285
+ "options.nestedFrames",
286
+ "a live widget has no network of its own: its frames stay removed (P079, P128)",
287
+ );
288
+ }
274
289
  // A capability's own origins join the CSP as egress does (P103): none for a live widget.
275
290
  for (const [name, value] of Object.entries((options as PresetOptions).capabilities ?? {})) {
276
291
  for (const field of ["connect", "resource"] as const) {
@@ -2,6 +2,7 @@ import type { CompiledConfig } from "../compile/compile.ts";
2
2
  import {
3
3
  assetCspDirectives,
4
4
  fileSetCspDirectives,
5
+ fileSetDirectives,
5
6
  INERT_FILE_CSP,
6
7
  servedDocumentCsp,
7
8
  servedPermissionsPolicy,
@@ -268,10 +269,15 @@ export async function serveFile(serving: FileServing): Promise<Response> {
268
269
  serving.compiled.config.capabilities.assets !== undefined
269
270
  ? "same-origin"
270
271
  : "no-referrer";
271
- // Its version's files (P082), and its artifact's assets where the config serves them (P089).
272
+ // Its version's files (P082), frames of them where the config opts in (P128), and its
273
+ // artifact's assets where the config serves them (P089).
272
274
  const directives = assetCspDirectives(
273
275
  serving.compiled.config,
274
- fileSetCspDirectives(serving.compiled.cspDirectives, serving.source),
276
+ fileSetCspDirectives(
277
+ serving.compiled.cspDirectives,
278
+ serving.source,
279
+ fileSetDirectives(serving.compiled.config),
280
+ ),
275
281
  serving.origin,
276
282
  );
277
283
  // A page and a script (a worker's policy is its script's) get the page's CSP, a page with its
@@ -1303,6 +1303,9 @@ export function createServer(options: ServerOptions): PortholeServer {
1303
1303
  const ancestors = nested ? nestedAncestors(access.origin, frameAncestors) : frameAncestors;
1304
1304
  if ("files" in served) {
1305
1305
  if (at !== undefined) {
1306
+ // A page's own frames (P128): its files below the base are framed by its own pages too,
1307
+ // on this origin (`frame-ancestors` names every ancestor). Never another origin's.
1308
+ const own = served.compiled.config.nestedFrames === "own";
1306
1309
  return serveFile({
1307
1310
  request,
1308
1311
  set: served.files,
@@ -1314,7 +1317,7 @@ export function createServer(options: ServerOptions): PortholeServer {
1314
1317
  source: at.source,
1315
1318
  compiled: served.compiled,
1316
1319
  hostOrigins: options.hostOrigins,
1317
- frameAncestors: ancestors,
1320
+ frameAncestors: own ? `${access.origin} ${ancestors}` : ancestors,
1318
1321
  ...versionOf(access.instance),
1319
1322
  });
1320
1323
  }
package/src/shell/plan.ts CHANGED
@@ -56,6 +56,11 @@ export interface ShellPlan {
56
56
  /** The most text `copyText` carries. */
57
57
  readonly maxCopyChars: number;
58
58
  readonly protocolVersion: string;
59
+ /**
60
+ * `own` where the config lets content frame its own files and `srcdoc` (P128): the shell keeps
61
+ * those iframes and removes every other frame-like element. Absent: it removes them all.
62
+ */
63
+ readonly nestedFrames?: "own";
59
64
  }
60
65
 
61
66
  export function shellPlan(config: PortholeConfig): ShellPlan | null {
@@ -103,5 +108,7 @@ export function shellPlan(config: PortholeConfig): ShellPlan | null {
103
108
  maxPromptChars: config.limits.maxPromptChars,
104
109
  maxCopyChars: MAX_COPY_CHARS,
105
110
  protocolVersion: MCP_APPS_PROTOCOL_VERSION,
111
+ // Only where opted into (P128): every other plan is the same as before it.
112
+ ...(config.nestedFrames === "own" ? { nestedFrames: "own" as const } : {}),
106
113
  };
107
114
  }