@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,86 @@
1
+ /**
2
+ * JSON data, as a host function carries it to a host's handler and its dialog (P095, after the
3
+ * review): what `callTool`'s arguments, `setModelContext`'s content and a download's contents are
4
+ * in MCP, and what a host forwards to a server or a model as JSON. A frame's messages come
5
+ * structured-cloned, so they can hold what JSON can't say or says otherwise: a cycle, an object
6
+ * reached twice (a graph of 30 is 2^30 nodes as a tree), a BigInt, NaN, a boxed `String` (JSON
7
+ * writes its value; a handler gets an object), a Map, a typed array, a Date.
8
+ *
9
+ * Plain data only: null, booleans, finite numbers, strings, arrays and objects whose prototype is
10
+ * Object's or none, each object reached once (MCP's arguments are JSON: an object in two places is
11
+ * refused, the simple bound), at most `nodes` values (a field left `undefined`, allowed as JSON
12
+ * leaves it out, counts as one), `depth` levels, and `chars` characters of strings and keys
13
+ * together (after the re-review: neither a field without a value nor a long string is free).
14
+ * Each node is visited once: linear in what was sent, stopped at the budget. Never throws (a
15
+ * value whose read throws is no data).
16
+ */
17
+ /**
18
+ * A call's: as many values as one db document holds (P091), nested deeper than any real one, and
19
+ * 4 MiB of text.
20
+ */
21
+ export const JSON_DATA_LIMITS = { nodes: 100_000, depth: 64, chars: 4_194_304 };
22
+ export function isJsonData(value, limits = JSON_DATA_LIMITS) {
23
+ let nodes = limits.nodes;
24
+ let chars = limits.chars;
25
+ const seen = new WeakSet();
26
+ /** Takes `length` characters from the budget: whether it still holds. */
27
+ const text = (length) => {
28
+ chars -= length;
29
+ return chars >= 0;
30
+ };
31
+ function plain(each, depth) {
32
+ nodes -= 1;
33
+ if (nodes < 0 || depth > limits.depth) {
34
+ return false;
35
+ }
36
+ if (typeof each === "string") {
37
+ return text(each.length);
38
+ }
39
+ if (each === null || typeof each === "boolean") {
40
+ return true;
41
+ }
42
+ if (typeof each === "number") {
43
+ return Number.isFinite(each);
44
+ }
45
+ if (typeof each !== "object" || seen.has(each)) {
46
+ return false;
47
+ }
48
+ seen.add(each);
49
+ if (Array.isArray(each)) {
50
+ const list = each;
51
+ for (let index = 0; index < list.length; index += 1) {
52
+ if (!plain(list[index], depth + 1)) {
53
+ return false;
54
+ }
55
+ }
56
+ return true;
57
+ }
58
+ const proto = Object.getPrototypeOf(each);
59
+ if (proto !== Object.prototype && proto !== null) {
60
+ return false;
61
+ }
62
+ for (const key of Object.keys(each)) {
63
+ if (!text(key.length)) {
64
+ return false;
65
+ }
66
+ const field = each[key];
67
+ if (field === undefined) {
68
+ // No value, but a field: it counts.
69
+ nodes -= 1;
70
+ if (nodes < 0) {
71
+ return false;
72
+ }
73
+ }
74
+ else if (!plain(field, depth + 1)) {
75
+ return false;
76
+ }
77
+ }
78
+ return true;
79
+ }
80
+ try {
81
+ return plain(value, 0);
82
+ }
83
+ catch {
84
+ return false;
85
+ }
86
+ }
@@ -1,5 +1,10 @@
1
1
  import type { PortholeConfig } from "../config/schema.ts";
2
2
  export declare const withoutSealedAddresses: (text: string) => string;
3
+ /**
4
+ * `text`, at most `max` characters (S05, P095): a cut inside a sealed address's access drops what
5
+ * of it is left, so a text cut before it is scrubbed tells no part of one.
6
+ */
7
+ export declare const cutText: (text: string, max: number) => string;
3
8
  /** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
4
9
  export declare function addressWithoutQuery(url: string): string;
5
10
  /** What the content's errors say about a navigation the shell cancelled. */
@@ -10,6 +10,13 @@
10
10
  */
11
11
  const SEALED = /(?:https?:\/\/[^\s"'<>/]+)?\/__porthole\/f\/[A-Za-z0-9_-]{20,}\//gu;
12
12
  export const withoutSealedAddresses = (text) => text.replace(SEALED, "./");
13
+ /** A sealed address's access, cut off by the end of the text: no longer one `SEALED` matches. */
14
+ const UNFINISHED = /\/__porthole\/f\/[A-Za-z0-9_-]*$/u;
15
+ /**
16
+ * `text`, at most `max` characters (S05, P095): a cut inside a sealed address's access drops what
17
+ * of it is left, so a text cut before it is scrubbed tells no part of one.
18
+ */
19
+ export const cutText = (text, max) => text.length <= max ? text : text.slice(0, max).replace(UNFINISHED, "");
13
20
  /** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
14
21
  export function addressWithoutQuery(url) {
15
22
  // A page's own file (P084), as the shell names it: its path, without query or fragment.
@@ -100,6 +100,7 @@ const CODES = {
100
100
  redirected: "denied",
101
101
  muted: "denied",
102
102
  "no-consent": "not_allowed",
103
+ "no-show": "not_allowed",
103
104
  denied: "denied",
104
105
  "rate-limited": "rate_limited",
105
106
  failed: "failed",
@@ -81,6 +81,13 @@ export type ConfirmRequest = {
81
81
  readonly capability: N;
82
82
  readonly args: CapabilityArgs[N];
83
83
  readonly display: ConfirmDisplay;
84
+ /**
85
+ * A confirmation only (never a consent's request): the runtime methods whose own gates
86
+ * (`CapabilityConfig.methodGates`, the contract's) asked for it, of those the call runs (P094):
87
+ * a db batch's writes' ops that need a yes, so a dialog can lead with them. Absent where only
88
+ * the host function's own gates ask.
89
+ */
90
+ readonly askedBy?: readonly string[];
84
91
  };
85
92
  }[CapabilityName];
86
93
  /**
@@ -96,6 +103,17 @@ export type ConfirmAnswer = boolean | "accepted" | "declined" | "redirected";
96
103
  * its own "yes" button, rather than resolving the promise and letting the effect run after.
97
104
  */
98
105
  export type Proceed = () => void;
106
+ /**
107
+ * Puts a call's whole effect in front of the person, outside every frame (the `show` gate, P100):
108
+ * a `setModelContext` update's text and structured content, which the model reads at its next
109
+ * turns. It asks nothing; the call goes once it returns (or its promise resolves), so it resolves
110
+ * only once this very update is visible: drawn, not queued behind a render (after the review). An
111
+ * update the person never saw, because a later one of the display replaced it first, rejects:
112
+ * the call doesn't go. One that throws or rejects stops the call: nobody saw it. Each update
113
+ * replaces the display's last (MCP Apps: the host sends the model the last one), so a surface
114
+ * shows the latest per display.
115
+ */
116
+ export type Show = (request: ConfirmRequest) => void | Promise<void>;
99
117
  /**
100
118
  * Asks a person. Resolves with their answer. The host's UI, or the React binding's default
101
119
  * dialog; drawn outside the frame, never inside it. `proceed` (optional to use) runs the effect
@@ -120,9 +138,11 @@ export type Refusal =
120
138
  | "muted"
121
139
  /** It is `consent`-gated and there is no `consent` function. */
122
140
  | "no-consent"
141
+ /** It is `show`-gated and there is no `show` function: nobody could see it (P100). */
142
+ | "no-show"
123
143
  /** The host's `consent` said no (for this display's life). */
124
144
  | "denied" | "rate-limited"
125
- /** The host's handler threw or rejected. */
145
+ /** The host's handler threw or rejected (or its `show` did: nobody saw the call, P100). */
126
146
  | "failed"
127
147
  /**
128
148
  * The display's page declared capabilities and not this one (P086): a built-in needs none, any
@@ -158,6 +178,17 @@ export interface CallOptions {
158
178
  readonly subscription?: Pick<SubscriptionContext, "changed" | "signal">;
159
179
  /** `readData`: the host's cache may answer, marked stale (the content subscribes to it). */
160
180
  readonly stale?: boolean;
181
+ /**
182
+ * `readData`: a result the host already gave for this read (a subscription's `changed(result)`,
183
+ * the fresh read after a stale answer), and the URI it was given for. It answers the read after
184
+ * every gate a read has, without the handler or the cache (P094: a kept result is never a way
185
+ * past the read's gates); a `uri` that isn't the read's is refused (`invalid`). Ignored for any
186
+ * capability but `readData`.
187
+ */
188
+ readonly held?: {
189
+ readonly uri: string;
190
+ readonly value: unknown;
191
+ };
161
192
  }
162
193
  /** What adapters call; one per display. */
163
194
  export interface HostFunctionBridge {