@botiverse/porthole 0.5.1 → 0.7.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 (167) hide show
  1. package/README.md +41 -0
  2. package/dist/bridge/bridge.d.ts +13 -0
  3. package/dist/bridge/bridge.js +208 -13
  4. package/dist/bridge/navigation.d.ts +1 -6
  5. package/dist/bridge/navigation.js +11 -0
  6. package/dist/bridge/refusal.d.ts +5 -1
  7. package/dist/bridge/refusal.js +16 -0
  8. package/dist/bridge/types.d.ts +41 -4
  9. package/dist/check/check.d.ts +19 -3
  10. package/dist/check/check.js +55 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/instrument.d.ts +3 -0
  14. package/dist/check/lint.js +31 -12
  15. package/dist/check/page-source.js +1 -1
  16. package/dist/check/page.js +14 -0
  17. package/dist/check/tools.d.ts +23 -0
  18. package/dist/check/tools.js +27 -3
  19. package/dist/compile/policy.d.ts +34 -0
  20. package/dist/compile/policy.js +74 -0
  21. package/dist/config/capabilities.d.ts +62 -3
  22. package/dist/config/capabilities.js +20 -0
  23. package/dist/config/schema.d.ts +32 -0
  24. package/dist/config/validate.d.ts +1 -1
  25. package/dist/config/validate.js +74 -5
  26. package/dist/conformance/harness-source.js +1 -1
  27. package/dist/conformance/index.d.ts +1 -0
  28. package/dist/conformance/index.js +2 -0
  29. package/dist/conformance/runtime.d.ts +58 -0
  30. package/dist/conformance/runtime.js +314 -0
  31. package/dist/files/paths.d.ts +99 -0
  32. package/dist/files/paths.js +263 -0
  33. package/dist/files/types.d.ts +24 -0
  34. package/dist/files/types.js +83 -0
  35. package/dist/guide/gates.d.ts +3 -0
  36. package/dist/guide/gates.js +19 -0
  37. package/dist/guide/guide.d.ts +2 -0
  38. package/dist/guide/guide.js +44 -32
  39. package/dist/guide/limits.js +4 -4
  40. package/dist/guide/runtime.d.ts +13 -0
  41. package/dist/guide/runtime.js +202 -0
  42. package/dist/host/create-host.js +45 -0
  43. package/dist/host/locate.js +8 -0
  44. package/dist/host/locator.js +7 -0
  45. package/dist/host/types.d.ts +18 -0
  46. package/dist/index.d.ts +13 -4
  47. package/dist/index.js +16 -3
  48. package/dist/isolation/types.d.ts +8 -0
  49. package/dist/presets/presets.d.ts +6 -0
  50. package/dist/presets/presets.js +1 -0
  51. package/dist/protocol/adapter.d.ts +4 -0
  52. package/dist/protocol/mcp-apps.d.ts +6 -0
  53. package/dist/protocol/mcp-apps.js +6 -0
  54. package/dist/protocol/runtime-calls.d.ts +28 -0
  55. package/dist/protocol/runtime-calls.js +113 -0
  56. package/dist/protocol/shell-adapter.js +52 -3
  57. package/dist/react/dialog.js +31 -0
  58. package/dist/react/frame.d.ts +13 -0
  59. package/dist/react/frame.js +6 -0
  60. package/dist/runtime/contract.d.ts +193 -0
  61. package/dist/runtime/contract.js +216 -0
  62. package/dist/runtime/db.d.ts +153 -0
  63. package/dist/runtime/db.js +398 -0
  64. package/dist/runtime/declaration.d.ts +86 -0
  65. package/dist/runtime/declaration.js +266 -0
  66. package/dist/runtime/levels.d.ts +33 -0
  67. package/dist/runtime/levels.js +41 -0
  68. package/dist/runtime/requests.d.ts +125 -0
  69. package/dist/runtime/requests.js +199 -0
  70. package/dist/runtime/segments.d.ts +8 -0
  71. package/dist/runtime/segments.js +14 -0
  72. package/dist/runtime/types.generated.d.ts +1 -0
  73. package/dist/runtime/types.generated.js +19 -0
  74. package/dist/server/files.d.ts +57 -0
  75. package/dist/server/files.js +338 -0
  76. package/dist/server/host.d.ts +44 -2
  77. package/dist/server/host.js +42 -2
  78. package/dist/server/index.d.ts +5 -2
  79. package/dist/server/index.js +5 -1
  80. package/dist/server/keys.d.ts +8 -0
  81. package/dist/server/keys.js +34 -0
  82. package/dist/server/pseudonym.d.ts +9 -0
  83. package/dist/server/pseudonym.js +20 -0
  84. package/dist/server/server.d.ts +0 -5
  85. package/dist/server/server.js +468 -24
  86. package/dist/server/types.d.ts +118 -5
  87. package/dist/shell/document.d.ts +27 -0
  88. package/dist/shell/document.js +46 -2
  89. package/dist/shell/legacy.d.ts +21 -0
  90. package/dist/shell/legacy.js +63 -0
  91. package/dist/shell/plan.d.ts +17 -1
  92. package/dist/shell/plan.js +13 -2
  93. package/dist/shell/runtime.d.ts +2 -1
  94. package/dist/shell/runtime.js +114 -46
  95. package/dist/shell/use.d.ts +15 -0
  96. package/dist/shell/use.js +235 -0
  97. package/docs/ADOPTING.md +142 -5
  98. package/docs/ARCHITECTURE.md +34 -5
  99. package/docs/DECISIONS.md +716 -7
  100. package/docs/DESIGN.md +97 -3
  101. package/package.json +3 -1
  102. package/src/bridge/bridge.ts +281 -17
  103. package/src/bridge/navigation.ts +12 -0
  104. package/src/bridge/refusal.ts +16 -0
  105. package/src/bridge/types.ts +46 -4
  106. package/src/check/check.ts +100 -14
  107. package/src/check/files.ts +384 -0
  108. package/src/check/instrument.ts +3 -0
  109. package/src/check/lint.ts +33 -12
  110. package/src/check/page.ts +14 -0
  111. package/src/check/tools.ts +52 -3
  112. package/src/compile/policy.ts +92 -0
  113. package/src/config/capabilities.ts +49 -2
  114. package/src/config/schema.ts +32 -0
  115. package/src/config/validate.ts +107 -5
  116. package/src/conformance/index.ts +7 -0
  117. package/src/conformance/runtime.ts +573 -0
  118. package/src/files/paths.ts +323 -0
  119. package/src/files/types.ts +101 -0
  120. package/src/guide/gates.ts +25 -0
  121. package/src/guide/guide.ts +78 -52
  122. package/src/guide/limits.ts +4 -4
  123. package/src/guide/runtime.ts +244 -0
  124. package/src/host/create-host.ts +55 -0
  125. package/src/host/locate.ts +10 -0
  126. package/src/host/locator.ts +11 -0
  127. package/src/host/types.ts +18 -0
  128. package/src/index.ts +121 -0
  129. package/src/isolation/types.ts +8 -0
  130. package/src/presets/presets.ts +7 -0
  131. package/src/protocol/adapter.ts +3 -1
  132. package/src/protocol/mcp-apps.ts +7 -0
  133. package/src/protocol/runtime-calls.ts +138 -0
  134. package/src/protocol/shell-adapter.ts +56 -2
  135. package/src/react/dialog.tsx +33 -0
  136. package/src/react/frame.tsx +19 -0
  137. package/src/runtime/contract.ts +305 -0
  138. package/src/runtime/db.ts +530 -0
  139. package/src/runtime/declaration.ts +378 -0
  140. package/src/runtime/levels.ts +69 -0
  141. package/src/runtime/requests.ts +339 -0
  142. package/src/runtime/segments.ts +17 -0
  143. package/src/runtime/types.generated.ts +19 -0
  144. package/src/server/files.ts +425 -0
  145. package/src/server/host.ts +84 -3
  146. package/src/server/index.ts +22 -0
  147. package/src/server/keys.ts +53 -0
  148. package/src/server/pseudonym.ts +21 -0
  149. package/src/server/server.ts +565 -26
  150. package/src/server/types.ts +124 -4
  151. package/src/shell/document.ts +74 -4
  152. package/src/shell/legacy.ts +64 -0
  153. package/src/shell/plan.ts +37 -3
  154. package/src/shell/runtime.ts +114 -46
  155. package/src/shell/use.ts +235 -0
  156. package/types/runtime/v1/artifact.d.ts +50 -0
  157. package/types/runtime/v1/assets.d.ts +43 -0
  158. package/types/runtime/v1/chat.d.ts +13 -0
  159. package/types/runtime/v1/clipboard.d.ts +14 -0
  160. package/types/runtime/v1/comments.d.ts +24 -0
  161. package/types/runtime/v1/context.d.ts +16 -0
  162. package/types/runtime/v1/data.d.ts +29 -0
  163. package/types/runtime/v1/db.d.ts +110 -0
  164. package/types/runtime/v1/downloads.d.ts +22 -0
  165. package/types/runtime/v1/links.d.ts +13 -0
  166. package/types/runtime/v1/porthole.d.ts +44 -0
  167. package/types/runtime/v1/user.d.ts +19 -0
@@ -11,6 +11,14 @@ export interface Keys {
11
11
  sign(value: unknown): string;
12
12
  /** The signed value, or null when the signature doesn't hold. */
13
13
  verify(token: string): unknown;
14
+ /**
15
+ * `value` sealed (AES-256-GCM, Web Crypto): unreadable and unforgeable without the secret,
16
+ * base64url. A file set's access in a frame's path (P083), which content can read: the viewer
17
+ * and the host's subject inside it stay the host's.
18
+ */
19
+ seal(value: unknown): Promise<string>;
20
+ /** The sealed value, or null when it doesn't open. */
21
+ unseal(token: string): Promise<unknown>;
14
22
  }
15
23
  export declare function createKeys(secret: Uint8Array): Keys;
16
24
  /** A fresh one-time ticket: 160 random bits. */
@@ -36,6 +36,8 @@ export function canonicalJson(value) {
36
36
  }
37
37
  return JSON.stringify(value);
38
38
  }
39
+ /** What a sealed value is bound to, so it can never be taken for anything else sealed. */
40
+ const SEAL_CONTEXT = utf8("porthole/files");
39
41
  export function createKeys(secret) {
40
42
  if (secret.byteLength < 32) {
41
43
  throw new TypeError("The server's secret must be at least 32 random bytes");
@@ -44,6 +46,12 @@ export function createKeys(secret) {
44
46
  const labelKey = derive("label");
45
47
  const instanceKey = derive("instance");
46
48
  const signKey = derive("session");
49
+ const sealKey = derive("files");
50
+ let sealing = null;
51
+ const sealingKey = () => (sealing ??= crypto.subtle.importKey("raw", new Uint8Array(sealKey), "AES-GCM", false, [
52
+ "encrypt",
53
+ "decrypt",
54
+ ]));
47
55
  const mac = (key, text) => hmacSha256(key, utf8(text));
48
56
  return {
49
57
  label: (scope) => base32(mac(labelKey, scope).subarray(0, 15)),
@@ -73,6 +81,32 @@ export function createKeys(secret) {
73
81
  return null;
74
82
  }
75
83
  },
84
+ seal: async (value) => {
85
+ const iv = randomBytes(12);
86
+ const sealed = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: new Uint8Array(iv), additionalData: new Uint8Array(SEAL_CONTEXT) }, await sealingKey(), new Uint8Array(utf8(JSON.stringify(value)))));
87
+ const token = new Uint8Array(iv.length + sealed.length);
88
+ token.set(iv);
89
+ token.set(sealed, iv.length);
90
+ return base64url(token);
91
+ },
92
+ unseal: async (token) => {
93
+ const bytes = token.length > 8_192 ? null : fromBase64url(token);
94
+ // 12 bytes of IV and 16 of tag at least.
95
+ if (bytes === null || bytes.length < 29) {
96
+ return null;
97
+ }
98
+ try {
99
+ const opened = await crypto.subtle.decrypt({
100
+ name: "AES-GCM",
101
+ iv: new Uint8Array(bytes.subarray(0, 12)),
102
+ additionalData: new Uint8Array(SEAL_CONTEXT),
103
+ }, await sealingKey(), new Uint8Array(bytes.subarray(12)));
104
+ return JSON.parse(fromUtf8(new Uint8Array(opened)));
105
+ }
106
+ catch {
107
+ return null;
108
+ }
109
+ },
76
110
  };
77
111
  }
78
112
  /** A fresh one-time ticket: 160 random bits. */
@@ -0,0 +1,9 @@
1
+ /**
2
+ * A person's id for one artifact's pages (P087, after the review): what `Grant.user.id` may be
3
+ * where pages shouldn't learn the account id or link one person across artifacts. Stable for the
4
+ * same secret, artifact and person (their `data/users/<id>` stays theirs across visits), a
5
+ * different one on every other artifact, not reversible without the secret. 26 lowercase base32
6
+ * characters: one db path segment. The secret is the host's (at least 32 random bytes); keep it
7
+ * apart from Porthole's server secret.
8
+ */
9
+ export declare function pseudonymFor(secret: Uint8Array, artifact: string, person: string): string;
@@ -0,0 +1,20 @@
1
+ import { hmacSha256, utf8 } from "./crypto.js";
2
+ import { base32 } from "./keys.js";
3
+ /**
4
+ * A person's id for one artifact's pages (P087, after the review): what `Grant.user.id` may be
5
+ * where pages shouldn't learn the account id or link one person across artifacts. Stable for the
6
+ * same secret, artifact and person (their `data/users/<id>` stays theirs across visits), a
7
+ * different one on every other artifact, not reversible without the secret. 26 lowercase base32
8
+ * characters: one db path segment. The secret is the host's (at least 32 random bytes); keep it
9
+ * apart from Porthole's server secret.
10
+ */
11
+ export function pseudonymFor(secret, artifact, person) {
12
+ if (!(secret instanceof Uint8Array) || secret.length < 32) {
13
+ throw new TypeError("pseudonymFor needs a secret of at least 32 random bytes");
14
+ }
15
+ if (artifact === "" || person === "") {
16
+ throw new TypeError("pseudonymFor needs an artifact and a person");
17
+ }
18
+ const mac = hmacSha256(secret, utf8(`porthole/pseudonym\u0000${artifact}\u0000${person}`));
19
+ return base32(mac.slice(0, 16)).slice(0, 26);
20
+ }
@@ -1,7 +1,2 @@
1
1
  import type { PortholeServer, ServerOptions } from "./types.ts";
2
- /**
3
- * Serving for domain, artifact and url modes, and the MCP Apps sandbox proxy (P016, P020): a
4
- * fetch-style handler a host's backend mounts in front of its own routes, plus `issue`, which the
5
- * host's authenticated API calls once it has decided a viewer may see an instance.
6
- */
7
2
  export declare function createServer(options: ServerOptions): PortholeServer;