@botiverse/porthole 0.13.0 → 0.14.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 (68) hide show
  1. package/dist/annotate/types.d.ts +32 -3
  2. package/dist/annotate/types.js +4 -0
  3. package/dist/annotate/validate.js +19 -2
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/compile/policy.d.ts +7 -0
  6. package/dist/compile/policy.js +13 -1
  7. package/dist/config/schema.d.ts +11 -0
  8. package/dist/config/validate.js +19 -0
  9. package/dist/conformance/harness-source.js +1 -1
  10. package/dist/displays/displays.js +3 -1
  11. package/dist/guide/limits.js +1 -1
  12. package/dist/host/create-host.d.ts +2 -0
  13. package/dist/host/create-host.js +73 -3
  14. package/dist/host/pass-on.d.ts +15 -0
  15. package/dist/host/pass-on.js +65 -0
  16. package/dist/host/types.d.ts +22 -0
  17. package/dist/index.d.ts +4 -1
  18. package/dist/index.js +4 -1
  19. package/dist/isolation/types.d.ts +8 -0
  20. package/dist/isolation/types.js +8 -0
  21. package/dist/platform/focus-guard.d.ts +71 -2
  22. package/dist/platform/focus-guard.js +187 -12
  23. package/dist/platform/types.d.ts +8 -1
  24. package/dist/platform/web.js +60 -4
  25. package/dist/presets/presets.d.ts +2 -0
  26. package/dist/presets/presets.js +1 -0
  27. package/dist/server/files.js +19 -3
  28. package/dist/server/index.d.ts +1 -0
  29. package/dist/server/index.js +4 -0
  30. package/dist/server/nested.d.ts +37 -0
  31. package/dist/server/nested.js +70 -0
  32. package/dist/server/server.js +57 -7
  33. package/dist/shell/annotate.d.ts +1 -1
  34. package/dist/shell/annotate.js +157 -7
  35. package/dist/shell/frame.d.ts +45 -0
  36. package/dist/shell/frame.js +250 -0
  37. package/dist/shell/plan.js +2 -1
  38. package/dist/shell/runtime.js +49 -14
  39. package/docs/ADOPTING.md +56 -2
  40. package/docs/ARCHITECTURE.md +23 -0
  41. package/docs/DECISIONS.md +209 -0
  42. package/docs/DESIGN.md +9 -0
  43. package/docs/THREAT_MODEL.md +75 -5
  44. package/package.json +1 -1
  45. package/src/annotate/types.ts +28 -3
  46. package/src/annotate/validate.ts +23 -2
  47. package/src/compile/policy.ts +14 -1
  48. package/src/config/schema.ts +11 -0
  49. package/src/config/validate.ts +23 -0
  50. package/src/displays/displays.ts +3 -1
  51. package/src/guide/limits.ts +1 -1
  52. package/src/host/create-host.ts +76 -4
  53. package/src/host/pass-on.ts +73 -0
  54. package/src/host/types.ts +20 -0
  55. package/src/index.ts +4 -1
  56. package/src/isolation/types.ts +12 -0
  57. package/src/platform/focus-guard.ts +258 -15
  58. package/src/platform/types.ts +8 -1
  59. package/src/platform/web.ts +81 -9
  60. package/src/presets/presets.ts +3 -0
  61. package/src/server/files.ts +19 -3
  62. package/src/server/index.ts +10 -0
  63. package/src/server/nested.ts +86 -0
  64. package/src/server/server.ts +65 -6
  65. package/src/shell/annotate.ts +157 -7
  66. package/src/shell/frame.ts +268 -0
  67. package/src/shell/plan.ts +2 -1
  68. package/src/shell/runtime.ts +49 -14
@@ -85,6 +85,13 @@ export declare function sandboxTokens(config: PortholeConfig): string[];
85
85
  * own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
86
86
  */
87
87
  export declare function servedSandboxDirective(config: PortholeConfig): CspDirective | null;
88
+ /**
89
+ * A nested page's sandbox (P111): its frame's attribute, set by Porthole's shell, and its own CSP
90
+ * header's, so it is an opaque origin in the shell's child frame and on a tab of its own. Scripts
91
+ * only: never `allow-same-origin`, which would give the page its served origin, the shell's, and
92
+ * so the shell's realm (a test holds every sandbox Porthole writes to this).
93
+ */
94
+ export declare const PAGE_SANDBOX_TOKENS: readonly string[];
88
95
  /** A served page's CSP header: the page's directives, then its sandbox (P099). */
89
96
  export declare function servedDocumentCsp(config: PortholeConfig, directives: readonly CspDirective[]): string;
90
97
  /**
@@ -173,6 +173,8 @@ export function sandboxTokens(config) {
173
173
  case "opaque":
174
174
  return ["allow-scripts"];
175
175
  case "domain":
176
+ // Nested (P111), this frame holds Porthole's shell, on the content origin, and the page is
177
+ // the shell's child (`PAGE_SANDBOX_TOKENS`).
176
178
  return ["allow-scripts", "allow-same-origin"];
177
179
  case "external":
178
180
  // The host may add a documented few (popups, modals, downloads), never top navigation.
@@ -190,8 +192,18 @@ export function sandboxTokens(config) {
190
192
  * own documents, and opaque content is never served. Never in a `<meta>` (browsers ignore it there).
191
193
  */
192
194
  export function servedSandboxDirective(config) {
193
- return config.isolation === "domain" ? ["sandbox", ...sandboxTokens(config)] : null;
195
+ if (config.isolation !== "domain") {
196
+ return null;
197
+ }
198
+ return ["sandbox", ...(config.nested === true ? PAGE_SANDBOX_TOKENS : sandboxTokens(config))];
194
199
  }
200
+ /**
201
+ * A nested page's sandbox (P111): its frame's attribute, set by Porthole's shell, and its own CSP
202
+ * header's, so it is an opaque origin in the shell's child frame and on a tab of its own. Scripts
203
+ * only: never `allow-same-origin`, which would give the page its served origin, the shell's, and
204
+ * so the shell's realm (a test holds every sandbox Porthole writes to this).
205
+ */
206
+ export const PAGE_SANDBOX_TOKENS = ["allow-scripts"];
195
207
  /** A served page's CSP header: the page's directives, then its sandbox (P099). */
196
208
  export function servedDocumentCsp(config, directives) {
197
209
  const sandbox = servedSandboxDirective(config);
@@ -238,6 +238,17 @@ export interface PortholeConfig {
238
238
  * `db`). Absent: 0.6's frames, globals and manual, exactly.
239
239
  */
240
240
  readonly runtime?: RuntimeVersion;
241
+ /**
242
+ * Domain isolation, artifact pages (P111): the address the host frames serves Porthole's shell
243
+ * alone, a document of Porthole's own with no content in it, and the page runs in a child frame
244
+ * of the shell's, sandboxed without `allow-same-origin` (an opaque origin), served from the same
245
+ * origin at its files' sealed address. The shell is then a realm the page can't reach, above the
246
+ * page's frame: it relays the page's messages, and tells the host when its own transient
247
+ * activation turns on (a press in the page activates its ancestors only), which is how the host
248
+ * knows the person, not the page, moved the keyboard into the frame or opened a comment. The
249
+ * page has no storage of its own (an in-memory stand-in) and fetches nothing with a cookie.
250
+ */
251
+ readonly nested?: true;
241
252
  }
242
253
  export interface StorageConfig {
243
254
  /**
@@ -270,6 +270,7 @@ export function validateConfig(input, options = {}) {
270
270
  "storage",
271
271
  "errors",
272
272
  "runtime",
273
+ "nested",
273
274
  ], "config");
274
275
  if (!MODES.includes(config.mode)) {
275
276
  fail("config.mode", `must be one of ${MODES.join(", ")}`);
@@ -544,6 +545,24 @@ export function validateConfig(input, options = {}) {
544
545
  fail("config.storage.shared", 'must be a short lowercase noun ("conversation")');
545
546
  }
546
547
  }
548
+ if (config.nested !== undefined) {
549
+ if (config.nested !== true) {
550
+ fail("config.nested", "must be true, or left out");
551
+ }
552
+ if (config.isolation !== "domain" || config.mode !== "artifact") {
553
+ fail("config.nested", "nests artifact pages served on their own origin (domain isolation)");
554
+ }
555
+ // The page's origin is opaque (P111): nothing of the content origin's own is its.
556
+ if (config.storage !== undefined) {
557
+ fail("config.nested", "a nested page keeps no storage: drop config.storage");
558
+ }
559
+ if (capabilities.assets !== undefined) {
560
+ fail("config.nested", "a nested page can't load its asset library (/_blob/) yet: drop assets");
561
+ }
562
+ if (isObject(config.egress) && config.egress.libraries === true) {
563
+ fail("config.nested", "a nested page can't load Porthole's libraries from its origin yet");
564
+ }
565
+ }
547
566
  if (config.errors !== undefined) {
548
567
  if (config.errors !== "agent" && config.errors !== "host" && config.errors !== "none") {
549
568
  fail("config.errors", 'must be "agent", "host" or "none"');