@aloud/runner 0.2.0

package/src/run/sanitise.ts

@@ -0,0 +1,93 @@
+import {
+  evaluateTargetUrl,
+  intersectHosts,
+  leasePermits,
+  normaliseHosts,
+  type JobLease,
+  type StudySnapshot,
+} from "@aloud/core";
+import type { LocalPolicy } from "../config/policy";
+
+/**
+ * The security core of the runner.
+ *
+ * `RunCoordinator` passes `snapshot.environment.allowedDomains`,
+ * `snapshot.environment.actionPolicy.blockOffDomainNavigation` and `snapshot.environment.type`
+ * straight into `workers.create`. All three arrive from the server. Handing the raw snapshot to the
+ * coordinator would therefore let a compromised control plane point a browser on this machine at
+ * anything it liked, which is the one thing this whole architecture exists to prevent.
+ *
+ * So nothing from the wire decides what may be opened. The effective allowlist is the intersection
+ * of what the lease granted and what this machine's own policy permits, and off-domain navigation
+ * is forced on whatever the snapshot said.
+ */
+export class SnapshotRefused extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SnapshotRefused";
+  }
+}
+
+export interface SanitisedSnapshot {
+  snapshot: StudySnapshot;
+  allowedHosts: string[];
+}
+
+export async function sanitiseSnapshot(
+  snapshot: StudySnapshot,
+  lease: JobLease,
+  local: LocalPolicy,
+  nowIso: string,
+  /** Injected only by tests. DNS is re-resolved on every check, which closes the rebinding window. */
+  resolver?: (hostname: string) => Promise<string[]>,
+): Promise<SanitisedSnapshot> {
+  const granted = normaliseHosts(lease.allowedHosts);
+  const permitted = normaliseHosts(local.allowedHosts);
+
+  // The server already did this intersection. Doing it again here is the point: a server that got
+  // it wrong, or lied about it, changes nothing on this machine.
+  const effective = intersectHosts(granted, permitted);
+  if (effective.length === 0) {
+    throw new SnapshotRefused(
+      `This study wants ${granted.join(", ") || "nothing"}, and this machine allows ` +
+        `${permitted.join(", ") || "nothing"}. Nothing in common, so nothing will be opened. ` +
+        "Add a host with `aloud allow <host>` if that is wrong.",
+    );
+  }
+
+  const startUrl = snapshot.study?.startUrl;
+  if (typeof startUrl !== "string" || startUrl.length === 0) {
+    throw new SnapshotRefused("This study has no start URL.");
+  }
+
+  // Checked against the *effective* list, not the one the lease claimed.
+  const verdict = leasePermits({ ...lease, allowedHosts: effective }, startUrl, nowIso);
+  if (!verdict.allowed) throw new SnapshotRefused(verdict.reason);
+
+  // And then the same check the browser worker will make, so a refusal happens before anything is
+  // launched rather than three browsers in. Cloud metadata endpoints are refused unconditionally
+  // in here, regardless of the private-network setting.
+  const target = await evaluateTargetUrl(startUrl, {
+    allowedDomains: effective,
+    allowPrivateNetwork: local.allowPrivateNetwork,
+    ...(resolver ? { resolver } : {}),
+  });
+  if (!target.allowed) throw new SnapshotRefused(target.reason);
+
+  return {
+    allowedHosts: effective,
+    snapshot: {
+      ...snapshot,
+      environment: {
+        ...snapshot.environment,
+        allowedDomains: effective,
+        actionPolicy: {
+          ...snapshot.environment.actionPolicy,
+          // Forced on. A snapshot that asked for it to be off is exactly the snapshot that must
+          // not get it: without this a single redirect walks the browser off the allowlist.
+          blockOffDomainNavigation: true,
+        },
+      },
+    } as StudySnapshot,
+  };
+}

package/src/ui/output.ts

@@ -0,0 +1,185 @@
+import { scrubToken } from "../config/credentials";
+import type { RunReporter } from "../run/execute";
+
+const CSI = String.fromCharCode(27) + "[";
+const RESET = CSI + "0m";
+const BOLD = CSI + "1m";
+const DIM = CSI + "2m";
+const GREEN = CSI + "32m";
+const YELLOW = CSI + "33m";
+
+export interface Writer {
+  write(text: string): void;
+}
+
+/**
+ * Terminal output, in the same plain register the rest of the product uses.
+ *
+ * Every write goes through `scrubToken`, so a transcript someone pastes into a bug report cannot
+ * carry a working runner credential.
+ */
+export class TerminalReporter implements RunReporter {
+  private readonly lines = new Map<string, string>();
+  private readonly order: string[] = [];
+  private rendered = 0;
+
+  constructor(
+    private readonly out: Writer = process.stdout,
+    private readonly token: string | null = null,
+    private readonly interactive = Boolean(process.stdout.isTTY),
+  ) {}
+
+  private say(text: string): void {
+    this.out.write(scrubToken(text, this.token) + "\n");
+  }
+
+  header(input: { runnerName: string; workspace: string; server: string; allowedHosts: string[]; chromium: boolean }): void {
+    this.say("");
+    this.say(`${BOLD}Aloud runner${RESET}  ${DIM}${input.runnerName} - ${input.workspace}${RESET}`);
+    this.say("");
+    this.say(`  Chromium          ${input.chromium ? GREEN + "ready" + RESET : YELLOW + "not installed yet" + RESET}`);
+    this.say(`  Connection        ${input.server}`);
+    this.say(`  Allowed here      ${input.allowedHosts.join(", ") || "nothing yet - run `aloud allow <host>`"}`);
+    this.say("");
+  }
+
+  waiting(url: string): void {
+    this.say(`Waiting for a study. Start one at ${url}`);
+    this.say(`${DIM}Press Ctrl-C to stop.${RESET}`);
+  }
+
+  studyStarted(input: { name: string; goal: string; startUrl: string; participants: number; runId: string }): void {
+    this.lines.clear();
+    this.order.length = 0;
+    this.rendered = 0;
+    this.say("");
+    this.say(`${BOLD}Study: ${input.name}${RESET}`);
+    this.say(`${DIM}${input.goal}${RESET}`);
+    this.say(`Target: ${input.startUrl}`);
+    this.say(`${input.participants} participants, running here on this machine.`);
+    this.say("");
+  }
+
+  sessionProgress(personaName: string, detail: string): void {
+    this.set(personaName, detail);
+  }
+
+  sessionFinished(personaName: string, detail: string): void {
+    this.set(personaName, detail, true);
+  }
+
+  private set(name: string, detail: string, done = false): void {
+    if (!this.lines.has(name)) this.order.push(name);
+    this.lines.set(name, `  ${name.padEnd(12)}${done ? GREEN + detail + RESET : DIM + detail + RESET}`);
+    this.repaint();
+  }
+
+  /**
+   * Rewrites the progress block in place on a terminal, and appends on anything else.
+   *
+   * Appending into a CI log or a pipe is the right behaviour there; cursor movement would turn it
+   * into a wall of escape codes.
+   */
+  private repaint(): void {
+    if (!this.interactive) {
+      const last = this.order[this.order.length - 1];
+      if (last) this.say(this.lines.get(last)!);
+      return;
+    }
+    if (this.rendered > 0) this.out.write(CSI + this.rendered + "A" + CSI + "0J");
+    for (const name of this.order) this.say(this.lines.get(name)!);
+    this.rendered = this.order.length;
+  }
+
+  synthesising(): void {
+    this.rendered = 0;
+    this.say("");
+    this.say("Writing up what happened...");
+  }
+
+  finished(summary: { participants: number; succeeded: number; costCents: number; runId: string }): void {
+    this.rendered = 0;
+    this.say("");
+    this.say(
+      `${GREEN}Done.${RESET} ${summary.succeeded} of ${summary.participants} participants reached the goal.`,
+    );
+    this.say(`Spent ${summary.costCents} cents.`);
+    this.say("");
+  }
+
+  failed(reason: string): void {
+    this.rendered = 0;
+    this.say("");
+    this.say(`${YELLOW}This study did not finish.${RESET} ${reason}`);
+    this.say(`${DIM}Anything the participants did before this has been saved.${RESET}`);
+    this.say("");
+  }
+
+  note(message: string): void {
+    this.rendered = 0;
+    this.say(`${DIM}  ${message}${RESET}`);
+  }
+
+  connection(state: "lost" | "restored", detail: string): void {
+    this.rendered = 0;
+    if (state === "lost") {
+      this.say("");
+      this.say(`${YELLOW}  waiting - no connection to the server${RESET}`);
+      this.say(`${DIM}  The browsers are paused, not lost. I will pick up where I left off when the`);
+      this.say(`  connection comes back, or stop after a minute.${RESET}`);
+      return;
+    }
+    this.say(`${GREEN}  Connection is back. Carrying on.${RESET}`);
+    void detail;
+  }
+
+  /**
+   * The one thing a security-minded person deserves to be told, once.
+   *
+   * What genuinely never happens is our servers dialling into their network. What does happen is
+   * that screenshots leave this machine, because that is what the report is made of. Saying only
+   * the first half would be true and misleading.
+   */
+  privacyNote(): void {
+    this.say("");
+    this.say(`${BOLD}One thing worth knowing.${RESET}`);
+    this.say("");
+    this.say("The browsers run here, on this machine, so we can test localhost and");
+    this.say("anything behind your firewall. Our servers never connect to you.");
+    this.say("");
+    this.say("But the participants' screenshots do get sent to us, because that is");
+    this.say("what the report is built from. If you point this at something you would");
+    this.say("not screenshot and email, don't.");
+    this.say("");
+  }
+}
+
+/** For tests and for `--quiet`: records everything, prints nothing. */
+export class SilentReporter implements RunReporter {
+  readonly messages: string[] = [];
+  studyStarted(input: { name: string }): void {
+    this.messages.push(`study:${input.name}`);
+  }
+  sessionProgress(name: string, detail: string): void {
+    this.messages.push(`progress:${name}:${detail}`);
+  }
+  sessionFinished(name: string, detail: string): void {
+    this.messages.push(`finished:${name}:${detail}`);
+  }
+  synthesising(): void {
+    this.messages.push("synthesising");
+  }
+  finished(summary: { succeeded: number; participants: number }): void {
+    this.messages.push(`done:${summary.succeeded}/${summary.participants}`);
+  }
+  failed(reason: string): void {
+    this.messages.push(`failed:${reason}`);
+  }
+  note(message: string): void {
+    this.messages.push(`note:${message}`);
+  }
+  connection(state: string, detail: string): void {
+    this.messages.push(`connection:${state}`);
+    void detail;
+  }
+}