@botiverse/porthole 0.5.1 → 0.6.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 (73) hide show
  1. package/README.md +25 -0
  2. package/dist/bridge/bridge.js +8 -5
  3. package/dist/bridge/navigation.d.ts +1 -6
  4. package/dist/bridge/navigation.js +11 -0
  5. package/dist/check/check.d.ts +12 -3
  6. package/dist/check/check.js +54 -8
  7. package/dist/check/files.d.ts +26 -0
  8. package/dist/check/files.js +307 -0
  9. package/dist/check/lint.js +27 -10
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/tools.d.ts +23 -0
  12. package/dist/check/tools.js +25 -0
  13. package/dist/compile/policy.d.ts +15 -0
  14. package/dist/compile/policy.js +32 -0
  15. package/dist/config/schema.d.ts +8 -0
  16. package/dist/config/validate.js +8 -1
  17. package/dist/conformance/harness-source.js +1 -1
  18. package/dist/files/paths.d.ts +99 -0
  19. package/dist/files/paths.js +263 -0
  20. package/dist/files/types.d.ts +24 -0
  21. package/dist/files/types.js +83 -0
  22. package/dist/guide/guide.js +11 -1
  23. package/dist/host/create-host.js +21 -0
  24. package/dist/index.d.ts +6 -3
  25. package/dist/index.js +8 -3
  26. package/dist/protocol/adapter.d.ts +4 -0
  27. package/dist/protocol/mcp-apps.d.ts +6 -0
  28. package/dist/protocol/mcp-apps.js +6 -0
  29. package/dist/protocol/shell-adapter.js +5 -1
  30. package/dist/server/files.d.ts +44 -0
  31. package/dist/server/files.js +244 -0
  32. package/dist/server/host.d.ts +38 -1
  33. package/dist/server/host.js +37 -2
  34. package/dist/server/index.d.ts +4 -2
  35. package/dist/server/index.js +4 -1
  36. package/dist/server/keys.d.ts +8 -0
  37. package/dist/server/keys.js +34 -0
  38. package/dist/server/server.js +287 -22
  39. package/dist/server/types.d.ts +49 -5
  40. package/dist/shell/document.d.ts +19 -0
  41. package/dist/shell/document.js +30 -0
  42. package/dist/shell/runtime.d.ts +2 -1
  43. package/dist/shell/runtime.js +85 -4
  44. package/docs/ADOPTING.md +56 -4
  45. package/docs/ARCHITECTURE.md +13 -3
  46. package/docs/DECISIONS.md +304 -4
  47. package/docs/DESIGN.md +31 -3
  48. package/package.json +1 -1
  49. package/src/bridge/bridge.ts +8 -5
  50. package/src/bridge/navigation.ts +12 -0
  51. package/src/check/check.ts +92 -14
  52. package/src/check/files.ts +384 -0
  53. package/src/check/lint.ts +29 -10
  54. package/src/check/tools.ts +50 -0
  55. package/src/compile/policy.ts +38 -0
  56. package/src/config/schema.ts +8 -0
  57. package/src/config/validate.ts +8 -1
  58. package/src/files/paths.ts +323 -0
  59. package/src/files/types.ts +101 -0
  60. package/src/guide/guide.ts +20 -0
  61. package/src/host/create-host.ts +21 -0
  62. package/src/index.ts +32 -0
  63. package/src/protocol/adapter.ts +3 -1
  64. package/src/protocol/mcp-apps.ts +7 -0
  65. package/src/protocol/shell-adapter.ts +5 -0
  66. package/src/server/files.ts +312 -0
  67. package/src/server/host.ts +72 -3
  68. package/src/server/index.ts +19 -0
  69. package/src/server/keys.ts +53 -0
  70. package/src/server/server.ts +353 -24
  71. package/src/server/types.ts +56 -4
  72. package/src/shell/document.ts +53 -0
  73. package/src/shell/runtime.ts +85 -4
@@ -1,5 +1,6 @@
1
1
  import type { PortholeConfig } from "../config/schema.ts";
2
2
  import { type Finding } from "./lint.ts";
3
+ import { type FileContents, type FileFinding } from "./files.ts";
3
4
  /**
4
5
  * The agent's tools, as a tool list names them (P073): a name, a description and a JSON Schema
5
6
  * for each, from the config, so a host lists them in one line (an MCP server's `tools/list`, an
@@ -54,6 +55,28 @@ export type AdmitResult = {
54
55
  export declare function admitContent(config: PortholeConfig, content: string, options?: {
55
56
  readonly refuseOn?: "error" | "never";
56
57
  }): AdmitResult;
58
+ export type AdmitFilesResult = {
59
+ readonly ok: true;
60
+ /** Warnings (and errors, with `refuseOn: "never"`), for the tool's answer. */
61
+ readonly findings: readonly FileFinding[];
62
+ /** One line for the agent, or null when there's nothing to say. */
63
+ readonly note: string | null;
64
+ } | {
65
+ readonly ok: false;
66
+ readonly findings: readonly FileFinding[];
67
+ /** What to tell the agent: what to change, and to call the tool again. */
68
+ readonly refusal: string;
69
+ };
70
+ /**
71
+ * A publish tool's check before it takes a page with files (P081): refuses only what certainly
72
+ * fails (a path or limit the server won't take, no entry, a page `admitContent` would refuse, a
73
+ * page's reference that starts with /); the rest, references to files that aren't in the set
74
+ * among them, are warnings. `refuseOn: "never"` refuses nothing.
75
+ */
76
+ export declare function admitFiles(config: PortholeConfig, files: FileContents, options?: {
77
+ readonly entry?: string;
78
+ readonly refuseOn?: "error" | "never";
79
+ }): AdmitFilesResult;
57
80
  /**
58
81
  * What to tell the agent when its manual changes (a display kind flipped between served and
59
82
  * opaque, P073): the lines that are new, or null when the manual reads the same.
@@ -1,6 +1,7 @@
1
1
  import { BUILT_IN_TOPICS } from "../config/validate.js";
2
2
  import { generateGuide, generateToolDescription } from "../guide/guide.js";
3
3
  import { fragmentOf, lintContent } from "./lint.js";
4
+ import { lintFiles, whereOf } from "./files.js";
4
5
  const noun = (config) => config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget";
5
6
  /** The show tool's name: the config's `guide.toolName`, else `show_<noun>`. */
6
7
  const showName = (config) => config.guide.toolName ?? `show_${noun(config)}`;
@@ -124,6 +125,30 @@ export function admitContent(config, content, options = {}) {
124
125
  : `Shown. Fix these next time:\n${findings.map((each) => `- ${said(each)}`).join("\n")}`,
125
126
  };
126
127
  }
128
+ /**
129
+ * A publish tool's check before it takes a page with files (P081): refuses only what certainly
130
+ * fails (a path or limit the server won't take, no entry, a page `admitContent` would refuse, a
131
+ * page's reference that starts with /); the rest, references to files that aren't in the set
132
+ * among them, are warnings. `refuseOn: "never"` refuses nothing.
133
+ */
134
+ export function admitFiles(config, files, options = {}) {
135
+ const findings = lintFiles(config, files, options.entry === undefined ? {} : { entry: options.entry });
136
+ const errors = findings.filter((each) => each.severity === "error");
137
+ if (errors.length > 0 && (options.refuseOn ?? "error") === "error") {
138
+ return {
139
+ ok: false,
140
+ findings,
141
+ refusal: `Not published. Change this, then publish again:\n${errors.map((each) => `- ${whereOf(each)}${each.message}`).join("\n")}`,
142
+ };
143
+ }
144
+ return {
145
+ ok: true,
146
+ findings,
147
+ note: findings.length === 0
148
+ ? null
149
+ : `Published. Fix these next time:\n${findings.map((each) => `- ${whereOf(each)}${each.message}`).join("\n")}`,
150
+ };
151
+ }
127
152
  /**
128
153
  * What to tell the agent when its manual changes (a display kind flipped between served and
129
154
  * opaque, P073): the lines that are new, or null when the manual reads the same.
@@ -31,6 +31,21 @@ export declare function librarySources(config: PortholeConfig): string[];
31
31
  * whose app serves its own policy.
32
32
  */
33
33
  export declare function frameCspDirectives(config: PortholeConfig): CspDirective[];
34
+ /** The directives a page of a file set loads its own files under (P082): everything that loads. */
35
+ export declare const FILE_SET_DIRECTIVES: readonly ["script-src", "style-src", "font-src", "img-src", "media-src", "connect-src", "worker-src"];
36
+ /**
37
+ * A served page's CSP when it comes with files (P082): the frame's, with its version's own files
38
+ * opened for each kind that loads (`FILE_SET_DIRECTIVES`), by `source`, the files' path on the
39
+ * content origin (`https://a-x.example-usercontent.com/v/3/`). Never `'self'`: the origin's other
40
+ * paths (other versions, Porthole's own) stay closed, and frames, plugins, forms and `<base>` stay
41
+ * `'none'`. Opaque frames have no files, and keep P022's rule whole.
42
+ */
43
+ export declare function fileSetCspDirectives(directives: readonly CspDirective[], source: string): CspDirective[];
44
+ /**
45
+ * The CSP of a file of a set that is neither a page nor a script (P081): nothing loads from it,
46
+ * and opened as a document (an SVG, an XML file) it runs nothing, on an opaque origin.
47
+ */
48
+ export declare const INERT_FILE_CSP = "default-src 'none'; sandbox";
34
49
  export declare function serializeCsp(directives: readonly CspDirective[]): string;
35
50
  /**
36
51
  * The frame's `sandbox` tokens. Opaque: scripts only, so the frame is an opaque origin and gets
@@ -76,6 +76,38 @@ export function frameCspDirectives(config) {
76
76
  ["webrtc", "'block'"],
77
77
  ];
78
78
  }
79
+ /** The directives a page of a file set loads its own files under (P082): everything that loads. */
80
+ export const FILE_SET_DIRECTIVES = [
81
+ "script-src",
82
+ "style-src",
83
+ "font-src",
84
+ "img-src",
85
+ "media-src",
86
+ "connect-src",
87
+ "worker-src",
88
+ ];
89
+ /**
90
+ * A served page's CSP when it comes with files (P082): the frame's, with its version's own files
91
+ * opened for each kind that loads (`FILE_SET_DIRECTIVES`), by `source`, the files' path on the
92
+ * content origin (`https://a-x.example-usercontent.com/v/3/`). Never `'self'`: the origin's other
93
+ * paths (other versions, Porthole's own) stay closed, and frames, plugins, forms and `<base>` stay
94
+ * `'none'`. Opaque frames have no files, and keep P022's rule whole.
95
+ */
96
+ export function fileSetCspDirectives(directives, source) {
97
+ const opened = new Set(FILE_SET_DIRECTIVES);
98
+ return directives.map(([name, ...sources]) => {
99
+ if (!opened.has(name)) {
100
+ return [name, ...sources];
101
+ }
102
+ const kept = sources.filter((each) => each !== "'none'");
103
+ return [name, ...kept, source];
104
+ });
105
+ }
106
+ /**
107
+ * The CSP of a file of a set that is neither a page nor a script (P081): nothing loads from it,
108
+ * and opened as a document (an SVG, an XML file) it runs nothing, on an opaque origin.
109
+ */
110
+ export const INERT_FILE_CSP = "default-src 'none'; sandbox";
79
111
  export function serializeCsp(directives) {
80
112
  return directives.map((directive) => directive.join(" ")).join("; ");
81
113
  }
@@ -113,6 +113,14 @@ export interface Limits {
113
113
  * when absent.
114
114
  */
115
115
  readonly loadTimeoutMs?: number;
116
+ /**
117
+ * A served page's files (P081): the most a version holds (default 1000), the largest one,
118
+ * bytes (default 25 MiB), and all of them together, bytes (default 100 MiB: a host sets its
119
+ * own). The manual states them; `checkFileSet` and `lintFiles` hold a version to them.
120
+ */
121
+ readonly maxFiles?: number;
122
+ readonly maxFileBytes?: number;
123
+ readonly maxVersionBytes?: number;
116
124
  }
117
125
  /**
118
126
  * Sandbox tokens a url-mode frame may add to its baseline, by the host's choice (P037): a
@@ -366,13 +366,20 @@ export function validateConfig(input) {
366
366
  "maxPromptChars",
367
367
  "maxErrorReports",
368
368
  ];
369
- only(limits, [...limitNames, "loadTimeoutMs"], "config.limits");
369
+ const fileLimitNames = ["maxFiles", "maxFileBytes", "maxVersionBytes"];
370
+ only(limits, [...limitNames, "loadTimeoutMs", ...fileLimitNames], "config.limits");
370
371
  for (const name of limitNames) {
371
372
  positive(limits[name], `config.limits.${name}`);
372
373
  }
373
374
  if (limits.loadTimeoutMs !== undefined) {
374
375
  positive(limits.loadTimeoutMs, "config.limits.loadTimeoutMs", 600_000);
375
376
  }
377
+ // A served page's files (P081): optional, with fileLimits' defaults.
378
+ for (const name of fileLimitNames) {
379
+ if (limits[name] !== undefined) {
380
+ positive(limits[name], `config.limits.${name}`);
381
+ }
382
+ }
376
383
  if (limits.minHeightPx > limits.maxHeightPx) {
377
384
  fail("config.limits.minHeightPx", "must not exceed maxHeightPx");
378
385
  }