@mostra/conformance 0.9.0 → 0.10.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.
package/src/remote.ts ADDED
@@ -0,0 +1,170 @@
1
+ /**
2
+ * A remote server the kit runs for the remote scenarios (WP-29, INTERFACES §18): `mostra-runtime
3
+ * server` from the runtime the host uses, on loopback, with a development identity provider, and
4
+ * the host's instance signed in to it by the device grant, the person approving on the server's
5
+ * device page as a browser would.
6
+ */
7
+ import { type ChildProcess, spawn } from "node:child_process";
8
+ import { mkdirSync, writeFileSync } from "node:fs";
9
+ import { request } from "node:http";
10
+ import { createServer } from "node:net";
11
+ import { join } from "node:path";
12
+ import { resolveRuntime } from "@mostra/sdk";
13
+ import type { ScenarioContext } from "./scenario.ts";
14
+
15
+ /** A running server: its API origin, its port, and the variables an instance needs to reach it. */
16
+ export interface RemoteServer {
17
+ /** `http://api.localhost:<port>`: the binding, version files and sign-in. */
18
+ readonly origin: string;
19
+ /** The loopback port it listens on. */
20
+ readonly port: number;
21
+ /**
22
+ * What an instance of this run needs to reach it: `*.localhost` is this machine, and the
23
+ * server listens on 127.0.0.1 alone (`MOSTRA_TEST_SERVER_ADDRESS`).
24
+ */
25
+ readonly env: Readonly<Record<string, string>>;
26
+ }
27
+
28
+ async function freePort(): Promise<number> {
29
+ return new Promise((resolve, reject) => {
30
+ const probe = createServer();
31
+ probe.once("error", reject);
32
+ probe.listen(0, "127.0.0.1", () => {
33
+ const address = probe.address();
34
+ probe.close(() => resolve(typeof address === "object" && address ? address.port : 0));
35
+ });
36
+ });
37
+ }
38
+
39
+ /** Starts a server for `context`, stopped when the scenario ends. */
40
+ export async function startRemoteServer(context: ScenarioContext): Promise<RemoteServer> {
41
+ const port = await freePort();
42
+ const dir = join(context.dir, "server");
43
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
44
+ const config = join(dir, "server.json");
45
+ writeFileSync(
46
+ config,
47
+ JSON.stringify({
48
+ apiOrigin: `http://api.localhost:${port}`,
49
+ domains: { active: `content.localhost:${port}` },
50
+ scheme: "http",
51
+ identityProviders: [{ id: "dev", kind: "development", label: "Development sign-in" }],
52
+ }),
53
+ );
54
+ const env = { ...process.env, ...context.settings.hostEnv };
55
+ const runtime = await resolveRuntime({ env });
56
+ const child: ChildProcess = spawn(
57
+ runtime.node,
58
+ [
59
+ runtime.runtimeEntry,
60
+ "server",
61
+ "--data",
62
+ join(dir, "data"),
63
+ "--config",
64
+ config,
65
+ "--listen",
66
+ `127.0.0.1:${port}`,
67
+ ],
68
+ { env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true },
69
+ );
70
+ const exited = new Promise<void>((done) => child.once("exit", () => done()));
71
+ context.defer(async () => {
72
+ if (child.exitCode === null) {
73
+ child.kill();
74
+ const timer = setTimeout(() => child.kill("SIGKILL"), 10_000);
75
+ await exited;
76
+ clearTimeout(timer);
77
+ }
78
+ });
79
+ await new Promise<void>((resolve, reject) => {
80
+ let out = "";
81
+ const timer = setTimeout(
82
+ () => reject(new Error("the remote server didn't start in 60 s")),
83
+ 60_000,
84
+ );
85
+ child.stdout?.on("data", (chunk: Buffer) => {
86
+ out += chunk.toString("utf8");
87
+ const line = out.split("\n")[0];
88
+ if (!out.includes("\n") || line === undefined) return;
89
+ clearTimeout(timer);
90
+ const status = JSON.parse(line) as { status: string };
91
+ if (status.status === "started") resolve();
92
+ else reject(new Error(`the remote server didn't start: ${line}`));
93
+ });
94
+ child.once("exit", (code) => {
95
+ clearTimeout(timer);
96
+ reject(new Error(`the remote server exited with ${code}`));
97
+ });
98
+ });
99
+ return {
100
+ origin: `http://api.localhost:${port}`,
101
+ port,
102
+ env: { MOSTRA_TEST_SERVER_ADDRESS: `127.0.0.1:${port}` },
103
+ };
104
+ }
105
+
106
+ /** Posts a form to the server as its own device page does (with its own `Origin`). */
107
+ function postForm(
108
+ server: RemoteServer,
109
+ path: string,
110
+ fields: Record<string, string>,
111
+ ): Promise<{ status: number; body: string }> {
112
+ const body = new URLSearchParams(fields).toString();
113
+ return new Promise((resolve, reject) => {
114
+ const req = request(
115
+ {
116
+ host: "127.0.0.1",
117
+ port: server.port,
118
+ method: "POST",
119
+ path,
120
+ headers: {
121
+ host: new URL(server.origin).host,
122
+ origin: server.origin,
123
+ "content-type": "application/x-www-form-urlencoded",
124
+ "content-length": Buffer.byteLength(body),
125
+ },
126
+ agent: false,
127
+ },
128
+ (res) => {
129
+ const chunks: Buffer[] = [];
130
+ res.on("data", (chunk: Buffer) => chunks.push(chunk));
131
+ res.on("end", () =>
132
+ resolve({ status: res.statusCode ?? 0, body: Buffer.concat(chunks).toString("utf8") }),
133
+ );
134
+ },
135
+ );
136
+ req.setTimeout(30_000, () => req.destroy(new Error(`${path} didn't answer in 30 s`)));
137
+ req.on("error", reject);
138
+ req.end(body);
139
+ });
140
+ }
141
+
142
+ /**
143
+ * Signs the host's instance in to `server` through the host (`remote/login`, then
144
+ * `remote/login.wait`), approving the code on the device page as `name`; the instance's link.
145
+ */
146
+ export async function signIn(
147
+ context: ScenarioContext,
148
+ server: RemoteServer,
149
+ name = "Ada",
150
+ ): Promise<{ readonly instanceId: string }> {
151
+ const started = await context.host.call<{ loginId: string; userCode: string }>("remote/login", {
152
+ server: server.origin,
153
+ });
154
+ const approved = await postForm(server, "/device", {
155
+ user_code: started.userCode,
156
+ name,
157
+ provider: "dev",
158
+ decision: "approve",
159
+ });
160
+ if (approved.status !== 200) {
161
+ throw new Error(`the device page refused the approval: ${approved.status}`);
162
+ }
163
+ const waited = await context.host.call<{ status: string; instanceId: string }>(
164
+ "remote/login.wait",
165
+ { loginId: started.loginId, timeoutMs: 30_000 },
166
+ 40_000,
167
+ );
168
+ if (waited.status !== "signed-in") throw new Error(`remote/login.wait: ${waited.status}`);
169
+ return { instanceId: waited.instanceId };
170
+ }
package/src/scenario.ts CHANGED
@@ -114,6 +114,7 @@ export class ScenarioContext {
114
114
  /** The host: its name and version. */
115
115
  host!: HostUnderTest;
116
116
  readonly #hosts: HostUnderTest[] = [];
117
+ readonly #cleanups: (() => Promise<void>)[] = [];
117
118
  #published = 0;
118
119
 
119
120
  constructor(settings: RunSettings, dir: string) {
@@ -296,8 +297,16 @@ export class ScenarioContext {
296
297
  }
297
298
  }
298
299
 
300
+ /** Runs `cleanup` when the scenario ends, before its hosts stop (a server it started). */
301
+ defer(cleanup: () => Promise<void>): void {
302
+ this.#cleanups.push(cleanup);
303
+ }
304
+
299
305
  /** Ends every shim, stops a daemon the scenario left, and removes the directory. */
300
306
  async close(): Promise<void> {
307
+ for (const cleanup of this.#cleanups.splice(0).reverse()) {
308
+ await cleanup().catch(() => undefined);
309
+ }
301
310
  for (const host of this.#hosts) {
302
311
  await host.stopInstance().catch(() => undefined);
303
312
  await host.close().catch(() => undefined);
@@ -7,6 +7,7 @@ import type { Scenario } from "../scenario.ts";
7
7
  import { DELIVERY_SCENARIOS } from "./delivery.ts";
8
8
  import { INTERACTION_SCENARIOS } from "./interaction.ts";
9
9
  import { PORT_SCENARIOS } from "./ports.ts";
10
+ import { REMOTE_SCENARIOS } from "./remote.ts";
10
11
  import { SESSION_SCENARIOS } from "./session.ts";
11
12
  import { VIEWING_SCENARIOS } from "./viewing.ts";
12
13
 
@@ -17,4 +18,5 @@ export const SCENARIOS: readonly Scenario[] = [
17
18
  ...INTERACTION_SCENARIOS,
18
19
  ...PORT_SCENARIOS,
19
20
  ...VIEWING_SCENARIOS,
21
+ ...REMOTE_SCENARIOS,
20
22
  ];
@@ -0,0 +1,122 @@
1
+ /**
2
+ * A host whose instance shares to a remote server (WP-29, RM-02, RM-04; INTERFACES §18): the kit
3
+ * runs the server, the host's instance signs in by the device grant and shares through the host's
4
+ * own client, and the kit answers the hosted page as a respondent would. Hosted submissions reach
5
+ * the host through its instance's local outbox, with H-04's guarantees, and a hosted page's
6
+ * actions run on the host's instance, with its secrets, through the relay.
7
+ */
8
+ import { ACTIONS, FORM } from "../fixtures.ts";
9
+ import { type RemoteServer, signIn, startRemoteServer } from "../remote.ts";
10
+ import { check, type Scenario, type ScenarioContext, same } from "../scenario.ts";
11
+ import { resultOf, Viewer } from "../viewer.ts";
12
+
13
+ /** Starts a server and the host's instance, signed in to it. */
14
+ async function linked(context: ScenarioContext): Promise<RemoteServer> {
15
+ const server = await startRemoteServer(context);
16
+ await context.start({ env: server.env });
17
+ await signIn(context, server);
18
+ return server;
19
+ }
20
+
21
+ /** Shares `artifactId` to the server through the host; the hosted link. */
22
+ async function hostedLink(
23
+ context: ScenarioContext,
24
+ artifactId: string,
25
+ params: Record<string, unknown> = {},
26
+ ): Promise<string> {
27
+ const shared = await context.host.call<{ url: string; via: string }>(
28
+ "share/start",
29
+ { artifact: { artifactId }, via: "remote", ...params },
30
+ 120_000,
31
+ );
32
+ same(shared.via, "remote", "the share's way");
33
+ return shared.url;
34
+ }
35
+
36
+ /** RM-02, H-04: a hosted page's answer reaches the host once, through its instance's outbox. */
37
+ export const hostedDelivery: Scenario = {
38
+ id: "remote.delivery",
39
+ title:
40
+ "An answer on a hosted link is told only that it was sent, reaches the host's submissions port once through its instance's local outbox, and reads locally with wait and results/get",
41
+ covers: ["RM-02", "HO-05", "IN-12", "IN-13", "H-04"],
42
+ async run(context) {
43
+ const server = await linked(context);
44
+ const receipt = await context.published(FORM);
45
+ const url = await hostedLink(context, receipt.artifactId);
46
+ check(
47
+ new URL(url).host === `content.localhost:${server.port}` && url.includes("/a/rte_"),
48
+ `a hosted link on the user-content domain, by route (${new URL(url).origin}${new URL(url).pathname})`,
49
+ );
50
+ const viewer = await Viewer.open(url);
51
+ const channel = viewer.ticket.submitChannels.includes("artifact") ? "artifact" : "shell";
52
+ const answer = await viewer.answer({ name: "Ada", comment: "From the server" }, channel);
53
+ same(answer.status, 200, `the hosted submit's status (${answer.body})`);
54
+ const summary = answer.json<{ id: string; deliveries?: unknown }>();
55
+ // A respondent sees that the answer was sent, never its delivery (D165 item 1a).
56
+ same(summary.deliveries, undefined, "the delivery states a respondent is shown");
57
+ const waited = await context.host.call<{ status: string }>(
58
+ "wait",
59
+ { artifact: { artifactId: receipt.artifactId }, until: "submitted", timeoutMs: 60_000 },
60
+ 70_000,
61
+ );
62
+ same(waited.status, "satisfied", "wait --until submitted on the host's instance");
63
+ const results = await context.eventually("results/get reads the hosted answer", async () => {
64
+ const read = await context.results(receipt.artifactId);
65
+ return read.submission.id === summary.id ? read : undefined;
66
+ });
67
+ same(results.answers, { name: "Ada", comment: "From the server" }, "the answers");
68
+ check(
69
+ (results.submission as { origin?: unknown }).origin !== undefined,
70
+ "the submission names the hosted home it came from",
71
+ );
72
+ if (context.host.serves("submissions")) {
73
+ const stored = await context.eventually("the host's store holds the submission", async () =>
74
+ (await context.store()).deliveries.find((entry) => entry.submissionId === summary.id),
75
+ );
76
+ same(stored.stored, 1, "copies the host's store holds");
77
+ // Once in effect: the same answer isn't delivered again however long the host waits.
78
+ await new Promise((done) => setTimeout(done, 2_000));
79
+ const later = (await context.store()).deliveries.filter(
80
+ (entry) => entry.submissionId === summary.id,
81
+ );
82
+ same(later.length, 1, "deliveries of the hosted answer");
83
+ same(later[0]?.stored, 1, "copies after a while");
84
+ }
85
+ },
86
+ };
87
+
88
+ /** RM-04: a hosted page's action runs once on the host's instance, with its secret. */
89
+ export const hostedRelay: Scenario = {
90
+ id: "remote.relay",
91
+ title:
92
+ "An action pressed on a hosted page runs on the host's instance with the instance's own secret, and what it raises reaches the host's events",
93
+ covers: ["RM-04", "AC-05", "HO-05"],
94
+ async run(context) {
95
+ await linked(context);
96
+ const receipt = await context.published(ACTIONS);
97
+ await context.host.call("secret/set", {
98
+ name: "MAIL_KEY",
99
+ value: "k-0123456789",
100
+ artifact: { artifactId: receipt.artifactId },
101
+ });
102
+ // A named respondent may trigger relayed actions by default (D159).
103
+ const url = await hostedLink(context, receipt.artifactId, {
104
+ viewer: { ref: "grace@example.com", name: "Grace" },
105
+ });
106
+ const viewer = await Viewer.open(url);
107
+ const length = await viewer.run("actions.ts#secretLength", ["MAIL_KEY"]);
108
+ same(length.status, "succeeded", "the relayed run's end");
109
+ same(await resultOf(length), 12, "the secret's length, read on the host's instance");
110
+ const notified = await viewer.run("actions.ts#notify", ["grace@example.com"]);
111
+ same(notified.status, "succeeded", "the second relayed run's end");
112
+ await context.eventually("the host's instance follows what the run raised", async () => {
113
+ const read = await context.host.call<{ events: { type: string }[] }>("events/read", {
114
+ filter: { artifacts: [receipt.artifactId], types: ["host.mail.sent"] },
115
+ });
116
+ return read.events.length === 1 ? read : undefined;
117
+ });
118
+ },
119
+ };
120
+
121
+ /** Every remote scenario. */
122
+ export const REMOTE_SCENARIOS: readonly Scenario[] = [hostedDelivery, hostedRelay];
package/src/viewer.ts CHANGED
@@ -5,7 +5,9 @@
5
5
  * `Origin`, `Sec-Fetch-*` and CSRF headers a browser sends. It also sends what no browser would,
6
6
  * for the hygiene scenarios. It never follows redirects. Where the shell and the artifact are two
7
7
  * sites (a host's external bases, a Cloudflare share), it enters the frame as the bootstrap page
8
- * does and signs the frame's requests as Mostra's service worker does (D70, D158 item 5).
8
+ * does and signs the frame's requests as Mostra's service worker does (D70, D158 item 5). On a
9
+ * remote server's hosted link (`/a/<routeId>`) it keeps the shell's session as the hosted shell
10
+ * does, in a header and never a cookie (`X-Mostra-Shell`, D165 item 8).
9
11
  */
10
12
  import { request as httpRequest } from "node:http";
11
13
  import {
@@ -101,7 +103,7 @@ export function send(ask: Ask): Promise<Answer> {
101
103
  export interface ParsedLink {
102
104
  /** The shell's origin. */
103
105
  readonly origin: string;
104
- /** The artifact the link opens. */
106
+ /** The artifact the link opens; on a hosted link, its hosted route (`rte_…`, §18.4). */
105
107
  readonly artifactId: string;
106
108
  /** The token's secret, from the fragment. */
107
109
  readonly secret: string;
@@ -109,10 +111,13 @@ export interface ParsedLink {
109
111
  readonly version?: string;
110
112
  }
111
113
 
112
- /** Reads a capability link (`http://host:port/a/<artifactId>[/v/<n>]#t=<secret>`). */
114
+ /**
115
+ * Reads a capability link (`http://host:port/a/<artifactId>[/v/<n>]#t=<secret>`), or a hosted one
116
+ * (`https://<domain>/a/<routeId>…`).
117
+ */
113
118
  export function parseLink(link: string): ParsedLink {
114
119
  const url = new URL(link);
115
- const match = /^\/a\/(art_[0-9A-Z]{26})(?:\/v\/(\d+))?$/.exec(url.pathname);
120
+ const match = /^\/a\/((?:art|rte)_[0-9A-Z]{26})(?:\/v\/(\d+))?$/.exec(url.pathname);
116
121
  const secret = new URLSearchParams(url.hash.slice(1)).get("t");
117
122
  if (!match?.[1] || !secret)
118
123
  throw new Error(`${url.origin}${url.pathname} isn't a capability link.`);
@@ -130,6 +135,14 @@ export class Browser {
130
135
  /** Worker-mode frame sessions by origin: the header Mostra's service worker adds (D70). */
131
136
  readonly #frames = new Map<string, string>();
132
137
 
138
+ /** Hosted shells' sessions by `<origin>/a/<routeId>`: the header the hosted shell sends. */
139
+ readonly #shells = new Map<string, string>();
140
+
141
+ /** Sends `secret` as `X-Mostra-Shell` on every later request under `prefix`, as a hosted shell does. */
142
+ keepShell(prefix: string, secret: string): void {
143
+ this.#shells.set(prefix, secret);
144
+ }
145
+
133
146
  /** Signs every later request to `origin` with a worker-mode frame session, as its worker does. */
134
147
  enterFrame(origin: string, secret: string): void {
135
148
  this.#frames.set(origin, secret);
@@ -158,11 +171,17 @@ export class Browser {
158
171
  const url = new URL(ask.url);
159
172
  // The service worker signs every same-origin request but a ticketed one, which bypasses it.
160
173
  const frame = url.searchParams.has("ticket") ? undefined : this.#frames.get(url.origin);
174
+ const shell = ask.noCookies
175
+ ? undefined
176
+ : [...this.#shells].find(
177
+ ([prefix]) => ask.url === prefix || ask.url.startsWith(`${prefix}/`),
178
+ )?.[1];
161
179
  const answer = await send({
162
180
  ...ask,
163
181
  headers: {
164
182
  ...(cookie ? { cookie } : {}),
165
183
  ...(frame !== undefined ? { "x-mostra-frame": frame } : {}),
184
+ ...(shell !== undefined ? { "x-mostra-shell": shell } : {}),
166
185
  ...ask.headers,
167
186
  },
168
187
  });
@@ -270,6 +289,9 @@ export class Viewer {
270
289
  });
271
290
  if (exchange.status !== 200) throw new OpenError("exchange", exchange);
272
291
  const shellCsrf = exchange.json<{ csrf: string }>().csrf;
292
+ // A hosted shell's session is a secret it keeps and sends in a header (D165 item 8).
293
+ const hosted = exchange.json<{ session?: string }>().session;
294
+ if (hosted !== undefined) browser.keepShell(`${parsed.origin}/a/${parsed.artifactId}`, hosted);
273
295
  const ticketAnswer = await browser.fetchJson(parsed.origin, `${api}/ticket`, {
274
296
  body: parsed.version !== undefined ? { version: Number(parsed.version) } : {},
275
297
  csrf: shellCsrf,