@botiverse/porthole 0.14.4 → 0.14.6

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 (78) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/dist/check/page-source.js +1 -1
  3. package/dist/check/page.js +5 -1
  4. package/dist/compile/policy.d.ts +6 -0
  5. package/dist/compile/policy.js +6 -0
  6. package/dist/conformance/entry.d.ts +25 -6
  7. package/dist/conformance/entry.js +69 -18
  8. package/dist/conformance/harness/page.d.ts +12 -0
  9. package/dist/conformance/harness/page.js +95 -51
  10. package/dist/conformance/harness-source.js +1 -1
  11. package/dist/conformance/host-kit.js +39 -13
  12. package/dist/conformance/served.js +140 -0
  13. package/dist/files/paths.d.ts +2 -2
  14. package/dist/files/paths.js +12 -2
  15. package/dist/host/client.d.ts +8 -0
  16. package/dist/host/client.js +47 -17
  17. package/dist/host/create-host.d.ts +10 -0
  18. package/dist/host/create-host.js +126 -10
  19. package/dist/host/door.d.ts +41 -0
  20. package/dist/host/door.js +55 -0
  21. package/dist/host/locate.js +2 -0
  22. package/dist/host/locator.d.ts +55 -3
  23. package/dist/host/locator.js +152 -42
  24. package/dist/host/outcome.d.ts +58 -1
  25. package/dist/host/outcome.js +74 -6
  26. package/dist/host/types.d.ts +20 -4
  27. package/dist/isolation/served.d.ts +1 -1
  28. package/dist/isolation/served.js +35 -0
  29. package/dist/isolation/types.d.ts +20 -2
  30. package/dist/isolation/types.js +2 -0
  31. package/dist/platform/types.d.ts +22 -0
  32. package/dist/platform/web.js +55 -12
  33. package/dist/react/frame.d.ts +2 -1
  34. package/dist/react/view.d.ts +13 -0
  35. package/dist/react/view.js +101 -2
  36. package/dist/server/files.d.ts +11 -0
  37. package/dist/server/files.js +26 -4
  38. package/dist/server/host.js +106 -28
  39. package/dist/server/index.d.ts +2 -1
  40. package/dist/server/index.js +6 -1
  41. package/dist/server/pages.d.ts +32 -0
  42. package/dist/server/pages.js +82 -6
  43. package/dist/server/server.js +140 -11
  44. package/dist/server/types.d.ts +15 -1
  45. package/dist/transport/post-message.d.ts +1 -9
  46. package/dist/transport/post-message.js +2 -8
  47. package/docs/ADOPTING.md +58 -0
  48. package/docs/DECISIONS.md +290 -0
  49. package/docs/DESIGN.md +24 -16
  50. package/docs/THREAT_MODEL.md +98 -3
  51. package/package.json +1 -1
  52. package/src/check/page.ts +6 -1
  53. package/src/compile/policy.ts +7 -0
  54. package/src/conformance/entry.ts +129 -24
  55. package/src/conformance/harness/page.ts +112 -49
  56. package/src/conformance/host-kit.ts +53 -16
  57. package/src/conformance/served.ts +175 -0
  58. package/src/files/paths.ts +11 -2
  59. package/src/host/client.ts +59 -22
  60. package/src/host/create-host.ts +146 -18
  61. package/src/host/door.ts +97 -0
  62. package/src/host/locate.ts +2 -0
  63. package/src/host/locator.ts +208 -57
  64. package/src/host/outcome.ts +88 -7
  65. package/src/host/types.ts +20 -4
  66. package/src/isolation/served.ts +40 -1
  67. package/src/isolation/types.ts +19 -2
  68. package/src/platform/types.ts +21 -0
  69. package/src/platform/web.ts +55 -20
  70. package/src/react/frame.tsx +2 -1
  71. package/src/react/view.tsx +149 -2
  72. package/src/server/files.ts +37 -5
  73. package/src/server/host.ts +131 -46
  74. package/src/server/index.ts +6 -1
  75. package/src/server/pages.ts +101 -6
  76. package/src/server/server.ts +186 -19
  77. package/src/server/types.ts +16 -1
  78. package/src/transport/post-message.ts +1 -9
@@ -44,6 +44,9 @@ const NOBODY = {
44
44
  const surface = webPlatform.createSurface(container, spec);
45
45
  return { ...surface, userActivation: () => false };
46
46
  },
47
+ // A served display's door (P125), as the web platform makes it: a platform without doors frames
48
+ // no served display that isn't nested.
49
+ createDoor: (container, spec) => webPlatform.createDoor(container, spec),
47
50
  };
48
51
  /** A handler for each host function the config declares: it notes the call and answers no. */
49
52
  function declining(capabilities, calls) {
@@ -61,7 +64,8 @@ function declining(capabilities, calls) {
61
64
  }
62
65
  const runs = new Map();
63
66
  let next = 0;
64
- const frameOf = (run) => run.box.querySelector("iframe");
67
+ /** A run's frame: the display's own, never its door (P125), which is gone once it said its word. */
68
+ const frameOf = (run) => run.box.querySelector("iframe:not([data-porthole-door])");
65
69
  addEventListener("message", (event) => {
66
70
  const data = event.data;
67
71
  if (data === null || typeof data !== "object" || typeof data.portholeCheck !== "string") {
@@ -92,6 +92,12 @@ export declare function servedSandboxDirective(config: PortholeConfig): CspDirec
92
92
  * so the shell's realm (a test holds every sandbox Porthole writes to this).
93
93
  */
94
94
  export declare const PAGE_SANDBOX_TOKENS: readonly string[];
95
+ /**
96
+ * A served display's door's sandbox (P125): its frame's attribute, which the host writes, and its
97
+ * answer's CSP header's. Scripts only: an opaque origin, a new one each time, that no content of
98
+ * the scope is the same origin as, so none reaches the door's document or speaks from its window.
99
+ */
100
+ export declare const DOOR_SANDBOX_TOKENS: readonly string[];
95
101
  /** A served page's CSP header: the page's directives, then its sandbox (P099). */
96
102
  export declare function servedDocumentCsp(config: PortholeConfig, directives: readonly CspDirective[]): string;
97
103
  /**
@@ -204,6 +204,12 @@ export function servedSandboxDirective(config) {
204
204
  * so the shell's realm (a test holds every sandbox Porthole writes to this).
205
205
  */
206
206
  export const PAGE_SANDBOX_TOKENS = ["allow-scripts"];
207
+ /**
208
+ * A served display's door's sandbox (P125): its frame's attribute, which the host writes, and its
209
+ * answer's CSP header's. Scripts only: an opaque origin, a new one each time, that no content of
210
+ * the scope is the same origin as, so none reaches the door's document or speaks from its window.
211
+ */
212
+ export const DOOR_SANDBOX_TOKENS = ["allow-scripts"];
207
213
  /** A served page's CSP header: the page's directives, then its sandbox (P099). */
208
214
  export function servedDocumentCsp(config, directives) {
209
215
  const sandbox = servedSandboxDirective(config);
@@ -2,10 +2,13 @@ import { type Frame, type Page } from "@playwright/test";
2
2
  import type { FrameOutcome } from "../host/types.ts";
3
3
  import type { ConformanceTest } from "./probes.ts";
4
4
  /**
5
- * Redirect entry's cases (P068): a clean address opens directly, signed in or not, and never
6
- * shows content without access; its one-time code works once, on its own origin; in a frame, the
7
- * app's sign-in never shows. A host implements `EntryConformanceHost` (or gives
8
- * `defineHostConformance` its `entry`).
5
+ * Redirect entry's cases (P068, P125): a clean address opens directly in a tab, signed in or not,
6
+ * and never shows content without access; its one-time code works once, on its own origin. A clean
7
+ * address is for a tab: a host frames what one names by resolving it through its issue endpoint
8
+ * first (a door, a ticket), and signed out, denied or not found, it builds no frame at all and
9
+ * shows its fallback from that answer. A clean address framed as it is goes nowhere: the host
10
+ * refuses it (no door), and the content origin answers it with a page that says nothing. A host
11
+ * implements `EntryConformanceHost` (or gives `defineHostConformance` its `entry`).
9
12
  */
10
13
  export interface EntryConformanceHost {
11
14
  readonly name: string;
@@ -35,12 +38,28 @@ export interface EntryConformanceHost {
35
38
  */
36
39
  completeSignIn?(page: Page): Promise<void>;
37
40
  /**
38
- * Frames a clean address on the app's page as the app would (a location of that address),
39
- * returning the frame and the display's outcome once it has one.
41
+ * Shows a clean address on the app's page as the app would (P125): resolved through the app's
42
+ * issue endpoint (`client.resolve`, `<PortholeView address>`), then framed through the location
43
+ * it issued. Returns the frame, the display's outcome once it has one, and whether any frame was
44
+ * ever made for it.
40
45
  */
41
46
  frame(page: Page, url: string): Promise<{
42
47
  frame(): Promise<Frame>;
43
48
  outcome(): Promise<FrameOutcome>;
49
+ framed(): Promise<boolean>;
50
+ }>;
51
+ /**
52
+ * Gives the app's `createHost` a clean address as a frame's location, as it is (no issue, no
53
+ * door), as a host of the wrong kind would. Returns the outcome, whether a frame was made, and
54
+ * the host errors it heard.
55
+ */
56
+ frameDirectly(page: Page, url: string): Promise<{
57
+ outcome(): Promise<FrameOutcome>;
58
+ framed(): Promise<boolean>;
59
+ hostErrors(): Promise<readonly {
60
+ readonly message: string;
61
+ readonly kind: string;
62
+ }[]>;
44
63
  }>;
45
64
  }
46
65
  export interface EntrySuiteOptions {
@@ -111,37 +111,88 @@ export function entryTests(host, options = {}) {
111
111
  expect(answer.status()).toBe(403);
112
112
  expect(answer.headers()["set-cookie"] ?? "").not.toMatch(/porthole-[a-z2-7]{16}=/u);
113
113
  });
114
- define("served.entry.framed", "a clean address in a frame shows the content where the browser keeps the cookies, else asks for a tab: never the app's sign-in", async ({ page, browserName }, info) => {
114
+ define("served.entry.framed", "a clean address shown in a frame is resolved through issue first, then framed through its door: the content, never the app's sign-in", async ({ page, browserName }, info) => {
115
115
  await host.signIn(page);
116
116
  const before = page.url();
117
117
  const shown = await host.frame(page, await host.url("entry-framed"));
118
- const outcome = await shown.outcome();
118
+ expect(await shown.outcome(), "probe: the issued frame loaded").toEqual({ state: "loaded" });
119
119
  const frame = await shown.frame();
120
120
  expect(page.url(), "the app's page stays where it was").toBe(before);
121
- expect(new URL(frame.url()).pathname).not.toMatch(/sign-?in/iu);
122
- if (outcome.state === "loaded") {
123
- await expect(frame.locator("#artifact")).toHaveText("version 1");
124
- }
125
- else {
126
- expect(outcome).toMatchObject({ state: "blocked" });
127
- expect(["cookies", "sign-in"]).toContain(outcome.reason);
128
- expect(await shows(frame)).toBe(false);
129
- }
130
- const said = outcome.state === "blocked" ? `blocked: ${outcome.reason}` : outcome.state;
121
+ // An issued frame (P125): Porthole's own document address, never the clean address, and
122
+ // never the app's sign-in. Its access is the ticket's (P083), so every engine shows it.
123
+ expect(new URL(frame.url()).pathname, "probe: framed through issue").toMatch(/^\/__porthole\/(d|f)\//u);
124
+ await expect(frame.locator("#artifact")).toHaveText("version 1");
131
125
  info.annotations.push({
132
126
  type: "measured",
133
- description: `${browserName}: framed entry ${said}`,
127
+ description: `${browserName}: framed entry loaded`,
134
128
  });
135
129
  });
136
- define("served.entry.framed-signed-out", "signed out, a clean address in a frame asks for a tab to sign in: the sign-in never shows in a frame", async ({ page }) => {
130
+ define("served.entry.framed-signed-out", "signed out, a clean address shown in a frame builds no frame: issue says sign in, and the fallback comes from that answer", async ({ page }) => {
137
131
  await host.signIn(page);
138
132
  // The app's page stays; the browser forgets every sign-in.
139
133
  await page.context().clearCookies();
140
134
  const shown = await host.frame(page, await host.url("entry-framed-out"));
141
- expect(await shown.outcome()).toMatchObject({ state: "blocked", reason: "sign-in" });
142
- const frame = await shown.frame();
143
- await expect(frame.locator("h1")).toHaveText("Open this in a new tab to sign in");
144
- expect(await shows(frame)).toBe(false);
135
+ expect(await shown.outcome(), "probe: issue's answer is the outcome").toEqual({
136
+ state: "blocked",
137
+ reason: "sign-in",
138
+ status: 401,
139
+ });
140
+ expect(await shown.framed(), "probe: no frame was made").toBe(false);
141
+ });
142
+ define("served.entry.framed-denied", "a clean address its viewer may not open, shown in a frame, builds no frame: issue says denied", async ({ page }, info) => {
143
+ info.skip(host.denied === undefined, "the host gave no address its viewer may not open (denied)");
144
+ await host.signIn(page);
145
+ const shown = await host.frame(page, (await host.denied?.("entry-framed-denied")) ?? "");
146
+ expect(await shown.outcome(), "probe: issue's answer is the outcome").toMatchObject({
147
+ state: "blocked",
148
+ reason: "denied",
149
+ status: 403,
150
+ });
151
+ expect(await shown.framed(), "probe: no frame was made").toBe(false);
152
+ });
153
+ define("served.entry.framed-not-found", "a clean address that names nothing, shown in a frame, builds no frame: issue says not found", async ({ page }, info) => {
154
+ const unknown = (await host.unknown?.()) ?? [];
155
+ // An address under a label the app never assigns: the first one that has a path.
156
+ const address = unknown.find((each) => new URL(each).hostname.split(".").length > 2);
157
+ info.skip(address === undefined, "the host gave no address that names nothing (unknown)");
158
+ await host.signIn(page);
159
+ const shown = await host.frame(page, address ?? "");
160
+ expect(await shown.outcome(), "probe: issue's answer is the outcome").toEqual({
161
+ state: "blocked",
162
+ reason: "not-found",
163
+ status: 404,
164
+ });
165
+ expect(await shown.framed(), "probe: no frame was made").toBe(false);
166
+ });
167
+ define("served.entry.in-a-frame", "a clean address framed as it is goes nowhere: the host refuses it (no door), and the content origin answers a page with no script, never the app", async ({ page }) => {
168
+ await host.signIn(page);
169
+ const url = await host.url("entry-in-a-frame");
170
+ // The host's own createHost, given the clean address as a location: refused before any
171
+ // frame (a served display needs a door from issue), and told why.
172
+ const direct = await host.frameDirectly(page, url);
173
+ expect(await direct.outcome(), "probe: refused before any frame").toEqual({
174
+ state: "blocked",
175
+ reason: "locate",
176
+ });
177
+ expect(await direct.framed(), "probe: no frame was made").toBe(false);
178
+ expect((await direct.hostErrors()).map((each) => each.kind), "probe: the host heard why (door)").toContain("door");
179
+ // A plain frame of the app's page at the clean address: the content origin answers it with
180
+ // a page of its own that has no script and goes nowhere (never the app's authorize).
181
+ const seen = await page.evaluate(async (address) => {
182
+ const frame = document.createElement("iframe");
183
+ const loaded = new Promise((resolve) => frame.addEventListener("load", resolve, { once: true }));
184
+ frame.src = address;
185
+ document.body.append(frame);
186
+ await loaded;
187
+ await new Promise((resolve) => setTimeout(resolve, 300));
188
+ return frame.getAttribute("src");
189
+ }, url);
190
+ expect(seen).toBe(url);
191
+ const frame = page.frames().find((each) => each.url() === url);
192
+ expect(frame, "probe: the frame stayed on the clean address (never the app's authorize)").toBeDefined();
193
+ expect(await frame?.locator("script").count(), "probe: the page in the frame has no script").toBe(0);
194
+ await expect(frame.locator("h1")).toHaveText("Open this in a new tab");
195
+ expect(await shows(frame), "probe: no content in the frame").toBe(false);
145
196
  });
146
197
  return tests;
147
198
  }
@@ -15,6 +15,18 @@ declare const harness: {
15
15
  } | {
16
16
  readonly location: FrameLocation;
17
17
  }, content?: string): number;
18
+ /**
19
+ * A clean address, shown as a host shows one (P125): resolved through the app's issue endpoint
20
+ * first (`{ address }`, `resolveAddress`), then framed through the location it issued (its
21
+ * door); signed out, denied or not found, the answer is the display's outcome and no frame is
22
+ * ever made. Later runs issue afresh by the resolved instance.
23
+ */
24
+ showAddress(config: PortholeConfig, where: {
25
+ readonly issue: string;
26
+ readonly headers?: Readonly<Record<string, string>>;
27
+ }, address: string): number;
28
+ /** Whether a display's frame was ever made (P125: a refused clean address makes none). */
29
+ framed: (id: number) => boolean;
18
30
  origin: (id: number) => string | null;
19
31
  failure: (id: number) => string | null;
20
32
  received: (id: number) => unknown[];
@@ -1,5 +1,5 @@
1
1
  import { createHost } from "../../host/create-host.js";
2
- import { httpLocator } from "../../host/locator.js";
2
+ import { httpLocator, resolveAddress } from "../../host/locator.js";
3
3
  const EVENTS = [
4
4
  "initialized",
5
5
  "resize",
@@ -70,6 +70,65 @@ addEventListener("message", (event) => {
70
70
  }
71
71
  }
72
72
  });
73
+ /** A display's record, before anything is mounted for it (a no-op handle until then). */
74
+ function recordOf(id) {
75
+ box(id, 600, 400);
76
+ const idle = { destroy() { }, setContent() { }, setTheme() { }, on: () => () => { } };
77
+ const shown = {
78
+ handle: idle,
79
+ calls: [],
80
+ events: [],
81
+ confirmations: [],
82
+ disclosed: [],
83
+ received: [],
84
+ origin: null,
85
+ failure: null,
86
+ frame: null,
87
+ };
88
+ displays.set(id, shown);
89
+ return shown;
90
+ }
91
+ /** Mounts a served display in its box, located by `asked` (the issue endpoint, or a location). */
92
+ function mountServed(id, shown, config, instance, asked, content) {
93
+ const container = document.getElementById(`porthole-display-${id}`);
94
+ const locator = {
95
+ async locate(each, signal) {
96
+ try {
97
+ const location = await asked.locate(each, signal);
98
+ shown.origin = location.origin;
99
+ return location;
100
+ }
101
+ catch (error) {
102
+ shown.failure = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
103
+ throw error;
104
+ }
105
+ },
106
+ };
107
+ const handle = createHost(config, {
108
+ handlers: recorder(shown.calls),
109
+ locator,
110
+ hostInfo: { name: "porthole-conformance", version: "1" },
111
+ ...(nonce === undefined ? {} : { nonce }),
112
+ }).mount(container, {
113
+ displayId: `display-${id}`,
114
+ title: "Probe",
115
+ scheme: "light",
116
+ instance,
117
+ });
118
+ shown.handle = handle;
119
+ watch(id, shown);
120
+ // The frame element, once it exists, so its messages can be told from others' (never a door).
121
+ const found = () => {
122
+ shown.frame = container.querySelector("iframe:not([data-porthole-door])");
123
+ if (shown.frame === null) {
124
+ requestAnimationFrame(found);
125
+ }
126
+ };
127
+ found();
128
+ if (content !== undefined) {
129
+ handle.setContent(content);
130
+ }
131
+ }
73
132
  const harness = {
74
133
  /** An opaque display with the suite's content (the leak suite's `launch`). */
75
134
  async launch(spec) {
@@ -131,62 +190,47 @@ const harness = {
131
190
  show(config, instance, where, content) {
132
191
  const id = next;
133
192
  next += 1;
134
- const container = box(id, 600, 400);
135
- const calls = [];
136
- const shown = {
137
- handle: null,
138
- calls,
139
- events: [],
140
- confirmations: [],
141
- disclosed: [],
142
- received: [],
143
- origin: null,
144
- failure: null,
145
- frame: null,
146
- };
193
+ const shown = recordOf(id);
147
194
  const asked = "issue" in where
148
195
  ? httpLocator(where.issue, where.headers === undefined ? {} : { headers: where.headers })
149
196
  : { locate: () => Promise.resolve(where.location) };
150
- const locator = {
151
- async locate(each, signal) {
152
- try {
153
- const location = await asked.locate(each, signal);
154
- shown.origin = location.origin;
155
- return location;
156
- }
157
- catch (error) {
158
- shown.failure =
159
- error instanceof Error ? `${error.name}: ${error.message}` : String(error);
160
- throw error;
161
- }
162
- },
163
- };
164
- const handle = createHost(config, {
165
- handlers: recorder(calls),
166
- locator,
167
- hostInfo: { name: "porthole-conformance", version: "1" },
168
- ...(nonce === undefined ? {} : { nonce }),
169
- }).mount(container, {
170
- displayId: `display-${id}`,
171
- title: "Probe",
172
- scheme: "light",
173
- instance,
174
- });
175
- shown.handle = handle;
176
- watch(id, shown);
177
- // The frame element, once it exists, so its messages can be told from others'.
178
- const found = () => {
179
- shown.frame = container.querySelector("iframe");
180
- if (shown.frame === null) {
181
- requestAnimationFrame(found);
197
+ mountServed(id, shown, config, instance, asked, content);
198
+ return id;
199
+ },
200
+ /**
201
+ * A clean address, shown as a host shows one (P125): resolved through the app's issue endpoint
202
+ * first (`{ address }`, `resolveAddress`), then framed through the location it issued (its
203
+ * door); signed out, denied or not found, the answer is the display's outcome and no frame is
204
+ * ever made. Later runs issue afresh by the resolved instance.
205
+ */
206
+ showAddress(config, where, address) {
207
+ const id = next;
208
+ next += 1;
209
+ const shown = recordOf(id);
210
+ const options = where.headers === undefined ? {} : { headers: where.headers };
211
+ void resolveAddress(where.issue, address, options).then((resolved) => {
212
+ if ("outcome" in resolved) {
213
+ shown.events.push({ type: "outcome", detail: resolved.outcome });
214
+ return;
182
215
  }
183
- };
184
- found();
185
- if (content !== undefined) {
186
- handle.setContent(content);
187
- }
216
+ shown.origin = resolved.location.origin;
217
+ let first = resolved.location;
218
+ const byInstance = httpLocator(where.issue, options);
219
+ const asked = {
220
+ locate(each, signal) {
221
+ const given = first;
222
+ first = null;
223
+ return given === null ? byInstance.locate(each, signal) : Promise.resolve(given);
224
+ },
225
+ };
226
+ mountServed(id, shown, config, resolved.instance, asked);
227
+ }, (error) => {
228
+ shown.failure = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
229
+ });
188
230
  return id;
189
231
  },
232
+ /** Whether a display's frame was ever made (P125: a refused clean address makes none). */
233
+ framed: (id) => (document.getElementById(`porthole-display-${id}`)?.querySelector("iframe") ?? null) !== null,
190
234
  origin: (id) => displays.get(id)?.origin ?? null,
191
235
  failure: (id) => displays.get(id)?.failure ?? null,
192
236
  received: (id) => displays.get(id)?.received ?? [],