@botiverse/porthole 0.14.7 → 0.14.9

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 (87) hide show
  1. package/CHANGELOG.md +74 -0
  2. package/dist/bridge/bridge.d.ts +6 -0
  3. package/dist/bridge/bridge.js +5 -0
  4. package/dist/check/files.js +2 -0
  5. package/dist/check/lint.js +82 -3
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/compile/policy.d.ts +17 -6
  8. package/dist/compile/policy.js +22 -7
  9. package/dist/config/capabilities.d.ts +16 -2
  10. package/dist/config/capabilities.js +8 -0
  11. package/dist/config/schema.d.ts +13 -0
  12. package/dist/config/validate.js +15 -0
  13. package/dist/conformance/harness-source.js +1 -1
  14. package/dist/conformance/kit.d.ts +5 -0
  15. package/dist/conformance/kit.js +21 -0
  16. package/dist/conformance/limits.js +10 -5
  17. package/dist/conformance/probes.js +139 -28
  18. package/dist/conformance/served.js +25 -4
  19. package/dist/find/types.d.ts +83 -0
  20. package/dist/find/types.js +29 -0
  21. package/dist/find/validate.d.ts +17 -0
  22. package/dist/find/validate.js +82 -0
  23. package/dist/guide/guide.js +2 -1
  24. package/dist/guide/limits.js +8 -1
  25. package/dist/host/create-host.js +249 -4
  26. package/dist/host/pass-on.js +3 -2
  27. package/dist/host/types.d.ts +51 -0
  28. package/dist/index.d.ts +4 -2
  29. package/dist/index.js +4 -1
  30. package/dist/presets/presets.d.ts +6 -0
  31. package/dist/presets/presets.js +6 -0
  32. package/dist/react/frame.d.ts +43 -0
  33. package/dist/react/frame.js +107 -3
  34. package/dist/react/view.js +2 -0
  35. package/dist/runtime/contract.d.ts +1 -1
  36. package/dist/runtime/contract.js +1 -1
  37. package/dist/server/files.js +4 -3
  38. package/dist/server/server.js +4 -1
  39. package/dist/shell/annotate.js +2 -95
  40. package/dist/shell/document.d.ts +3 -3
  41. package/dist/shell/document.js +5 -3
  42. package/dist/shell/find.d.ts +82 -0
  43. package/dist/shell/find.js +725 -0
  44. package/dist/shell/plan.d.ts +5 -0
  45. package/dist/shell/plan.js +2 -0
  46. package/dist/shell/runtime.d.ts +30 -1
  47. package/dist/shell/runtime.js +789 -105
  48. package/dist/shell/text.d.ts +17 -0
  49. package/dist/shell/text.js +140 -0
  50. package/docs/ADOPTING.md +103 -0
  51. package/docs/ARCHITECTURE.md +10 -3
  52. package/docs/DECISIONS.md +513 -1
  53. package/docs/DESIGN.md +40 -4
  54. package/docs/THREAT_MODEL.md +75 -6
  55. package/docs/insertion-entry-points.md +112 -0
  56. package/package.json +1 -1
  57. package/src/bridge/bridge.ts +7 -0
  58. package/src/check/files.ts +2 -0
  59. package/src/check/lint.ts +97 -8
  60. package/src/compile/policy.ts +23 -6
  61. package/src/config/capabilities.ts +13 -1
  62. package/src/config/schema.ts +13 -0
  63. package/src/config/validate.ts +16 -0
  64. package/src/conformance/kit.ts +22 -0
  65. package/src/conformance/limits.ts +10 -5
  66. package/src/conformance/probes.ts +149 -28
  67. package/src/conformance/served.ts +24 -4
  68. package/src/find/types.ts +86 -0
  69. package/src/find/validate.ts +101 -0
  70. package/src/guide/guide.ts +3 -1
  71. package/src/guide/limits.ts +9 -1
  72. package/src/host/create-host.ts +267 -4
  73. package/src/host/pass-on.ts +3 -2
  74. package/src/host/types.ts +52 -0
  75. package/src/index.ts +13 -0
  76. package/src/presets/presets.ts +15 -0
  77. package/src/react/frame.tsx +160 -1
  78. package/src/react/view.tsx +3 -0
  79. package/src/runtime/contract.ts +1 -1
  80. package/src/server/files.ts +8 -2
  81. package/src/server/server.ts +4 -1
  82. package/src/shell/annotate.ts +3 -95
  83. package/src/shell/document.ts +5 -3
  84. package/src/shell/find.ts +731 -0
  85. package/src/shell/plan.ts +7 -0
  86. package/src/shell/runtime.ts +792 -105
  87. package/src/shell/text.ts +140 -0
@@ -51,5 +51,10 @@ export interface ShellPlan {
51
51
  /** The most text `copyText` carries. */
52
52
  readonly maxCopyChars: number;
53
53
  readonly protocolVersion: string;
54
+ /**
55
+ * `own` where the config lets content frame its own files and `srcdoc` (P128): the shell keeps
56
+ * those iframes and removes every other frame-like element. Absent: it removes them all.
57
+ */
58
+ readonly nestedFrames?: "own";
54
59
  }
55
60
  export declare function shellPlan(config: PortholeConfig): ShellPlan | null;
@@ -44,5 +44,7 @@ export function shellPlan(config) {
44
44
  maxPromptChars: config.limits.maxPromptChars,
45
45
  maxCopyChars: MAX_COPY_CHARS,
46
46
  protocolVersion: MCP_APPS_PROTOCOL_VERSION,
47
+ // Only where opted into (P128): every other plan is the same as before it.
48
+ ...(config.nestedFrames === "own" ? { nestedFrames: "own" } : {}),
47
49
  };
48
50
  }
@@ -4,6 +4,31 @@
4
4
  * more comes. Parsed as it is, a cut right after `<` or `</` draws them as text.
5
5
  */
6
6
  export declare const HELD_BACK: string;
7
+ /**
8
+ * Which `<iframe>` the shell keeps under `nestedFrames: "own"` (P128), spliced into the runtime:
9
+ * one with a `srcdoc` attribute (which wins over any `src`), or one whose `src`, resolved by the
10
+ * platform's own URL parser (`resolve`, which normalizes `..`, `%2e` and backslashes), is under the
11
+ * version's own files' address (`filesBase`, ending in `/`). Nothing else: no `src` or a blank one
12
+ * (`about:blank`), another path of the origin, another origin, `data:`, `blob:`, `javascript:`.
13
+ * Only comparisons and indexing, which content can't replace (no String.prototype method).
14
+ */
15
+ export declare const OWN_FRAME: string;
16
+ /**
17
+ * Which values a guard forwards as they are (P129, P130), spliced into the runtime: those that are
18
+ * their own single reading. A string, a number, a boolean, a bigint, `null`, and a genuine
19
+ * `undefined` (`value === undefined`: an object whose `typeof` is "undefined" isn't one). Nothing
20
+ * here can throw or run content's code (`typeof` and `===` read no property).
21
+ */
22
+ export declare const PASSES_AS_IS: string;
23
+ /**
24
+ * A name or value a guard inspects and then forwards, pinned to one reading (P129, P130), spliced
25
+ * into the runtime as `ONCE(passesAsIs, toText)`: a value `passesAsIs` lets through goes on
26
+ * unchanged; anything else is turned into its string once, by `toText` (the platform's own
27
+ * `String`, kept before content runs), and that string is what is both checked and forwarded. A
28
+ * symbol, a conversion that throws, or one that doesn't give a string is refused (the guard throws
29
+ * and nothing is forwarded): fail closed.
30
+ */
31
+ export declare const ONCE: string;
7
32
  /**
8
33
  * The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
9
34
  * no imports and no build step, so every engine (a browser frame now, a native web view later)
@@ -17,7 +42,11 @@ export declare const HELD_BACK: string;
17
42
  * 3. removes every frame-like element content adds, wherever it adds it (the document, any shadow
18
43
  * root), since a nested frame runs in a fresh realm where step 2 never happened (and not every
19
44
  * engine enforces `frame-src 'none'` for `srcdoc`/`about:blank` children); and the resource
20
- * hints and refreshes a CSP doesn't govern;
45
+ * hints and refreshes a CSP doesn't govern. Where the config opts in (`nestedFrames: "own"`,
46
+ * P128), an `<iframe>` of the page's own files or with `srcdoc` is kept (`OWN_FRAME`), and
47
+ * one that is kept leaves the document before a change would make it any other; in such a
48
+ * child realm steps 1, 2, 5 and 6 never ran (a page of the set has its own shell there), which
49
+ * the host accepted by opting in;
21
50
  * 4. closes the parser entry points that could build a shadow root step 3 can't see (declarative
22
51
  * shadow DOM through `setHTMLUnsafe`, `parseHTMLUnsafe`, `document.write`);
23
52
  * 5. keeps content off the clipboard: the async Clipboard API refuses, `execCommand` won't copy or