@botiverse/porthole 0.7.0 → 0.8.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 (153) hide show
  1. package/README.md +9 -2
  2. package/THIRD_PARTY_NOTICES.md +421 -0
  3. package/dist/bridge/bounded-text.d.ts +34 -0
  4. package/dist/bridge/bounded-text.js +188 -0
  5. package/dist/bridge/bridge.d.ts +25 -5
  6. package/dist/bridge/bridge.js +311 -73
  7. package/dist/bridge/json-data.d.ts +28 -0
  8. package/dist/bridge/json-data.js +86 -0
  9. package/dist/bridge/navigation.d.ts +5 -0
  10. package/dist/bridge/navigation.js +7 -0
  11. package/dist/bridge/refusal.js +1 -0
  12. package/dist/bridge/types.d.ts +32 -1
  13. package/dist/check/page-source.js +1 -1
  14. package/dist/check/page.js +2 -0
  15. package/dist/compile/compile.d.ts +6 -0
  16. package/dist/compile/compile.js +3 -1
  17. package/dist/compile/policy.d.ts +38 -2
  18. package/dist/compile/policy.js +122 -7
  19. package/dist/config/capabilities.d.ts +23 -4
  20. package/dist/config/capabilities.js +12 -2
  21. package/dist/config/schema.d.ts +11 -0
  22. package/dist/config/validate.d.ts +8 -2
  23. package/dist/config/validate.js +28 -6
  24. package/dist/config/warnings.d.ts +20 -0
  25. package/dist/config/warnings.js +25 -0
  26. package/dist/conformance/behavior.js +46 -1
  27. package/dist/conformance/cookies.d.ts +15 -0
  28. package/dist/conformance/cookies.js +80 -0
  29. package/dist/conformance/harness/page.d.ts +1 -0
  30. package/dist/conformance/harness/page.js +9 -2
  31. package/dist/conformance/harness-source.js +1 -1
  32. package/dist/conformance/host-kit.js +5 -1
  33. package/dist/conformance/index.d.ts +10 -0
  34. package/dist/conformance/limits.js +38 -1
  35. package/dist/conformance/runtime.js +10 -0
  36. package/dist/conformance/served.d.ts +2 -0
  37. package/dist/conformance/served.js +737 -4
  38. package/dist/files/paths.js +4 -0
  39. package/dist/guide/gates.d.ts +7 -1
  40. package/dist/guide/gates.js +12 -0
  41. package/dist/guide/guide.js +2 -2
  42. package/dist/guide/runtime.js +11 -3
  43. package/dist/host/create-host.js +49 -37
  44. package/dist/host/pages-of-set.d.ts +43 -0
  45. package/dist/host/pages-of-set.js +196 -0
  46. package/dist/host/types.d.ts +8 -1
  47. package/dist/index.d.ts +5 -4
  48. package/dist/index.js +3 -2
  49. package/dist/mcp/adapter.js +11 -15
  50. package/dist/node/index.d.ts +36 -4
  51. package/dist/node/index.js +402 -101
  52. package/dist/presets/presets.d.ts +16 -8
  53. package/dist/presets/presets.js +39 -8
  54. package/dist/protocol/live-data.d.ts +6 -2
  55. package/dist/protocol/live-data.js +20 -1
  56. package/dist/protocol/mcp-apps.d.ts +13 -2
  57. package/dist/protocol/mcp-apps.js +10 -2
  58. package/dist/protocol/message-text.d.ts +8 -0
  59. package/dist/protocol/message-text.js +29 -0
  60. package/dist/protocol/runtime-calls.js +3 -0
  61. package/dist/protocol/shell-adapter.js +16 -22
  62. package/dist/react/context-notice.d.ts +32 -0
  63. package/dist/react/context-notice.js +28 -0
  64. package/dist/react/dialog.js +62 -18
  65. package/dist/react/frame.d.ts +12 -1
  66. package/dist/react/frame.js +79 -2
  67. package/dist/react/index.d.ts +2 -1
  68. package/dist/react/index.js +2 -1
  69. package/dist/runtime/contract.d.ts +9 -1
  70. package/dist/runtime/contract.js +31 -2
  71. package/dist/runtime/db.d.ts +41 -6
  72. package/dist/runtime/db.js +120 -16
  73. package/dist/runtime/declaration.d.ts +15 -1
  74. package/dist/runtime/declaration.js +184 -87
  75. package/dist/runtime/requests.js +27 -11
  76. package/dist/runtime/types.generated.js +1 -1
  77. package/dist/server/files.d.ts +5 -0
  78. package/dist/server/files.js +22 -7
  79. package/dist/server/host.d.ts +18 -1
  80. package/dist/server/host.js +132 -2
  81. package/dist/server/index.d.ts +1 -1
  82. package/dist/server/index.js +1 -1
  83. package/dist/server/peer.d.ts +4 -0
  84. package/dist/server/peer.js +19 -0
  85. package/dist/server/proxy.d.ts +6 -0
  86. package/dist/server/proxy.js +12 -3
  87. package/dist/server/server.js +113 -26
  88. package/dist/server/types.d.ts +6 -3
  89. package/dist/shell/document.d.ts +8 -0
  90. package/dist/shell/document.js +3 -0
  91. package/dist/shell/runtime.js +361 -14
  92. package/docs/ADOPTING.md +119 -14
  93. package/docs/ARCHITECTURE.md +13 -3
  94. package/docs/DECISIONS.md +1455 -8
  95. package/docs/DESIGN.md +79 -25
  96. package/docs/THREAT_MODEL.md +616 -0
  97. package/package.json +14 -3
  98. package/src/bridge/bounded-text.ts +240 -0
  99. package/src/bridge/bridge.ts +373 -84
  100. package/src/bridge/json-data.ts +95 -0
  101. package/src/bridge/navigation.ts +10 -0
  102. package/src/bridge/refusal.ts +1 -0
  103. package/src/bridge/types.ts +30 -1
  104. package/src/check/page.ts +2 -0
  105. package/src/compile/compile.ts +9 -1
  106. package/src/compile/policy.ts +130 -7
  107. package/src/config/capabilities.ts +22 -3
  108. package/src/config/schema.ts +11 -0
  109. package/src/config/validate.ts +43 -5
  110. package/src/config/warnings.ts +42 -0
  111. package/src/conformance/behavior.ts +54 -1
  112. package/src/conformance/cookies.ts +93 -0
  113. package/src/conformance/harness/page.ts +11 -2
  114. package/src/conformance/host-kit.ts +10 -1
  115. package/src/conformance/index.ts +10 -0
  116. package/src/conformance/limits.ts +39 -1
  117. package/src/conformance/runtime.ts +21 -0
  118. package/src/conformance/served.ts +888 -4
  119. package/src/files/paths.ts +4 -0
  120. package/src/guide/gates.ts +13 -1
  121. package/src/guide/guide.ts +3 -3
  122. package/src/guide/runtime.ts +12 -3
  123. package/src/host/create-host.ts +54 -36
  124. package/src/host/pages-of-set.ts +226 -0
  125. package/src/host/types.ts +15 -1
  126. package/src/index.ts +5 -0
  127. package/src/mcp/adapter.ts +16 -20
  128. package/src/node/index.ts +507 -116
  129. package/src/presets/presets.ts +60 -17
  130. package/src/protocol/live-data.ts +31 -3
  131. package/src/protocol/mcp-apps.ts +11 -2
  132. package/src/protocol/message-text.ts +36 -0
  133. package/src/protocol/runtime-calls.ts +3 -0
  134. package/src/protocol/shell-adapter.ts +27 -23
  135. package/src/react/context-notice.tsx +95 -0
  136. package/src/react/dialog.tsx +77 -17
  137. package/src/react/frame.tsx +101 -0
  138. package/src/react/index.ts +8 -1
  139. package/src/runtime/contract.ts +36 -2
  140. package/src/runtime/db.ts +140 -20
  141. package/src/runtime/declaration.ts +227 -89
  142. package/src/runtime/requests.ts +27 -11
  143. package/src/runtime/types.generated.ts +1 -1
  144. package/src/server/files.ts +29 -11
  145. package/src/server/host.ts +158 -3
  146. package/src/server/index.ts +1 -0
  147. package/src/server/peer.ts +21 -0
  148. package/src/server/proxy.ts +13 -3
  149. package/src/server/server.ts +139 -36
  150. package/src/server/types.ts +6 -3
  151. package/src/shell/document.ts +8 -0
  152. package/src/shell/runtime.ts +361 -14
  153. package/types/runtime/v1/context.d.ts +13 -2
@@ -0,0 +1,80 @@
1
+ /**
2
+ * Whether this browser keeps a cookie a cross-site frame's own document was answered with
3
+ * (P025, P098): what a framed url-mode app needs, since its every request rides on the cookie its
4
+ * ticket's answer set. Measured, never assumed from the engine's name: Playwright's WebKit keeps
5
+ * none on Linux and keeps them on macOS (the audit of 2026-10-19), and an engine's policy changes
6
+ * between versions.
7
+ *
8
+ * The probe is the browser's own, outside the host under test: in a context of its own, a page on
9
+ * one site frames a page on another (both answered by the probe's routes, never the network,
10
+ * never the host's server), whose answer sets a cookie as Porthole's server sets a framed one
11
+ * (`Secure; SameSite=None; Partitioned`, over the display's own scheme); the frame then reads
12
+ * whether it was kept. Asked once per browser.
13
+ */
14
+ export function keepsFramedCookies(page, scheme) {
15
+ const browser = page.context().browser();
16
+ const key = `${scheme} ${browser === null ? "persistent" : browser.version()}`;
17
+ const known = cache(browser ?? page.context());
18
+ let answer = known.get(key);
19
+ if (answer === undefined) {
20
+ answer = probe(browser, page.context(), scheme);
21
+ known.set(key, answer);
22
+ }
23
+ return answer;
24
+ }
25
+ const answers = new WeakMap();
26
+ function cache(owner) {
27
+ let known = answers.get(owner);
28
+ if (known === undefined) {
29
+ known = new Map();
30
+ answers.set(owner, known);
31
+ }
32
+ return known;
33
+ }
34
+ /** Two sites the probe makes up: the embedding page's, and the frame's. */
35
+ function sites(scheme) {
36
+ // Over http, as a loopback host and its content origins are (a `*.localhost` frame on a
37
+ // `127.0.0.1` page, the leak suite's own shape); over https, two names that are each a site.
38
+ // Default ports: a browser refuses to navigate to some others (9 is on Fetch's bad-port list).
39
+ return scheme === "http:"
40
+ ? {
41
+ top: "http://127.0.0.1/__porthole-cookie-probe/",
42
+ framed: "http://porthole-cookie-probe.localhost/",
43
+ }
44
+ : {
45
+ top: "https://porthole-cookie-probe-top.test/",
46
+ framed: "https://porthole-cookie-probe-frame.test/",
47
+ };
48
+ }
49
+ async function probe(browser, context, scheme) {
50
+ const own = browser === null ? null : await browser.newContext();
51
+ const page = await (own ?? context).newPage();
52
+ try {
53
+ const { top, framed } = sites(scheme);
54
+ await page.route(`${framed}**`, (route) => route.fulfill({
55
+ status: 200,
56
+ headers: {
57
+ "content-type": "text/html; charset=utf-8",
58
+ "cache-control": "no-store",
59
+ "set-cookie": "porthole-cookie-probe=1; Path=/; Secure; SameSite=None; Partitioned",
60
+ },
61
+ body: "<!doctype html><title>probe</title>",
62
+ }));
63
+ await page.route(top, (route) => route.fulfill({
64
+ status: 200,
65
+ headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
66
+ body: `<!doctype html><title>probe</title><iframe src="${framed}frame"></iframe>`,
67
+ }));
68
+ await page.goto(top);
69
+ const frame = await (await page.locator("iframe").elementHandle())?.contentFrame();
70
+ if (frame === null || frame === undefined) {
71
+ throw new Error("keepsFramedCookies: the probe's frame didn't load");
72
+ }
73
+ await frame.waitForLoadState("load");
74
+ return await frame.evaluate(() => document.cookie.includes("porthole-cookie-probe=1"));
75
+ }
76
+ finally {
77
+ await page.close();
78
+ await own?.close();
79
+ }
80
+ }
@@ -21,6 +21,7 @@ declare const harness: {
21
21
  post(id: number, message: unknown): void;
22
22
  setContent(id: number, html: string, partial: boolean): void;
23
23
  calls: (id: number) => RecordedCall[];
24
+ shown: (id: number) => ConfirmRequest[];
24
25
  events: (id: number) => RecordedEvent[];
25
26
  errors: (id: number) => string[];
26
27
  pendingConfirmations: (id: number) => number;
@@ -78,6 +78,7 @@ const harness = {
78
78
  const container = box(id, spec.widthPx ?? 600, spec.heightPx);
79
79
  const calls = [];
80
80
  const confirmations = [];
81
+ const disclosed = [];
81
82
  const host = createHost(spec.config, {
82
83
  handlers: recorder(calls),
83
84
  ...(spec.confirms === false
@@ -85,6 +86,9 @@ const harness = {
85
86
  : {
86
87
  confirm: (request) => new Promise((resolve) => confirmations.push({ request, resolve })),
87
88
  }),
89
+ ...(spec.shows === false
90
+ ? {}
91
+ : { show: (request) => void disclosed.push(request) }),
88
92
  theme: (scheme) => spec.hostTheme?.[scheme] ?? {},
89
93
  hostInfo: { name: "porthole-conformance", version: "1" },
90
94
  ...(nonce === undefined ? {} : { nonce }),
@@ -95,18 +99,19 @@ const harness = {
95
99
  scheme: spec.scheme ?? "light",
96
100
  ...(spec.document === undefined ? {} : { document: spec.document }),
97
101
  });
98
- const shown = {
102
+ const display = {
99
103
  handle,
100
104
  calls,
101
105
  events: [],
102
106
  confirmations,
107
+ disclosed,
103
108
  received: [],
104
109
  origin: null,
105
110
  failure: null,
106
111
  frame: null,
107
112
  };
108
113
  const initialized = new Promise((resolve) => handle.on("initialized", () => resolve()));
109
- watch(id, shown);
114
+ watch(id, display);
110
115
  if (spec.document === undefined) {
111
116
  await Promise.race([initialized, pause(5_000)]);
112
117
  for (const partial of spec.partials ?? []) {
@@ -133,6 +138,7 @@ const harness = {
133
138
  calls,
134
139
  events: [],
135
140
  confirmations: [],
141
+ disclosed: [],
136
142
  received: [],
137
143
  origin: null,
138
144
  failure: null,
@@ -194,6 +200,7 @@ const harness = {
194
200
  displays.get(id)?.handle.setContent(html, { partial });
195
201
  },
196
202
  calls: (id) => displays.get(id)?.calls ?? [],
203
+ shown: (id) => displays.get(id)?.disclosed ?? [],
197
204
  events: (id) => displays.get(id)?.events ?? [],
198
205
  errors: (id) => (displays.get(id)?.events ?? []).flatMap((event) => event.type === "error" ? [event.detail.message] : []),
199
206
  pendingConfirmations: (id) => displays.get(id)?.confirmations.length ?? 0,