@botiverse/porthole 0.15.3 → 0.16.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.
Files changed (107) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/dist/bridge/bridge.d.ts +1 -8
  3. package/dist/bridge/bridge.js +0 -7
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/check/page.js +1 -1
  6. package/dist/compile/policy.d.ts +0 -7
  7. package/dist/compile/policy.js +1 -10
  8. package/dist/config/capabilities.d.ts +8 -14
  9. package/dist/config/capabilities.js +4 -5
  10. package/dist/config/schema.d.ts +2 -13
  11. package/dist/config/validate.js +0 -24
  12. package/dist/conformance/behavior.js +26 -37
  13. package/dist/conformance/clipboard.js +47 -1
  14. package/dist/conformance/harness-source.js +1 -1
  15. package/dist/displays/displays.js +1 -3
  16. package/dist/guide/limits.js +1 -1
  17. package/dist/guide/runtime.js +1 -1
  18. package/dist/host/create-host.d.ts +1 -1
  19. package/dist/host/create-host.js +6 -51
  20. package/dist/host/door.d.ts +1 -1
  21. package/dist/host/locate.d.ts +1 -1
  22. package/dist/host/locate.js +2 -2
  23. package/dist/host/outcome.d.ts +5 -12
  24. package/dist/host/outcome.js +8 -16
  25. package/dist/host/types.d.ts +6 -22
  26. package/dist/index.d.ts +2 -4
  27. package/dist/index.js +2 -4
  28. package/dist/isolation/served.d.ts +4 -14
  29. package/dist/isolation/served.js +7 -28
  30. package/dist/isolation/types.d.ts +2 -25
  31. package/dist/isolation/types.js +0 -23
  32. package/dist/platform/focus-field.d.ts +11 -0
  33. package/dist/platform/focus-field.js +18 -0
  34. package/dist/platform/types.d.ts +6 -22
  35. package/dist/platform/web.js +8 -106
  36. package/dist/presets/presets.d.ts +0 -2
  37. package/dist/presets/presets.js +0 -1
  38. package/dist/react/frame.d.ts +0 -8
  39. package/dist/react/frame.js +0 -4
  40. package/dist/runtime/contract.d.ts +2 -2
  41. package/dist/runtime/contract.js +2 -2
  42. package/dist/runtime/types.generated.js +6 -6
  43. package/dist/server/files.js +7 -23
  44. package/dist/server/host.d.ts +1 -1
  45. package/dist/server/index.d.ts +1 -1
  46. package/dist/server/index.js +4 -6
  47. package/dist/server/naming.js +1 -1
  48. package/dist/server/server.js +28 -166
  49. package/dist/server/types.d.ts +7 -7
  50. package/dist/shell/plan.d.ts +0 -5
  51. package/dist/shell/plan.js +2 -4
  52. package/dist/shell/runtime.js +1 -268
  53. package/docs/ADOPTING.md +42 -138
  54. package/docs/ARCHITECTURE.md +0 -33
  55. package/docs/DECISIONS.md +115 -10
  56. package/docs/DESIGN.md +27 -64
  57. package/docs/THREAT_MODEL.md +128 -255
  58. package/package.json +1 -1
  59. package/src/bridge/bridge.ts +1 -17
  60. package/src/check/page.ts +1 -1
  61. package/src/compile/policy.ts +1 -11
  62. package/src/config/capabilities.ts +8 -14
  63. package/src/config/schema.ts +2 -13
  64. package/src/config/validate.ts +0 -28
  65. package/src/conformance/behavior.ts +50 -52
  66. package/src/conformance/clipboard.ts +56 -1
  67. package/src/displays/displays.ts +1 -3
  68. package/src/guide/limits.ts +1 -1
  69. package/src/guide/runtime.ts +1 -1
  70. package/src/host/create-host.ts +6 -52
  71. package/src/host/door.ts +1 -1
  72. package/src/host/locate.ts +2 -2
  73. package/src/host/outcome.ts +8 -21
  74. package/src/host/types.ts +6 -20
  75. package/src/index.ts +2 -4
  76. package/src/isolation/served.ts +6 -34
  77. package/src/isolation/types.ts +2 -31
  78. package/src/platform/focus-field.ts +18 -0
  79. package/src/platform/types.ts +6 -21
  80. package/src/platform/web.ts +8 -129
  81. package/src/presets/presets.ts +0 -3
  82. package/src/react/frame.tsx +0 -10
  83. package/src/runtime/contract.ts +4 -4
  84. package/src/runtime/types.generated.ts +6 -6
  85. package/src/server/files.ts +4 -19
  86. package/src/server/host.ts +1 -1
  87. package/src/server/index.ts +4 -16
  88. package/src/server/naming.ts +1 -1
  89. package/src/server/server.ts +29 -189
  90. package/src/server/types.ts +7 -7
  91. package/src/shell/plan.ts +2 -9
  92. package/src/shell/runtime.ts +1 -268
  93. package/types/runtime/v1/artifact.d.ts +2 -3
  94. package/types/runtime/v1/assets.d.ts +1 -1
  95. package/types/runtime/v1/chat.d.ts +2 -2
  96. package/types/runtime/v1/comments.d.ts +1 -1
  97. package/types/runtime/v1/downloads.d.ts +2 -2
  98. package/types/runtime/v1/links.d.ts +2 -2
  99. package/dist/platform/focus-guard.d.ts +0 -288
  100. package/dist/platform/focus-guard.js +0 -838
  101. package/dist/server/nested.d.ts +0 -66
  102. package/dist/server/nested.js +0 -121
  103. package/dist/shell/frame.d.ts +0 -28
  104. package/dist/shell/frame.js +0 -407
  105. package/src/platform/focus-guard.ts +0 -1114
  106. package/src/server/nested.ts +0 -157
  107. package/src/shell/frame.ts +0 -444
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.15.3",
3
+ "version": "0.16.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
  "homepage": "https://github.com/botiverse/porthole#readme",
6
6
  "bugs": {
@@ -73,8 +73,7 @@ import type {
73
73
  * every capability its host function's own rate (P091, P095) → arguments well formed and within
74
74
  * their limits → who may (P087: the level of each method the call runs for the viewer, a page's
75
75
  * named data with or without a viewer, db's rules) → not muted, if confirm-gated → the own rate
76
- * of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so (and
77
- * for `comments`, the host page's focus in the calling frame: P109) → the
76
+ * of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so → the
78
77
  * viewer's consent, if gated so → a person's confirmation, if gated so (at most 10 waiting) →
79
78
  * shown to the person, if gated so (P100) → the handler (or, for a read, a result the host already
80
79
  * gave for it, or for a stale-allowed one the host's cache).
@@ -111,12 +110,6 @@ export interface BridgeOptions {
111
110
  readonly cached?: DataCache;
112
111
  /** Whether the embedding page has user activation now; undefined where it can't tell. */
113
112
  readonly userActivation?: () => boolean | undefined;
114
- /**
115
- * Whether the embedding page's focus is in this display's frame now (P109); undefined where it
116
- * can't tell. A capability whose gesture must be in its frame (`inFrame`: `comments`) is refused
117
- * without it.
118
- */
119
- readonly focused?: () => boolean | undefined;
120
113
  readonly onEvent: (event: BridgeEvent) => void;
121
114
  /** The clock, in milliseconds (tests pass their own). */
122
115
  readonly now?: () => number;
@@ -136,10 +129,6 @@ export interface BridgeOptions {
136
129
  const isRecord = (value: unknown): value is Record<string, unknown> =>
137
130
  value !== null && typeof value === "object" && !Array.isArray(value);
138
131
 
139
- /** Whether `capability`'s gesture must be in its own frame (P109: the host page's focus there). */
140
- const inFrame = (capability: CapabilityName): boolean =>
141
- capabilitySpec(capability).inFrame === true;
142
-
143
132
  const MAX_URL = 4_096;
144
133
 
145
134
  /**
@@ -669,11 +658,6 @@ export function createBridge(options: BridgeOptions): DisplayBridge {
669
658
  if (activated === false) {
670
659
  return refuse<Result>(capability, "no-user-activation");
671
660
  }
672
- // A gesture in this frame, not anywhere on the host's page (P109): the person typing in
673
- // the host's composer gives its page activation, which a frame's call would borrow.
674
- if (inFrame(capability) && options.focused?.() === false) {
675
- return refuse<Result>(capability, "no-user-activation");
676
- }
677
661
  }
678
662
  if (gates.includes("consent")) {
679
663
  const consent = options.consent;
package/src/check/page.ts CHANGED
@@ -63,7 +63,7 @@ const NOBODY: PlatformHost = {
63
63
  return { ...surface, userActivation: () => false };
64
64
  },
65
65
  // A served display's door (P125), as the web platform makes it: a platform without doors frames
66
- // no served display that isn't nested.
66
+ // no served display.
67
67
  createDoor: (container, spec) => webPlatform.createDoor!(container, spec),
68
68
  };
69
69
 
@@ -234,8 +234,6 @@ export function sandboxTokens(config: PortholeConfig): string[] {
234
234
  case "opaque":
235
235
  return ["allow-scripts"];
236
236
  case "domain":
237
- // Nested (P111), this frame holds Porthole's shell, on a label of its own where no content
238
- // runs with this origin (P114), and the page is the shell's child (`PAGE_SANDBOX_TOKENS`).
239
237
  return ["allow-scripts", "allow-same-origin"];
240
238
  case "external":
241
239
  // The host may add a documented few (popups, modals, downloads), never top navigation.
@@ -257,17 +255,9 @@ export function servedSandboxDirective(config: PortholeConfig): CspDirective | n
257
255
  if (config.isolation !== "domain") {
258
256
  return null;
259
257
  }
260
- return ["sandbox", ...(config.nested === true ? PAGE_SANDBOX_TOKENS : sandboxTokens(config))];
258
+ return ["sandbox", ...sandboxTokens(config)];
261
259
  }
262
260
 
263
- /**
264
- * A nested page's sandbox (P111): its frame's attribute, set by Porthole's shell, and its own CSP
265
- * header's, so it is an opaque origin in the shell's child frame and on a tab of its own. Scripts
266
- * only: never `allow-same-origin`, which would give the page its served origin, the shell's, and
267
- * so the shell's realm (a test holds every sandbox Porthole writes to this).
268
- */
269
- export const PAGE_SANDBOX_TOKENS: readonly string[] = ["allow-scripts"];
270
-
271
261
  /**
272
262
  * A served display's door's sandbox (P125): its frame's attribute, which the host writes, and its
273
263
  * answer's CSP header's. Scripts only: an opaque origin, a new one each time, that no content of
@@ -53,8 +53,10 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
53
53
  * propagates to, and which lasts 5 s after any gesture anywhere on the host's page: a click on
54
54
  * the host's own UI, or the person typing in its own composer, counts. So it stops calls made on
55
55
  * load, or on a timer while nobody does anything; it is not proof that the gesture was in this
56
- * frame, nor of intent. Where a capability needs that (`comments`, P109: its draft goes into
57
- * the person's composer), the host also asks that its page's focus be in the calling frame.
56
+ * frame, nor of intent. Since 0.16.0 (P149) only `copyText` has it by default: nothing else
57
+ * stands between a page and the person's clipboard. Every other call either shows the person
58
+ * its whole effect first (`confirm`) or opens something of the host's that does nothing by
59
+ * itself (`comments`), and a guess at who pressed what refused real presses.
58
60
  * - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
59
61
  * goes only if they accept. No `confirm` function means the call is refused (fail closed).
60
62
  * - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
@@ -89,13 +91,6 @@ export interface CapabilitySpec {
89
91
  * Absent for what the shell does by itself (sizes, errors, annotations, find).
90
92
  */
91
93
  readonly request?: { readonly method: string; readonly sdk?: string };
92
- /**
93
- * Its `user-activation` gate also needs the person in the calling frame (P109): the host page's
94
- * focus in that frame, which a press on it or a Tab into it gives and the focus guard keeps from
95
- * a frame's own `focus()`. Activation alone lasts 5 s after any gesture on the host's page,
96
- * typing in its own composer included.
97
- */
98
- readonly inFrame?: true;
99
94
  }
100
95
 
101
96
  const rate = (perMinute: number): Gate => ({ rateLimit: { perMinute } });
@@ -111,19 +106,19 @@ export const MAX_CONTEXT_CHARS = 20_000;
111
106
 
112
107
  export const CAPABILITIES = {
113
108
  sendPrompt: {
114
- defaultGates: ["user-activation", "confirm"],
109
+ defaultGates: ["confirm", rate(30)],
115
110
  served: "handler",
116
111
  global: "sendPrompt",
117
112
  request: { method: "ui/message", sdk: "app.sendMessage" },
118
113
  },
119
114
  openLink: {
120
- defaultGates: ["user-activation", "confirm"],
115
+ defaultGates: ["confirm", rate(30)],
121
116
  served: "handler",
122
117
  global: "openLink",
123
118
  request: { method: "ui/open-link", sdk: "app.openLink" },
124
119
  },
125
120
  downloadFile: {
126
- defaultGates: ["user-activation", "confirm"],
121
+ defaultGates: ["confirm", rate(30)],
127
122
  served: "handler",
128
123
  request: { method: "ui/download-file", sdk: "app.downloadFile" },
129
124
  },
@@ -188,10 +183,9 @@ export const CAPABILITIES = {
188
183
  user: { defaultGates: [rate(60)], served: "viewer", request: { method: "porthole/call" } },
189
184
  /** Opens the host's comment composer at the page's anchor (P090): write-only. */
190
185
  comments: {
191
- defaultGates: ["user-activation", rate(30)],
186
+ defaultGates: [rate(30)],
192
187
  served: "handler",
193
188
  request: { method: "porthole/call" },
194
- inFrame: true,
195
189
  },
196
190
  /** This artifact's current version, and a new version of it, base-checked (P088). */
197
191
  artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
@@ -258,17 +258,6 @@ export interface PortholeConfig {
258
258
  * `db`). Absent: 0.6's frames, globals and manual, exactly.
259
259
  */
260
260
  readonly runtime?: RuntimeVersion;
261
- /**
262
- * Domain isolation, artifact pages (P111): the address the host frames serves Porthole's shell
263
- * alone, a document of Porthole's own with no content in it, and the page runs in a child frame
264
- * of the shell's, sandboxed without `allow-same-origin` (an opaque origin), served from the same
265
- * origin at its files' sealed address. The shell is then a realm the page can't reach, above the
266
- * page's frame: it relays the page's messages, and tells the host when its own transient
267
- * activation turns on (a press in the page activates its ancestors only), which is how the host
268
- * knows the person, not the page, moved the keyboard into the frame or opened a comment. The
269
- * page has no storage of its own (an in-memory stand-in) and fetches nothing with a cookie.
270
- */
271
- readonly nested?: true;
272
261
  /**
273
262
  * Which nested frames content may make (P128). `none` (default, and absent): the shell removes
274
263
  * every frame-like element content adds, and the CSP's `frame-src` is `'none'`. `own`: an
@@ -278,8 +267,8 @@ export interface PortholeConfig {
278
267
  * A weakening, opted into: a child frame is a realm of its own, where the shell's WebRTC
279
268
  * removal, clipboard guards and navigation cancel never ran (a page of the set framed there has
280
269
  * its own shell; a `srcdoc` frame, or the `about:blank` a new frame starts as, has none), so
281
- * content reaches WebRTC and the clipboard's events there. Not for url mode, a live widget
282
- * (no network of its own, P079) or a nested page (P111).
270
+ * content reaches WebRTC and the clipboard's events there. Not for url mode or a live widget
271
+ * (no network of its own, P079).
283
272
  */
284
273
  readonly nestedFrames?: "none" | "own";
285
274
  }
@@ -324,7 +324,6 @@ export function validateConfig(
324
324
  "storage",
325
325
  "errors",
326
326
  "runtime",
327
- "nested",
328
327
  "nestedFrames",
329
328
  ],
330
329
  "config",
@@ -689,28 +688,6 @@ export function validateConfig(
689
688
  }
690
689
  }
691
690
 
692
- if (config.nested !== undefined) {
693
- if (config.nested !== true) {
694
- fail("config.nested", "must be true, or left out");
695
- }
696
- if (config.isolation !== "domain" || config.mode !== "artifact") {
697
- fail("config.nested", "nests artifact pages served on their own origin (domain isolation)");
698
- }
699
- // The page's origin is opaque (P111): nothing of the content origin's own is its.
700
- if (config.storage !== undefined) {
701
- fail("config.nested", "a nested page keeps no storage: drop config.storage");
702
- }
703
- if (capabilities.assets !== undefined) {
704
- fail(
705
- "config.nested",
706
- "a nested page can't load its asset library (/_blob/) yet: drop assets",
707
- );
708
- }
709
- if (isObject(config.egress) && config.egress.libraries === true) {
710
- fail("config.nested", "a nested page can't load Porthole's libraries from its origin yet");
711
- }
712
- }
713
-
714
691
  // A page's own nested frames (P128): opted into, never a default.
715
692
  if (config.nestedFrames !== undefined) {
716
693
  if (config.nestedFrames !== "none" && config.nestedFrames !== "own") {
@@ -719,11 +696,6 @@ export function validateConfig(
719
696
  if (config.nestedFrames === "own" && config.mode === "url") {
720
697
  fail("config.nestedFrames", "url mode has no shell: its app's frames are its own");
721
698
  }
722
- // A nested page's frames have an opaque ancestor, which no frame-ancestors source matches:
723
- // none of its own files would load in one. Not measured yet.
724
- if (config.nestedFrames === "own" && config.nested === true) {
725
- fail("config.nestedFrames", 'a nested page (P111) has no "own" frames yet: leave it out');
726
- }
727
699
  }
728
700
 
729
701
  if (config.errors !== undefined) {
@@ -49,28 +49,6 @@ async function click(display: LaunchedDisplay, selector: string): Promise<void>
49
49
  await (await display.frame()).locator(selector).click();
50
50
  }
51
51
 
52
- /**
53
- * Lets any user activation the test harness gave the host page lapse: Playwright's own
54
- * evaluations count as gestures in some engines, and Chromium keeps one for 5 s. Between this and
55
- * the next raw input, the test must not evaluate anything in the page.
56
- */
57
- const ACTIVATION_LAPSE_MS = 6_000;
58
-
59
- /** A click by raw mouse input at `selector`'s center, after any harness activation has lapsed. */
60
- async function clickAfterLapse(
61
- context: ProbeContext,
62
- display: LaunchedDisplay,
63
- selector: string,
64
- ): Promise<void> {
65
- const frame = await display.frame();
66
- const box = await frame.locator(selector).boundingBox();
67
- if (box === null) {
68
- throw new Error(`${selector} is not on screen`);
69
- }
70
- await context.page.waitForTimeout(ACTIVATION_LAPSE_MS);
71
- await context.page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
72
- }
73
-
74
52
  /**
75
53
  * The attribute `name` of the frame's body, once set. Where it is a gate's answer to the content,
76
54
  * `verdict` is the probe's: an answer that never comes (a call left waiting on a gate that should
@@ -130,8 +108,13 @@ const PROMPT_CONTENT = `<button id="ask">Explain March</button>
130
108
  (error) => (document.body.dataset.result = "refused: " + error.message),
131
109
  );
132
110
  });
111
+ </script>`;
112
+
113
+ /** A prompt asked as the page loads, with no click anywhere. */
114
+ const PROMPT_ON_LOAD = `<p>Asks on load</p>
115
+ <script>
133
116
  sendPrompt("asked on load").then(
134
- () => (document.body.dataset.onload = "sent"),
117
+ (sent) => (document.body.dataset.onload = String(sent)),
135
118
  (error) => (document.body.dataset.onload = "refused: " + error.message),
136
119
  );
137
120
  </script>`;
@@ -466,29 +449,36 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
466
449
 
467
450
  // ── 12: the host-function gates ────────────────────────────────────────────────────────────
468
451
  {
469
- id: "12.prompt-gesture-confirm",
452
+ id: "12.prompt-confirm",
470
453
  item: 12,
471
- title: "sendPrompt needs a click and the person's yes; a no sends nothing",
454
+ title: "sendPrompt needs the person's yes, from a click or not; a no sends nothing",
472
455
  async run(context) {
473
- const display = await context.launch({ config: prompts(), content: PROMPT_CONTENT });
474
- expect(
475
- await bodyData(display, "onload", "probe: a call made on load is refused by the shell"),
476
- "probe: a call made on load is refused by the shell",
477
- ).toContain("needs a click");
456
+ // No proof of a click is asked (0.16.0, P149): a prompt made as the page loads is the
457
+ // person's to answer like any other, and their no sends nothing.
458
+ const loading = await context.launch({ config: prompts(), content: PROMPT_ON_LOAD });
459
+ const unasked = await answered(
460
+ loading,
461
+ false,
462
+ "probe: the person was asked about a prompt made on load",
463
+ );
464
+ expect(unasked, "probe: the person was asked about the whole prompt").toMatchObject({
465
+ capability: "sendPrompt",
466
+ args: { text: "asked on load" },
467
+ });
478
468
  expect(
479
- await display.calls(),
480
- "probe: a call made on load reached the host's handler",
481
- ).toEqual([]);
482
-
483
- // The host's own check needs the frame's click to reach the host page (activation
484
- // propagates to ancestors): measured with raw input, after the harness's activation lapsed.
485
- await clickAfterLapse(context, display, "#ask");
486
- await context.page.waitForTimeout(500);
487
- const refused = await refusals(display);
488
- context.measured(
489
- `${context.engine}: a click in the frame ${refused.includes("sendPrompt:no-user-activation") ? "does not reach" : "reaches"} the host page's user activation`,
469
+ await bodyData(
470
+ loading,
471
+ "onload",
472
+ "probe: the content is told a declined prompt wasn't sent",
473
+ ),
474
+ "probe: the content is told a declined prompt wasn't sent",
475
+ ).toBe("false");
476
+ expect(await loading.calls(), "probe: a declined prompt reached the host's handler").toEqual(
477
+ [],
490
478
  );
491
- expect(refused, "the frame's click didn't count as a gesture on the host page").toEqual([]);
479
+
480
+ const display = await context.launch({ config: prompts(), content: PROMPT_CONTENT });
481
+ await click(display, "#ask");
492
482
  const declined = await answered(
493
483
  display,
494
484
  false,
@@ -522,7 +512,8 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
522
512
  {
523
513
  id: "12.raw-message",
524
514
  item: 12,
525
- title: "a prompt sent around the shell (raw ui/message, no click) is refused by the host",
515
+ title:
516
+ "a prompt sent around the shell (raw ui/message, no click) is the person's to answer too; a no sends nothing",
526
517
  async run(context) {
527
518
  const display = await context.launch({
528
519
  config: prompts(),
@@ -530,22 +521,29 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
530
521
  addEventListener("message", (event) => {
531
522
  if (event.data && event.data.id === "raw-1") document.body.dataset.answer = JSON.stringify(event.data.result ?? event.data.error);
532
523
  });
533
- // Late enough that no harness gesture is still active on the host page.
534
- setTimeout(() => parent.postMessage({ jsonrpc: "2.0", id: "raw-1", method: "ui/message", params: { role: "user", content: [{ type: "text", text: "sent around the shell" }] } }, "*"), ${ACTIVATION_LAPSE_MS});
524
+ parent.postMessage({ jsonrpc: "2.0", id: "raw-1", method: "ui/message", params: { role: "user", content: [{ type: "text", text: "sent around the shell" }] } }, "*");
535
525
  </script>`,
536
526
  });
537
- // Nothing is evaluated in the page until the message has been answered.
538
- await context.page.waitForTimeout(ACTIVATION_LAPSE_MS + 1_500);
527
+ const asked = await answered(
528
+ display,
529
+ false,
530
+ "probe: the person was asked about a raw ui/message",
531
+ );
532
+ expect(asked, "probe: the person was asked about the whole prompt").toMatchObject({
533
+ capability: "sendPrompt",
534
+ args: { text: "sent around the shell" },
535
+ });
539
536
  expect(
540
- await bodyData(display, "answer", "probe: a raw ui/message without a click is refused"),
541
- "probe: a raw ui/message without a click is refused",
537
+ await bodyData(
538
+ display,
539
+ "answer",
540
+ "probe: a declined raw ui/message is answered as not sent",
541
+ ),
542
+ "probe: a declined raw ui/message is answered as not sent",
542
543
  ).toBe(JSON.stringify({ isError: true }));
543
544
  expect(await display.calls(), "probe: a raw ui/message reached the host's handler").toEqual(
544
545
  [],
545
546
  );
546
- expect(await refusals(display), "probe: the host refused it for no user activation").toEqual([
547
- "sendPrompt:no-user-activation",
548
- ]);
549
547
  },
550
548
  },
551
549
  {
@@ -52,6 +52,20 @@ async function pasted(page: Page): Promise<string> {
52
52
  );
53
53
  }
54
54
 
55
+ /**
56
+ * Lets any user activation the test harness gave the host page lapse: Playwright's own
57
+ * evaluations count as gestures in some engines, and Chromium keeps one for 5 s. Between this and
58
+ * the next raw input, the test must not evaluate anything in the page.
59
+ */
60
+ const ACTIVATION_LAPSE_MS = 6_000;
61
+
62
+ /** The refusals the display reported, by capability. */
63
+ async function refusals(display: LaunchedDisplay): Promise<string[]> {
64
+ return (await display.events()).flatMap((event) =>
65
+ event.type === "refused" ? [`${event.detail.capability}:${event.detail.refusal}`] : [],
66
+ );
67
+ }
68
+
55
69
  /** Clicks `selector` in the display (a real click: the user activation a person gives). */
56
70
  async function click(display: LaunchedDisplay, selector: string): Promise<void> {
57
71
  await (await display.frame()).locator(selector).click();
@@ -206,7 +220,21 @@ export const CLIPBOARD_PROBES: readonly Probe[] = [
206
220
  await bodyData(display, "onload", "probe: copyText without a click is refused"),
207
221
  "probe: copyText without a click is refused",
208
222
  ).toMatch(/^refused/u);
209
- await click(display, "#copy");
223
+ // The host's own check needs the frame's click to reach the host page (activation
224
+ // propagates to ancestors): measured with raw input, after the harness's activation lapsed.
225
+ const frame = await display.frame();
226
+ const box = await frame.locator("#copy").boundingBox();
227
+ if (box === null) {
228
+ throw new Error("#copy is not on screen");
229
+ }
230
+ await context.page.waitForTimeout(ACTIVATION_LAPSE_MS);
231
+ await context.page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
232
+ await context.page.waitForTimeout(500);
233
+ const refused = await refusals(display);
234
+ context.measured(
235
+ `${context.engine}: a click in the frame ${refused.includes("copyText:no-user-activation") ? "does not reach" : "reaches"} the host page's user activation`,
236
+ );
237
+ expect(refused, "the frame's click didn't count as a gesture on the host page").toEqual([]);
210
238
  expect(await bodyData(display, "result")).toBe("true");
211
239
  expect(
212
240
  await display.calls(),
@@ -214,4 +242,31 @@ export const CLIPBOARD_PROBES: readonly Probe[] = [
214
242
  ).toEqual([{ capability: "copyText", args: { text: "npm test -- --run" } }]);
215
243
  },
216
244
  },
245
+ {
246
+ id: "12.raw-copy",
247
+ item: 12,
248
+ title: "a copy sent around the shell (raw porthole/copy-text, no click) is refused by the host",
249
+ async run(context) {
250
+ const display = await context.launch({
251
+ config: inline({ capabilities: { copyText: {} } }),
252
+ content: `<script>
253
+ addEventListener("message", (event) => {
254
+ if (event.data && event.data.id === "raw-1") document.body.dataset.answer = JSON.stringify(event.data.result ?? event.data.error);
255
+ });
256
+ // Late enough that no harness gesture is still active on the host page.
257
+ setTimeout(() => parent.postMessage({ jsonrpc: "2.0", id: "raw-1", method: "porthole/copy-text", params: { text: "copied around the shell" } }, "*"), ${ACTIVATION_LAPSE_MS});
258
+ </script>`,
259
+ });
260
+ // Nothing is evaluated in the page until the message has been answered.
261
+ await context.page.waitForTimeout(ACTIVATION_LAPSE_MS + 1_500);
262
+ expect(
263
+ await bodyData(display, "answer", "probe: a raw copy without a click is refused"),
264
+ "probe: a raw copy without a click is refused",
265
+ ).toBe(JSON.stringify({ isError: true }));
266
+ expect(await display.calls(), "probe: a raw copy reached the host's handler").toEqual([]);
267
+ expect(await refusals(display), "probe: the host refused it for no user activation").toEqual([
268
+ "copyText:no-user-activation",
269
+ ]);
270
+ },
271
+ },
217
272
  ];
@@ -93,11 +93,9 @@ export function defineDisplays<N extends string>(
93
93
  return presets.url({ ...kind.options, contentOrigins: [source] });
94
94
  }
95
95
  const options = kind.options ?? {};
96
- // Nesting (P111) is a served page's: an opaque frame has nothing to nest.
97
- const { nested: _nested, ...opaque } = options;
98
96
  return presets[kind.preset](
99
97
  source === null
100
- ? opaque
98
+ ? options
101
99
  : { ...options, ...kind.served, isolation: "domain", contentOrigins: [source] },
102
100
  );
103
101
  };
@@ -204,7 +204,7 @@ export function manualLimits(config: PortholeConfig, network: string): ManualLim
204
204
  );
205
205
  add(
206
206
  "storage",
207
- config.isolation === "opaque" || config.nested === true
207
+ config.isolation === "opaque"
208
208
  ? `State isn't saved: localStorage works but lasts only while the ${it} is on screen, and a reload or another device starts fresh. Keep what matters in the ${it}'s code.`
209
209
  : config.storage?.scope !== undefined
210
210
  ? `localStorage is kept for ${config.storage.scope}, in this browser; another browser or device starts fresh. Reads and writes can throw (private windows, strict settings): wrap them in try/catch and keep only what can be lost.`
@@ -61,7 +61,7 @@ const CALLS: Readonly<Record<RuntimeCapabilityName, Readonly<Record<string, stri
61
61
  const WHAT: Readonly<Partial<Record<CapabilityName, (config: PortholeConfig) => string>>> = {
62
62
  user: () => "who is viewing: { id, name, level }, as the app says",
63
63
  comments: () =>
64
- "opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width characters, joiners only between two letters (Persian's or Hindi's are fine; an emoji joined with U+200D is refused; ❤️ is fine), no bidi or tag characters, line or paragraph separators, or runs of blanks; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. Call it from a click in the page. True if it opened. Write-only: a page never reads comments, and never posts one",
64
+ "opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width characters, joiners only between two letters (Persian's or Hindi's are fine; an emoji joined with U+200D is refused; ❤️ is fine), no bidi or tag characters, line or paragraph separators, or runs of blanks; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. True if it opened. Write-only: a page never reads comments, and never posts one",
65
65
  copyText: () =>
66
66
  `copies text to the person's clipboard (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters), and the app shows them what was copied; nothing else in the page can write the clipboard. True if copied`,
67
67
  openLink: () =>
@@ -32,7 +32,6 @@ import { watchDoor, type DoorWatch } from "./door.ts";
32
32
  import { outcomeOfRefusal } from "./locator.ts";
33
33
  import { STORAGE_USED_METHOD, type FrameSource } from "../isolation/types.ts";
34
34
  import { webPlatform } from "../platform/web.ts";
35
- import { TAKES } from "../platform/focus-guard.ts";
36
35
  import type { DoorSurface, Surface } from "../platform/types.ts";
37
36
  import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
38
37
  import {
@@ -75,7 +74,7 @@ export const REUSED_LOCATION =
75
74
 
76
75
  /** What the host is told when its platform makes no doors (P125): no served frame is made. */
77
76
  export const NO_DOOR_PLATFORM =
78
- "This platform makes no door frames (PlatformHost.createDoor, P125), so no served display that isn't nested is framed on it";
77
+ "This platform makes no door frames (PlatformHost.createDoor, P125), so no served display is framed on it";
79
78
 
80
79
  const BASE_KEYS = new Set(["hostContextChanged", "teardown", "close"]);
81
80
 
@@ -120,10 +119,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
120
119
  }
121
120
  // A url frame is someone else's app: no shell, no protocol, and its navigations are its own.
122
121
  const speaks = config.mode !== "url";
123
- const nested = config.nested === true;
124
122
  // A served display on its scope's origin, beside the scope's other content (P125): its door
125
123
  // says how loading went, before its frame is made.
126
- const hasDoor = config.isolation === "domain" && speaks && !nested;
124
+ const hasDoor = config.isolation === "domain" && speaks;
127
125
  const adapter = (options.adapter ?? shellAdapter) as ProtocolAdapter<C>;
128
126
  const platform = options.platform ?? webPlatform;
129
127
  const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
@@ -381,18 +379,6 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
381
379
  return undefined;
382
380
  }
383
381
  };
384
- /**
385
- * Whether the person is known to have made no gesture just now (P105): the platform says the
386
- * page has no transient activation, or fails to say. Where it can't tell (undefined), as for
387
- * the gesture gate, a report passes.
388
- */
389
- const noGesture = (): boolean => {
390
- try {
391
- return surface?.userActivation() === false;
392
- } catch {
393
- return true;
394
- }
395
- };
396
382
  /**
397
383
  * Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
398
384
  * places the host's own UI nowhere outside its frame. A mark's `documentRect` and the
@@ -432,7 +418,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
432
418
  /**
433
419
  * A report from the frame: checked, taken only while the host asked for it (a selection
434
420
  * only in select mode, results only for its own marks, a marker's click only for a mark it
435
- * shows with one, a count's or a draft's, within a gesture), then through the bridge's gates.
421
+ * shows with one, a count's or a draft's), then through the bridge's gates. No proof of a
422
+ * gesture is asked of a marker's click (0.16.0, P149): what a host opens for one takes no
423
+ * focus and does nothing by itself (THREAT_MODEL §6), and a page that says it unasked only
424
+ * shows that.
436
425
  */
437
426
  const onAnnotation = (raw: unknown, through: HostFunctionBridge) => {
438
427
  if (
@@ -536,13 +525,6 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
536
525
  if (!marks.some((mark) => mark.id === id && hasMarker(mark))) {
537
526
  return;
538
527
  }
539
- // A marker's real click gives the host's page transient activation (measured on all
540
- // three engines, P105); a click a page posts at load, on a timer or on a scroll has
541
- // none and is dropped. One posted on the person's own press in the content passes: the
542
- // host's view guards itself against that (THREAT_MODEL §6).
543
- if (noGesture()) {
544
- return;
545
- }
546
528
  break;
547
529
  }
548
530
  }
@@ -910,8 +892,6 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
910
892
  allow: compiled.allow,
911
893
  referrerPolicy: compiled.referrerPolicy,
912
894
  colorScheme: scheme,
913
- // A nested page's shell (P111): the config's word, never the frame's.
914
- ...(config.nested === true ? { nested: true } : {}),
915
895
  // An app reports no size: its frame fills the host's container, at least the minimum;
916
896
  // so does any display the host mounts to fill, or whose layout fills (P065): its
917
897
  // content scrolls itself.
@@ -939,34 +919,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
939
919
  })
940
920
  : framed;
941
921
  surface = created;
942
- // The focus guard undid a move of the keyboard into this frame (P109): heard each time,
943
- // and a frame that keeps taking it is stopped, as one that keeps navigating away is.
944
- const takes: { at: number; counts: boolean }[] = [];
945
- created.onFocusTaken?.(({ typing, failed }) => {
946
- const at = Date.now();
947
- // While the person typed, or a take-back that failed (the keys then go to the frame and
948
- // the page sees no typing): either counts toward the first rule.
949
- takes.push({ at, counts: typing || failed });
950
- const within = (ms: number) => takes.filter((take) => at - take.at <= ms);
951
- emit("focusTaken", { typing });
952
- if (
953
- surface === created &&
954
- (within(TAKES.typing.withinMs).filter((take) => take.counts).length >=
955
- TAKES.typing.most ||
956
- within(TAKES.any.withinMs).length >= TAKES.any.most)
957
- ) {
958
- stop();
959
- contentError("The content kept taking the keyboard from the page; it was stopped.");
960
- }
961
- while (takes.length > 0 && at - (takes[0] as { at: number }).at > TAKES.typing.withinMs) {
962
- takes.shift();
963
- }
964
- });
965
922
  const watch = watchOutcome({
966
923
  surface: created,
967
924
  source,
968
925
  speaks,
969
- nested,
970
926
  timeoutMs: timeLeft,
971
927
  onOutcome: (outcome) => emit("outcome", outcome),
972
928
  // A frame status from the content (P124): never shown, the host's to hear.
@@ -1000,8 +956,6 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
1000
956
  ...(options.show === undefined ? {} : { show: options.show }),
1001
957
  ...(options.cached === undefined ? {} : { cached: options.cached }),
1002
958
  userActivation: () => created.userActivation(),
1003
- // The person in this frame (P109): the page's focus in it, after the focus guard.
1004
- focused: () => created.focused?.(),
1005
959
  onEvent: onBridge,
1006
960
  ...(declaration === null ? {} : { declaration }),
1007
961
  ...(viewer === undefined ? {} : { viewer }),
package/src/host/door.ts CHANGED
@@ -3,7 +3,7 @@ import { parseFrameStatus, SETTLE_MS } from "./outcome.ts";
3
3
  import type { FrameOutcome } from "./types.ts";
4
4
 
5
5
  /**
6
- * A served display's door (P125). A served display that isn't nested (a served shell, a page, a
6
+ * A served display's door (P125). A served display (a served shell, a page, a
7
7
  * view through the sandbox proxy) is framed on its scope's origin, where the scope's other displays
8
8
  * run content with `allow-same-origin`: one of them reaches a new document there before its first
9
9
  * script runs, so nothing its frame says, and nothing its silence suggests, is Porthole's word.