setup-agent 0.0.6 → 0.0.8

package/src/cli.ts

@@ -2,9 +2,20 @@ import { connectCheckout } from "./client";
 import type { CheckoutClient } from "./client";
 import { INPUT_PRESETS, isPresetId, presetInput } from "./presets";
 import { spawn } from "node:child_process";
-import { open, readFile } from "node:fs/promises";
+import { createHash, randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import {
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  realpath,
+  unlink,
+} from "node:fs/promises";
+import { homedir, tmpdir, userInfo } from "node:os";
 import { createInterface } from "node:readline/promises";
-import { resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import {
   AGENT_HEARTBEAT_MS,
   OPTION_ICONS,
@@ -12,6 +23,7 @@ import {
   currentPlan,
   isAgentPresent,
   isClosed,
+  isLoopbackHostname,
   isOptionIcon,
   isValidModelAnswer,
   parseEntryPointOptions,
@@ -54,9 +66,56 @@ Commands (the url always comes first):
                                     Mark every remaining step done and propose closing; the user closes it.
 `;
 
-export const agentInstructions = (
-  url: string,
-) => `You are the coding agent for a setup the user opened in their browser. The browser shows this setup live; every command below updates it. The user watches the browser, not this terminal: once setup begins, send questions through "ask" so the user can answer in their browser.
+/** Characters a setup URL may hold: an origin and a path, nothing a shell or a reader treats as more than an address. */
+const SETUP_URL_PATTERN =
+  /^https?:\/\/[A-Za-z0-9.-]+(?::[0-9]+)?(?:\/[A-Za-z0-9._~%/-]*)?$|^http:\/\/\[::1\](?::[0-9]+)?(?:\/[A-Za-z0-9._~%/-]*)?$/;
+
+/**
+ * The normalized setup URL, or an error saying why it is refused. A setup URL
+ * is printed into shell commands and the coding agent's prompt, and the API
+ * key travels over it, so it must be https (http only on this machine), carry
+ * no credentials, query or fragment, and hold only address characters.
+ */
+export const parseSetupUrl = (value: string): string => {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`"${value}" is not a URL`);
+  }
+  if (
+    url.protocol !== "https:" &&
+    !(url.protocol === "http:" && isLoopbackHostname(url.hostname))
+  ) {
+    throw new Error("the setup URL must use https (http only on localhost)");
+  }
+  if (url.username !== "" || url.password !== "") {
+    throw new Error("the setup URL must not carry credentials");
+  }
+  if (
+    url.search !== "" ||
+    url.hash !== "" ||
+    value.includes("?") ||
+    value.includes("#")
+  ) {
+    throw new Error("the setup URL must not have a query or fragment");
+  }
+  const href = url.href.replace(/\/$/, "");
+  if (!SETUP_URL_PATTERN.test(href)) {
+    throw new Error("the setup URL has characters a setup URL does not use");
+  }
+  return href;
+};
+
+/** `value` as one shell word, quoted only when it holds more than plain URL characters. */
+const shellWord = (value: string) =>
+  /^[A-Za-z0-9._~%/:@=+,-]+$/.test(value)
+    ? value
+    : `'${value.replaceAll("'", `'\\''`)}'`;
+
+export const agentInstructions = (setupUrl: string) => {
+  const url = shellWord(setupUrl);
+  return `You are the coding agent for a setup the user opened in their browser. The browser shows this setup live; every command below updates it. The user watches the browser, not this terminal: once setup begins, send questions through "ask" so the user can answer in their browser.
 
 First, start a persistent Monitor on
   npx setup-agent ${url} stream
@@ -99,6 +158,7 @@ Before that, start the project's dev server in the background when the project h
   npx setup-agent ${url} wait start
 which returns once that setup begins, then run "status" for its products, guides and instructions and go through plan and install again. A "setup.created" event while you are still working means the user replaced this setup: drop what you were doing and start over the same way.
 `;
+};
 
 export const INSTRUCTIONS = agentInstructions;
 
@@ -231,7 +291,7 @@ const chooseLauncher = async () => {
 
 const launchAgent = async (url: string) => {
   const launcher = await chooseLauncher();
-  const prompt = `Run \`npx setup-agent ${url}\` and follow the instructions it prints.`;
+  const prompt = `Run \`npx setup-agent ${shellWord(url)}\` and follow the instructions it prints.`;
   process.stdout.write(`\nStarting ${launcher.name}...\n\n`);
   const child = spawn(launcher.command, launcher.args(prompt), {
     stdio: "inherit",
@@ -643,6 +703,16 @@ const assertEnvKey = (key: string) => {
 /** Sets `key=value` in dotenv text, replacing an existing line for the key. */
 export const upsertEnvLine = (content: string, key: string, value: string) => {
   assertEnvKey(key);
+  // A line break or other control character would end the line and let the
+  // value write lines of its own.
+  const isLineBreaking = (code: number) =>
+    code < 0x20 ||
+    (code >= 0x7f && code <= 0x9f) ||
+    code === 0x2028 ||
+    code === 0x2029;
+  if ([...value].some((char) => isLineBreaking(char.charCodeAt(0)))) {
+    throw new Error(`the value for ${key} must be a single line`);
+  }
   const line = `${key}=${value}`;
   const lines = content === "" ? [] : content.replace(/\n$/, "").split("\n");
   const index = lines.findIndex(
@@ -664,20 +734,165 @@ export const writeEnvSecret = async (
   file: string,
   key: string,
   take: () => Promise<string>,
+  projectRoot = process.cwd(),
 ) => {
   assertEnvKey(key);
-  const handle = await open(file, "a+", 0o600);
+  try {
+    if ((await lstat(file)).isSymbolicLink()) {
+      throw new Error(
+        `${file} is a symbolic link; pass --file with its target to write there`,
+      );
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  const projectRelative = relative(projectRoot, file);
+  if (
+    projectRelative !== ".." &&
+    !projectRelative.startsWith(`..${sep}`) &&
+    !isAbsolute(projectRelative)
+  ) {
+    const root = await realpath(projectRoot);
+    const parent = await realpath(dirname(file));
+    const parentRelative = relative(root, parent);
+    if (
+      parentRelative === ".." ||
+      parentRelative.startsWith(`..${sep}`) ||
+      isAbsolute(parentRelative)
+    ) {
+      throw new Error(`${file} has a parent directory outside the project`);
+    }
+  }
+  const handle = await open(
+    file,
+    constants.O_RDWR |
+      constants.O_APPEND |
+      constants.O_CREAT |
+      constants.O_NOFOLLOW,
+    0o600,
+  ).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "ELOOP")
+      throw new Error(
+        `${file} is a symbolic link; pass --file with its target to write there`,
+      );
+    throw error;
+  });
   try {
     await handle.chmod(0o600);
     const value = await take();
     const current = await handle.readFile("utf8");
+    // Built before truncating, so a refused value leaves the file intact.
+    const next = upsertEnvLine(current, key, value);
     await handle.truncate(0);
-    await handle.writeFile(upsertEnvLine(current, key, value));
+    await handle.writeFile(next);
   } finally {
     await handle.close();
   }
 };
 
+const redeemKeyDirectories = () => {
+  const stateHome =
+    process.platform === "win32"
+      ? process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local")
+      : process.env.XDG_STATE_HOME || join(homedir(), ".local", "state");
+  return [
+    join(stateHome, "setup-agent"),
+    join(
+      tmpdir(),
+      `setup-agent-${process.platform === "win32" ? userInfo().username : process.getuid!()}`,
+    ),
+  ];
+};
+
+const checkRedeemKeyDirectory = async (directory: string) => {
+  if (!isAbsolute(directory)) {
+    throw new Error("state home must be an absolute path");
+  }
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new Error(
+      `redeem key directory must not be a symbolic link: ${directory}`,
+    );
+  }
+  if (process.platform !== "win32") {
+    if (info.uid !== process.getuid!()) {
+      throw new Error(
+        `redeem key directory must be owned by the user: ${directory}`,
+      );
+    }
+    if ((info.mode & 0o077) !== 0) await chmod(directory, 0o700);
+  }
+};
+
+const prepareRedeemKeyDirectory = async (directory: string) => {
+  if (isAbsolute(directory)) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+  }
+  await checkRedeemKeyDirectory(directory);
+};
+
+const saveRedeemKey = async (hash: string, key: string) => {
+  let lastError: unknown;
+  for (const directory of redeemKeyDirectories()) {
+    const file = join(directory, `${hash}.key`);
+    let created = false;
+    try {
+      await prepareRedeemKeyDirectory(directory);
+      const handle = await open(
+        file,
+        constants.O_WRONLY |
+          constants.O_CREAT |
+          constants.O_EXCL |
+          constants.O_NOFOLLOW,
+        0o600,
+      );
+      created = true;
+      try {
+        await handle.writeFile(key);
+      } finally {
+        await handle.close();
+      }
+      return file;
+    } catch (error) {
+      if (created) await unlink(file).catch(() => {});
+      lastError = error;
+    }
+  }
+  throw lastError;
+};
+
+const readRedeemKey = async (hash: string) => {
+  if (!/^[0-9a-f]{64}$/.test(hash)) return undefined;
+  for (const directory of redeemKeyDirectories()) {
+    try {
+      await checkRedeemKeyDirectory(directory);
+      const file = join(directory, `${hash}.key`);
+      const handle = await open(
+        file,
+        constants.O_RDONLY | constants.O_NOFOLLOW,
+      );
+      try {
+        const info = await handle.stat();
+        if (
+          !info.isFile() ||
+          (process.platform !== "win32" && (info.mode & 0o077) !== 0)
+        ) {
+          throw new Error("redeem key file must be private and regular");
+        }
+        const key = await handle.readFile("utf8");
+        if (createHash("sha256").update(key).digest("hex") === hash) {
+          return { key, file };
+        }
+      } finally {
+        await handle.close();
+      }
+    } catch {
+      continue;
+    }
+  }
+  return undefined;
+};
+
 const answerFields = (input: Checkout.Input, answer: string) => ({
   answer: (input.multiple && parseMultipleAnswer(answer)) || answer,
   ...(input.note !== undefined && { note: input.note }),
@@ -701,7 +916,12 @@ export const main = async (argv: readonly string[]) => {
     process.stdout.write(HELP);
     return process.exit(first === undefined ? 1 : 0);
   }
-  const url = first;
+  let url: string;
+  try {
+    url = parseSetupUrl(first);
+  } catch (error) {
+    return fail(error instanceof Error ? error.message : String(error));
+  }
   if (command === "intro" && isDirectInvocation()) return launchAgent(url);
 
   const client = await connectCheckout(url).catch((error: unknown) =>
@@ -775,7 +995,32 @@ export const main = async (argv: readonly string[]) => {
         break;
       }
       case "ask": {
-        const { inputId } = await commands["agent/ask"](askSeed(rest, flags));
+        const seed = askSeed(rest, flags);
+        const redeemKey =
+          seed.kind === "model" ? randomBytes(32).toString("hex") : undefined;
+        const redeemKeyHash =
+          redeemKey === undefined
+            ? undefined
+            : createHash("sha256").update(redeemKey).digest("hex");
+        const keyFile =
+          redeemKey === undefined || redeemKeyHash === undefined
+            ? undefined
+            : await saveRedeemKey(redeemKeyHash, redeemKey).catch(
+                (error: unknown) =>
+                  fail(
+                    `could not store the model redeem key: ${error instanceof Error ? error.message : String(error)}`,
+                  ),
+              );
+        let inputId: string;
+        try {
+          ({ inputId } = await commands["agent/ask"]({
+            ...seed,
+            ...(redeemKeyHash !== undefined && { redeemKeyHash }),
+          }));
+        } catch (error) {
+          if (keyFile !== undefined) await unlink(keyFile).catch(() => {});
+          throw error;
+        }
         if (!flags.has("wait")) {
           print({ ok: true, inputId });
           break;
@@ -835,19 +1080,58 @@ export const main = async (argv: readonly string[]) => {
         ) {
           fail(`input "${inputId}" is not an llm-provider answer`);
         }
+        const storedKey =
+          input.redeemKeyHash === undefined
+            ? undefined
+            : await readRedeemKey(input.redeemKeyHash);
+        if (input.redeemKeyHash !== undefined && storedKey === undefined) {
+          fail(`no local redeem key for "${inputId}"`);
+        }
         const file = resolve(flagText(flags, "file") ?? ".env.local");
         await writeEnvSecret(file, envKey, async () => {
+          const secretUrl = new URL(url);
+          if (
+            secretUrl.protocol !== "https:" &&
+            !(
+              secretUrl.protocol === "http:" &&
+              isLoopbackHostname(secretUrl.hostname)
+            )
+          ) {
+            fail("the key is only fetched over https");
+          }
           const response = await fetch(
             `${url.replace(/\/$/, "")}/secret/${encodeURIComponent(inputId)}?setup=${encodeURIComponent(setupId)}`,
+            storedKey === undefined
+              ? undefined
+              : { headers: { "Setup-Agent-Redeem-Key": storedKey.key } },
           );
+          if (response.status === 403) {
+            fail(`redeem key rejected for "${inputId}"`);
+          }
           if (response.status === 404) {
             fail(
               `the key for "${inputId}" was already taken or never deposited`,
             );
           }
           if (!response.ok) fail(`could not fetch the key: ${response.status}`);
-          return response.text();
+          const key = await response.text();
+          // An API key is one word of letters, digits and a few separators;
+          // anything else could break out of the env line, be read differently
+          // by dotenv, or run as shell syntax when the file is sourced.
+          if (!/^[A-Za-z0-9._~+/=:@%,-]+$/.test(key)) {
+            fail("the deposited key is not a valid API key");
+          }
+          return key;
         });
+        if (storedKey !== undefined) {
+          await unlink(storedKey.file).catch((error: NodeJS.ErrnoException) => {
+            if (error.code !== "ENOENT") {
+              process.stderr.write(
+                `warning: could not remove a redeem key: ${error.message}\n`,
+              );
+            }
+          });
+        }
         print({ ok: true, envKey, file });
         break;
       }

package/src/host.test.ts

@@ -163,6 +163,70 @@ describe("CheckoutHost", () => {
 });
 
 describe("plans", () => {
+  it.each([
+    { decision: "approve" },
+    { decision: "revise", feedback: "Use pnpm" },
+  ] satisfies Checkout.PlanDecision[])(
+    "rejects a $decision decision for a superseded revision",
+    async (decision) => {
+      const host = mount();
+      await host.commands["checkout/create"](seed);
+      await host.commands["checkout/begin-plan"]();
+      await host.commands["agent/plan"]({ markdown: "Install chat" });
+      const pending = { ...decision, id: seed.id, revision: 1 };
+      await host.commands["agent/plan"]({ markdown: "Replace the API route" });
+
+      expect(await reason(host.commands["checkout/plan"](pending))).toEqual({
+        reason: "stale-plan",
+      });
+      expect(currentPlan(host.state)).toMatchObject({
+        revision: 2,
+        status: "proposed",
+      });
+      expect(host.state.status).toBe("planning");
+      expect(currentPlan(host.state)?.feedback).toBeUndefined();
+
+      await host.commands["checkout/plan"]({ ...pending, revision: 2 });
+      expect(currentPlan(host.state)?.status).toBe(
+        decision.decision === "approve" ? "approved" : "changes-requested",
+      );
+    },
+  );
+
+  it("rejects a decision from an earlier setup with the same plan revision", async () => {
+    const host = mount();
+    await host.commands["checkout/create"](seed);
+    await host.commands["checkout/begin-plan"]();
+    await host.commands["agent/plan"]({ markdown: "Install chat" });
+    await host.commands["checkout/cancel"]({ id: seed.id });
+    await host.commands["checkout/create"]({ ...seed, id: "replacement" });
+    await host.commands["checkout/begin-plan"]();
+    await host.commands["agent/plan"]({ markdown: "Install cloud" });
+
+    expect(
+      await reason(
+        host.commands["checkout/plan"]({
+          decision: "approve",
+          id: seed.id,
+          revision: 1,
+        }),
+      ),
+    ).toEqual({ reason: "stale-plan" });
+    expect(currentPlan(host.state)).toMatchObject({
+      revision: 1,
+      status: "proposed",
+    });
+    expect(host.state.status).toBe("planning");
+
+    await host.commands["checkout/plan"]({
+      decision: "approve",
+      id: "replacement",
+      revision: 1,
+    });
+    expect(currentPlan(host.state)?.status).toBe("approved");
+    expect(host.state.status).toBe("installing");
+  });
+
   it("refuses steps until the user approves a plan", async () => {
     const host = mount();
     await host.commands["checkout/create"](seed);
@@ -606,6 +670,46 @@ describe("inputs", () => {
 describe("model inputs", () => {
   const answer = { provider: "openai", model: "gpt-test" };
 
+  it("stores a valid redeem hash only on model inputs", async () => {
+    const host = mount();
+    await host.commands["checkout/create"](seed);
+    await host.commands["checkout/begin-plan"]();
+    const hash = "a".repeat(64);
+    const { inputId } = await host.commands["agent/ask"]({
+      ...presetInput("llm-provider"),
+      redeemKeyHash: hash,
+    });
+    expect(
+      host.state.inputs.find((input) => input.id === inputId)?.redeemKeyHash,
+    ).toBe(hash);
+    await host.commands["checkout/answer"]({
+      inputId,
+      answer: JSON.stringify(answer),
+    });
+    expect(
+      host.state.inputs.find((input) => input.id === inputId)?.redeemKeyHash,
+    ).toBe(hash);
+    for (const redeemKeyHash of [
+      "A".repeat(64),
+      "a".repeat(63),
+      "not-a-hash",
+    ]) {
+      expect(
+        await reason(
+          host.commands["agent/ask"]({
+            ...presetInput("llm-provider"),
+            redeemKeyHash,
+          }),
+        ),
+      ).toEqual({ reason: "invalid-input" });
+    }
+    expect(
+      await reason(
+        host.commands["agent/ask"]({ prompt: "Name?", redeemKeyHash: hash }),
+      ),
+    ).toEqual({ reason: "invalid-input" });
+  });
+
   it("parses a model answer and rejects malformed ones", () => {
     expect(parseModelAnswer(JSON.stringify(answer))).toEqual(answer);
     expect(

package/src/host.ts

@@ -86,6 +86,12 @@ const useCheckoutHost = (restored: unknown) => {
 
   const ask = (seed: Checkout.InputSeed & { stepId?: string }) => {
     const kind = seed.kind ?? "text";
+    if (
+      seed.redeemKeyHash !== undefined &&
+      (kind !== "model" || !/^[0-9a-f]{64}$/.test(seed.redeemKeyHash))
+    ) {
+      throw reject("invalid-input", "invalid model redeem key hash");
+    }
     const options =
       kind === "entry-point"
         ? parseEntryPointOptions(seed.options)
@@ -166,6 +172,9 @@ const useCheckoutHost = (restored: unknown) => {
       ...(kind === "product" && { product: seed.product }),
       ...(seed.default !== undefined && { default: seed.default }),
       ...(seed.help !== undefined && { help: seed.help }),
+      ...(seed.redeemKeyHash !== undefined && {
+        redeemKeyHash: seed.redeemKeyHash,
+      }),
       optional: seed.optional ?? false,
       status: "open",
       ...(stepId !== undefined && { stepId }),
@@ -331,6 +340,15 @@ const useCheckoutHost = (restored: unknown) => {
       if (plan === undefined) {
         throw reject("no-plan", "the agent has not proposed a plan yet");
       }
+      if (
+        (params.id !== undefined && params.id !== state.id) ||
+        (params.revision !== undefined && params.revision !== plan.revision)
+      ) {
+        throw reject(
+          "stale-plan",
+          "review the current setup plan before deciding",
+        );
+      }
       if (plan.status !== "proposed") {
         throw reject("plan-decided", `the plan is already ${plan.status}`);
       }

package/src/protocol.ts

@@ -101,6 +101,7 @@ export namespace Checkout {
     product?: string;
     default?: string;
     help?: InputHelp;
+    redeemKeyHash?: string;
     optional: boolean;
     status: InputStatus;
     answer?: string;
@@ -192,12 +193,16 @@ export namespace Checkout {
     product?: string;
     default?: string;
     help?: InputHelp;
+    redeemKeyHash?: string;
     optional?: boolean;
   };
 
-  export type PlanDecision =
-    | { decision: "approve" }
-    | { decision: "revise"; feedback: string };
+  export type PlanDecision = {
+    /** The setup the browser reviewed; omitted by legacy clients. */
+    id?: string;
+    /** The plan revision the browser reviewed; omitted by legacy clients. */
+    revision?: number;
+  } & ({ decision: "approve" } | { decision: "revise"; feedback: string });
 
   export type Commands = {
     "checkout/create": (params: {
@@ -254,6 +259,7 @@ export namespace Checkout {
     | "plan-required"
     | "no-plan"
     | "plan-decided"
+    | "stale-plan"
     | "finish-not-proposed"
     | "feedback-required"
     | "empty-plan"
@@ -333,11 +339,13 @@ export const parsePreviewUrl = (value: string | undefined) => {
   }
   if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
   if (url.username !== "" || url.password !== "") return undefined;
-  const loopback =
-    LOOPBACK_HOSTS.has(url.hostname) || url.hostname.endsWith(".localhost");
-  return loopback ? url : undefined;
+  return isLoopbackHostname(url.hostname) ? url : undefined;
 };
 
+/** True for a hostname that names this machine. */
+export const isLoopbackHostname = (hostname: string) =>
+  LOOPBACK_HOSTS.has(hostname) || hostname.endsWith(".localhost");
+
 export const openInputs = (state: Checkout.State) =>
   state.inputs.filter((input) => input.status === "open");