@botiverse/porthole 0.14.7 → 0.14.8

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 (49) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/dist/check/files.js +2 -0
  3. package/dist/check/lint.js +82 -3
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/compile/policy.d.ts +17 -6
  6. package/dist/compile/policy.js +22 -7
  7. package/dist/config/schema.d.ts +13 -0
  8. package/dist/config/validate.js +15 -0
  9. package/dist/conformance/harness-source.js +1 -1
  10. package/dist/conformance/kit.d.ts +5 -0
  11. package/dist/conformance/kit.js +21 -0
  12. package/dist/conformance/limits.js +10 -5
  13. package/dist/conformance/probes.js +139 -28
  14. package/dist/conformance/served.js +25 -4
  15. package/dist/guide/limits.js +8 -1
  16. package/dist/host/create-host.js +35 -4
  17. package/dist/index.d.ts +1 -1
  18. package/dist/index.js +1 -1
  19. package/dist/presets/presets.d.ts +6 -0
  20. package/dist/presets/presets.js +6 -0
  21. package/dist/server/files.js +4 -3
  22. package/dist/server/server.js +4 -1
  23. package/dist/shell/plan.d.ts +5 -0
  24. package/dist/shell/plan.js +2 -0
  25. package/dist/shell/runtime.d.ts +30 -1
  26. package/dist/shell/runtime.js +785 -104
  27. package/docs/ADOPTING.md +20 -0
  28. package/docs/DECISIONS.md +294 -0
  29. package/docs/DESIGN.md +7 -4
  30. package/docs/THREAT_MODEL.md +30 -5
  31. package/docs/insertion-entry-points.md +95 -0
  32. package/package.json +1 -1
  33. package/src/check/files.ts +2 -0
  34. package/src/check/lint.ts +97 -8
  35. package/src/compile/policy.ts +23 -6
  36. package/src/config/schema.ts +13 -0
  37. package/src/config/validate.ts +16 -0
  38. package/src/conformance/kit.ts +22 -0
  39. package/src/conformance/limits.ts +10 -5
  40. package/src/conformance/probes.ts +149 -28
  41. package/src/conformance/served.ts +24 -4
  42. package/src/guide/limits.ts +9 -1
  43. package/src/host/create-host.ts +37 -4
  44. package/src/index.ts +1 -0
  45. package/src/presets/presets.ts +15 -0
  46. package/src/server/files.ts +8 -2
  47. package/src/server/server.ts +4 -1
  48. package/src/shell/plan.ts +7 -0
  49. package/src/shell/runtime.ts +788 -104
@@ -41,13 +41,24 @@ export declare function frameCspDirectives(config: PortholeConfig): CspDirective
41
41
  /** The directives a page of a file set loads its own files under (P082): everything that loads. */
42
42
  export declare const FILE_SET_DIRECTIVES: readonly ["script-src", "style-src", "font-src", "img-src", "media-src", "connect-src", "worker-src"];
43
43
  /**
44
- * A served page's CSP when it comes with files (P082): the frame's, with its version's own files
45
- * opened for each kind that loads (`FILE_SET_DIRECTIVES`), by `source`, the files' path on the
46
- * content origin (`https://a-x.example-usercontent.com/v/3/`). Never `'self'`: the origin's other
47
- * paths (other versions, Porthole's own) stay closed, and frames, plugins, forms and `<base>` stay
48
- * `'none'`. Opaque frames have no files, and keep P022's rule whole.
44
+ * The directives a page of a file set opens to its version's own files under `config` (P082):
45
+ * `FILE_SET_DIRECTIVES`, and `frame-src` too where the config lets content frame its own files
46
+ * (`nestedFrames: "own"`, P128). Never `child-src`: every engine Porthole supports reads frames
47
+ * from `frame-src` (P038), and `child-src` is only its fallback (and workers', which have
48
+ * `worker-src`).
49
49
  */
50
- export declare function fileSetCspDirectives(directives: readonly CspDirective[], source: string): CspDirective[];
50
+ export declare function fileSetDirectives(config: PortholeConfig): readonly string[];
51
+ /**
52
+ * A served page's CSP when it comes with files (P082): the frame's, with its version's own files
53
+ * opened for each kind that loads (`opened`: `FILE_SET_DIRECTIVES` by default, a server's
54
+ * `fileSetDirectives(config)`), by `source`, the files' path on the content origin
55
+ * (`https://a-x.example-usercontent.com/v/3/`).
56
+ * Never `'self'`: the origin's other paths (other versions, Porthole's own) stay closed, and
57
+ * plugins, forms and `<base>` stay `'none'`, frames too unless the config opts into its own
58
+ * (P128: `frame-src` its version's path, never another origin). Opaque frames have no files, and
59
+ * keep P022's rule whole.
60
+ */
61
+ export declare function fileSetCspDirectives(directives: readonly CspDirective[], source: string, opened?: readonly string[]): CspDirective[];
51
62
  /**
52
63
  * The directives a page opens its artifact's asset library to (P089), at `/_blob/` on its own
53
64
  * origin: what loads without running, always; what runs (scripts, styles) only where uploads are
@@ -108,17 +108,32 @@ export const FILE_SET_DIRECTIVES = [
108
108
  "connect-src",
109
109
  "worker-src",
110
110
  ];
111
+ /**
112
+ * The directives a page of a file set opens to its version's own files under `config` (P082):
113
+ * `FILE_SET_DIRECTIVES`, and `frame-src` too where the config lets content frame its own files
114
+ * (`nestedFrames: "own"`, P128). Never `child-src`: every engine Porthole supports reads frames
115
+ * from `frame-src` (P038), and `child-src` is only its fallback (and workers', which have
116
+ * `worker-src`).
117
+ */
118
+ export function fileSetDirectives(config) {
119
+ return config.nestedFrames === "own"
120
+ ? [...FILE_SET_DIRECTIVES, "frame-src"]
121
+ : FILE_SET_DIRECTIVES;
122
+ }
111
123
  /**
112
124
  * A served page's CSP when it comes with files (P082): the frame's, with its version's own files
113
- * opened for each kind that loads (`FILE_SET_DIRECTIVES`), by `source`, the files' path on the
114
- * content origin (`https://a-x.example-usercontent.com/v/3/`). Never `'self'`: the origin's other
115
- * paths (other versions, Porthole's own) stay closed, and frames, plugins, forms and `<base>` stay
116
- * `'none'`. Opaque frames have no files, and keep P022's rule whole.
125
+ * opened for each kind that loads (`opened`: `FILE_SET_DIRECTIVES` by default, a server's
126
+ * `fileSetDirectives(config)`), by `source`, the files' path on the content origin
127
+ * (`https://a-x.example-usercontent.com/v/3/`).
128
+ * Never `'self'`: the origin's other paths (other versions, Porthole's own) stay closed, and
129
+ * plugins, forms and `<base>` stay `'none'`, frames too unless the config opts into its own
130
+ * (P128: `frame-src` its version's path, never another origin). Opaque frames have no files, and
131
+ * keep P022's rule whole.
117
132
  */
118
- export function fileSetCspDirectives(directives, source) {
119
- const opened = new Set(FILE_SET_DIRECTIVES);
133
+ export function fileSetCspDirectives(directives, source, opened = FILE_SET_DIRECTIVES) {
134
+ const open = new Set(opened);
120
135
  return directives.map(([name, ...sources]) => {
121
- if (!opened.has(name)) {
136
+ if (!open.has(name)) {
122
137
  return [name, ...sources];
123
138
  }
124
139
  const kept = sources.filter((each) => each !== "'none'");
@@ -249,6 +249,19 @@ export interface PortholeConfig {
249
249
  * page has no storage of its own (an in-memory stand-in) and fetches nothing with a cookie.
250
250
  */
251
251
  readonly nested?: true;
252
+ /**
253
+ * Which nested frames content may make (P128). `none` (default, and absent): the shell removes
254
+ * every frame-like element content adds, and the CSP's `frame-src` is `'none'`. `own`: an
255
+ * `<iframe>` of one of the page's own files (its `src` under its version's own address, P082)
256
+ * and a `srcdoc` one load and run; frames of other sites, `<frame>`, `<object>` and `<embed>`
257
+ * are still removed, and a served file set's `frame-src` opens its version's own path only.
258
+ * A weakening, opted into: a child frame is a realm of its own, where the shell's WebRTC
259
+ * removal, clipboard guards and navigation cancel never ran (a page of the set framed there has
260
+ * its own shell; a `srcdoc` frame, or the `about:blank` a new frame starts as, has none), so
261
+ * content reaches WebRTC and the clipboard's events there. Not for url mode, a live widget
262
+ * (no network of its own, P079) or a nested page (P111).
263
+ */
264
+ readonly nestedFrames?: "none" | "own";
252
265
  }
253
266
  export interface StorageConfig {
254
267
  /**
@@ -271,6 +271,7 @@ export function validateConfig(input, options = {}) {
271
271
  "errors",
272
272
  "runtime",
273
273
  "nested",
274
+ "nestedFrames",
274
275
  ], "config");
275
276
  if (!MODES.includes(config.mode)) {
276
277
  fail("config.mode", `must be one of ${MODES.join(", ")}`);
@@ -563,6 +564,20 @@ export function validateConfig(input, options = {}) {
563
564
  fail("config.nested", "a nested page can't load Porthole's libraries from its origin yet");
564
565
  }
565
566
  }
567
+ // A page's own nested frames (P128): opted into, never a default.
568
+ if (config.nestedFrames !== undefined) {
569
+ if (config.nestedFrames !== "none" && config.nestedFrames !== "own") {
570
+ fail("config.nestedFrames", 'must be "none" or "own", or left out');
571
+ }
572
+ if (config.nestedFrames === "own" && config.mode === "url") {
573
+ fail("config.nestedFrames", "url mode has no shell: its app's frames are its own");
574
+ }
575
+ // A nested page's frames have an opaque ancestor, which no frame-ancestors source matches:
576
+ // none of its own files would load in one. Not measured yet.
577
+ if (config.nestedFrames === "own" && config.nested === true) {
578
+ fail("config.nestedFrames", 'a nested page (P111) has no "own" frames yet: leave it out');
579
+ }
580
+ }
566
581
  if (config.errors !== undefined) {
567
582
  if (config.errors !== "agent" && config.errors !== "host" && config.errors !== "none") {
568
583
  fail("config.errors", 'must be "agent", "host" or "none"');