@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,240 @@
1
+ import { cutText } from "./navigation.ts";
2
+
3
+ /**
4
+ * What content said, as text a host can show (S05, P095), at a cost bounded whatever the frame
5
+ * sent. A frame's messages come structured-cloned, which keeps cycles and shared references (13
6
+ * objects each holding the next twice are 2^13 nodes written as a tree) and carries BigInt, Maps
7
+ * and nesting of any depth: `JSON.stringify` throws on the first and the second, and is
8
+ * exponential in the third.
9
+ *
10
+ * A string is as it is, cut. Anything else is written the way JSON writes it, with each object
11
+ * read once (`"[Circular]"` where it is inside itself, `"[Repeated]"` where it was written
12
+ * already), at most `nodes` values (`…` where it stops) and `depth` levels (`"[Object]"`,
13
+ * `"[Array]"` below), a boxed primitive as its value (as JSON does), a BigInt as `"5n"`
14
+ * (`"[BigInt]"` past 2,000 digits), a Date as its time, an Error as its name and message, any other
15
+ * object as its kind (`"[Map]"`), and anything that throws when read as `"[unreadable]"`; any of
16
+ * these but a boxed primitive and a Date means the text isn't `whole`. Every cut is `cutText`'s:
17
+ * no part of a sealed address's access is left at one. Never throws.
18
+ */
19
+
20
+ export interface TextLimits {
21
+ /** The longest the text is. */
22
+ readonly chars: number;
23
+ /** The most values read. */
24
+ readonly nodes: number;
25
+ /** The deepest an object or array is read. */
26
+ readonly depth: number;
27
+ }
28
+
29
+ /** An error report's: read past what the bridge keeps (2,000 characters, after the scrub). */
30
+ export const REPORT_TEXT_LIMITS: TextLimits = { chars: 8_000, nodes: 1_000, depth: 16 };
31
+
32
+ /** The text, and whether it is all of the value (nothing cut, stopped or left below the depth). */
33
+ export interface BoundedText {
34
+ readonly text: string;
35
+ readonly whole: boolean;
36
+ }
37
+
38
+ /** A BigInt past this has more digits than a report shows; its decimal text is superlinear. */
39
+ const BIGGEST = 10n ** 2_000n;
40
+
41
+ /** A boxed primitive's value, read by its own prototype's `valueOf` (which throws for a fake). */
42
+ function unboxed(kind: string, boxed: object): unknown {
43
+ switch (kind) {
44
+ case "String":
45
+ return String.prototype.valueOf.call(boxed);
46
+ case "Number":
47
+ return Number.prototype.valueOf.call(boxed);
48
+ case "Boolean":
49
+ return Boolean.prototype.valueOf.call(boxed);
50
+ default:
51
+ return BigInt.prototype.valueOf.call(boxed);
52
+ }
53
+ }
54
+
55
+ /** A field whose read threw (a getter, a proxy: what structured clone never delivers). */
56
+ const UNREADABLE: unique symbol = Symbol("unreadable");
57
+
58
+ /** `value` as bounded text (above); with `indent`, as `JSON.stringify(value, null, indent)` lays it out. */
59
+ export function boundedText(
60
+ value: unknown,
61
+ limits: TextLimits = REPORT_TEXT_LIMITS,
62
+ indent = 0,
63
+ ): string {
64
+ return formatBounded(value, limits, indent).text;
65
+ }
66
+
67
+ export function formatBounded(value: unknown, limits: TextLimits, indent = 0): BoundedText {
68
+ if (typeof value === "string") {
69
+ const text = cutText(value, limits.chars);
70
+ return { text, whole: text === value };
71
+ }
72
+ let out = "";
73
+ let nodes = limits.nodes;
74
+ let stopped = false;
75
+ let whole = true;
76
+ const written = new WeakSet<object>();
77
+ const inside = new WeakSet<object>();
78
+ const colon = indent > 0 ? ": " : ":";
79
+ const quoted = (text: string) => {
80
+ const room = Math.max(0, limits.chars - out.length);
81
+ if (text.length > room) {
82
+ whole = false;
83
+ }
84
+ return JSON.stringify(cutText(text, room));
85
+ };
86
+ /** Where a nested value starts, at `depth`: a new line, indented, when laid out. */
87
+ const line = (depth: number) => (indent > 0 ? `\n${" ".repeat(indent * depth)}` : "");
88
+
89
+ /** Whether there is room for another value; if not, `…` once (after `separator`), then none. */
90
+ const room = (separator: string): boolean => {
91
+ nodes -= 1;
92
+ if (!stopped && (nodes < 0 || out.length >= limits.chars)) {
93
+ stopped = true;
94
+ whole = false;
95
+ out += `${separator}…`;
96
+ }
97
+ return !stopped;
98
+ };
99
+
100
+ /** What JSON leaves out of an object (and writes as null in an array). */
101
+ const unwritten = (each: unknown): boolean =>
102
+ each === undefined || typeof each === "function" || typeof each === "symbol";
103
+
104
+ function write(each: unknown, depth: number): void {
105
+ switch (typeof each) {
106
+ case "string":
107
+ out += quoted(each);
108
+ return;
109
+ case "number":
110
+ out += Number.isFinite(each) ? String(each) : "null";
111
+ return;
112
+ case "boolean":
113
+ out += each ? "true" : "false";
114
+ return;
115
+ case "bigint":
116
+ // No JSON for it: its digits, or past 2,000 of them its kind, and either way not whole.
117
+ whole = false;
118
+ out += each < BIGGEST && each > -BIGGEST ? `"${String(each)}n"` : '"[BigInt]"';
119
+ return;
120
+ case "object":
121
+ break;
122
+ default:
123
+ out += "null";
124
+ return;
125
+ }
126
+ if (each === null) {
127
+ out += "null";
128
+ return;
129
+ }
130
+ if (inside.has(each)) {
131
+ whole = false;
132
+ out += '"[Circular]"';
133
+ return;
134
+ }
135
+ if (written.has(each)) {
136
+ whole = false;
137
+ out += '"[Repeated]"';
138
+ return;
139
+ }
140
+ written.add(each);
141
+ if (Array.isArray(each)) {
142
+ if (depth >= limits.depth) {
143
+ whole = false;
144
+ out += '"[Array]"';
145
+ return;
146
+ }
147
+ const list = each as readonly unknown[];
148
+ inside.add(list);
149
+ out += "[";
150
+ const inner = line(depth + 1);
151
+ for (
152
+ let index = 0;
153
+ index < list.length && room(index === 0 ? inner : `,${inner}`);
154
+ index += 1
155
+ ) {
156
+ out += index === 0 ? inner : `,${inner}`;
157
+ guarded(list[index], depth + 1);
158
+ }
159
+ out += list.length === 0 ? "]" : `${line(depth)}]`;
160
+ inside.delete(list);
161
+ return;
162
+ }
163
+ const kind = Object.prototype.toString.call(each).slice(8, -1);
164
+ const proto: unknown = Object.getPrototypeOf(each);
165
+ // A boxed primitive is its value, as JSON writes it (`new String("x")` is "x").
166
+ if (kind === "String" || kind === "Number" || kind === "Boolean" || kind === "BigInt") {
167
+ write(unboxed(kind, each), depth);
168
+ return;
169
+ }
170
+ if (kind === "Date") {
171
+ const time = Date.prototype.getTime.call(each);
172
+ out += quoted(Number.isFinite(time) ? new Date(time).toISOString() : "Invalid Date");
173
+ return;
174
+ }
175
+ if (kind === "Error") {
176
+ whole = false;
177
+ const { name, message } = each as { name?: unknown; message?: unknown };
178
+ out += quoted(
179
+ `${typeof name === "string" ? cutText(name, 100) : "Error"}: ${typeof message === "string" ? cutText(message, limits.chars) : ""}`,
180
+ );
181
+ return;
182
+ }
183
+ if (proto !== Object.prototype && proto !== null) {
184
+ // A Map, a typed array, a Blob: its kind only, so the text is no longer all of it.
185
+ whole = false;
186
+ out += quoted(`[${kind}]`);
187
+ return;
188
+ }
189
+ if (depth >= limits.depth) {
190
+ whole = false;
191
+ out += '"[Object]"';
192
+ return;
193
+ }
194
+ inside.add(each);
195
+ out += "{";
196
+ const inner = line(depth + 1);
197
+ let first = true;
198
+ for (const key of Object.keys(each)) {
199
+ if (!room(first ? inner : `,${inner}`)) {
200
+ first = false;
201
+ break;
202
+ }
203
+ let field: unknown;
204
+ try {
205
+ field = (each as Record<string, unknown>)[key];
206
+ } catch {
207
+ field = UNREADABLE;
208
+ }
209
+ if (field !== UNREADABLE && unwritten(field)) {
210
+ continue;
211
+ }
212
+ out += `${first ? inner : `,${inner}`}${quoted(key)}${colon}`;
213
+ first = false;
214
+ guarded(field, depth + 1);
215
+ }
216
+ out += first ? "}" : `${line(depth)}}`;
217
+ inside.delete(each);
218
+ }
219
+
220
+ /** One value, or `"[unreadable]"` where reading it throws (a getter, a proxy: never cloned). */
221
+ function guarded(each: unknown, depth: number): void {
222
+ if (each === UNREADABLE) {
223
+ out += '"[unreadable]"';
224
+ return;
225
+ }
226
+ const before = out.length;
227
+ try {
228
+ write(each, depth);
229
+ } catch {
230
+ whole = false;
231
+ out = `${out.slice(0, before)}"[unreadable]"`;
232
+ }
233
+ }
234
+
235
+ nodes -= 1;
236
+ guarded(value, 0);
237
+ // Cut past the length, it still ends in `…`.
238
+ const text = out.length <= limits.chars ? out : `${cutText(out, limits.chars - 1)}…`;
239
+ return { text, whole: whole && text === out };
240
+ }