@nimbus-dev/connectors 0.2.1 → 0.2.3

package/shared/windows-batch-args.ts

@@ -0,0 +1,273 @@
+/**
+ * windows-batch-args — refuse an argument cmd.exe would act on, when the CLI being spawned may
+ * start a Windows batch file.
+ *
+ * Every spawn in this package passes an argv array with no shell, so on Linux and macOS each
+ * argument reaches the CLI byte for byte. Windows breaks that for one kind of executable. A batch
+ * file — a `.cmd` or `.bat` — cannot be started on its own, so CreateProcess runs it as
+ * `cmd.exe /c <command line>`, and cmd.exe parses the whole command line again before the batch
+ * file sees any of it. `az` and `gcloud` are batch files on Windows. Measured with Bun 1.3.14, which
+ * resolves a bare `az` to `az.cmd` whenever the spawn environment spells the variable `PATH`, and
+ * whose `node:child_process` launches one the same way:
+ *
+ *  - `&`, `|`, `<` and `>` in an argument the runtime did not quote — any argument without a space
+ *    — start a second command, a pipe or a redirection: `x&echo,INJECTED` printed `INJECTED`.
+ *  - `"` ends the quoting the runtime added, so an argument with a space is no defence:
+ *    `q"&echo INJECTED&"` ran the `echo` too.
+ *  - `%NAME%` is replaced by the value of an environment variable even inside quotes, and `!NAME!`
+ *    is too in a batch file that turns on delayed expansion — so a credential in the connector's
+ *    environment would be sent to the cloud API as the argument, where an error could quote it.
+ *  - `(` and `)` close a parenthesised block early. `az.cmd` runs the CLI inside one, and in a
+ *    batch file of that shape an unquoted argument holding `)` is a syntax error — "... was
+ *    unexpected at this time" — before the CLI starts.
+ *  - `^` is consumed as an escape, and a line break ends the command.
+ *
+ * Quoting for cmd.exe is possible, but it is a second grammar layered on the first, with `%` and
+ * `!` that no quote stops; refusing is simpler and can be verified. What the refusal costs was
+ * checked against every value the connectors pass: none of these characters is valid in a GCP or
+ * AWS resource name, an Azure app, cluster or node pool name, or a subscription id. An Azure
+ * resource group may hold `(` and `)`, but never a space, so the runtime never quotes it and
+ * `az.cmd` already failed on it as above. What did work and is now refused: an Azure subscription
+ * passed by a display name holding one of these characters and a space — its id still works — and
+ * a CloudFormation template body, whenever the `aws` that runs is a batch file: a pip-installed v1
+ * found on `PATH` before any `aws.exe`.
+ *
+ * Which file runs is decided the way the runtime decides it — see {@link mayRunAsBatchFile} — so
+ * an `aws.exe` found first is never refused, whatever batch file of that name comes later.
+ *
+ * Node itself never gets this far: it resolves a bare name only to `.com` or `.exe`, and it has
+ * refused to spawn a `.cmd` or `.bat` without a shell since 18.20.2 / 20.12.2 (CVE-2024-27980).
+ * The rule applies to both runtimes all the same, since the check costs nothing where Node would
+ * have refused anyway.
+ */
+
+import { statSync } from "node:fs";
+import { win32 } from "node:path";
+
+/** The characters cmd.exe acts on when it parses a command line again, line breaks aside. */
+const CMD_METACHARACTERS: ReadonlySet<string> = new Set([
+  "%",
+  "!",
+  '"',
+  "&",
+  "|",
+  "<",
+  ">",
+  "^",
+  "(",
+  ")",
+]);
+
+/** The extensions CreateProcess hands to cmd.exe. */
+const BATCH_EXTENSIONS = [".cmd", ".bat"] as const;
+
+/** The extensions Bun tries, in this order, on a name it looks up on Windows. */
+const LOOKUP_EXTENSIONS = [".exe", ".cmd", ".bat"] as const;
+
+/**
+ * The first character of `value` that cmd.exe would act on — one of `% ! " & | < > ^ ( )`, or a
+ * control character such as a line break — or `undefined` when there is none.
+ */
+export function cmdMetacharacterIn(value: string): string | undefined {
+  for (const ch of value) {
+    if (CMD_METACHARACTERS.has(ch) || (ch.codePointAt(0) ?? 0) < 0x20) {
+      return ch;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Whether Windows runs a file of this name through cmd.exe: a `.cmd` or a `.bat`, in any case,
+ * after the trailing dots and spaces Windows drops from a file name — `az.cmd.` opens `az.cmd`.
+ */
+export function isBatchFileName(name: string): boolean {
+  const trimmed = name.replace(/[. ]+$/, "").toLowerCase();
+  return BATCH_EXTENSIONS.some((ext) => trimmed.endsWith(ext));
+}
+
+/**
+ * Whether Bun looks `name` up exactly as written instead of trying extensions on it: when it ends
+ * in `.exe`, `.cmd` or `.bat`, in any case. `.com` is not among them, so `x.com` is looked up as
+ * `x.com.exe`, `x.com.cmd` and `x.com.bat`.
+ */
+function endsWithLookupExtension(name: string): boolean {
+  return /\.(?:exe|cmd|bat)$/i.test(name);
+}
+
+/** The filesystem a batch-file check looks at. Production leaves both to their defaults. */
+export interface BatchFileProbe {
+  /**
+   * Whether a FILE exists at a path. A directory does not count, as it does not for Bun's lookup.
+   * Defaults to a `statSync` check, which follows a link to what it points at.
+   */
+  readonly exists?: (path: string) => boolean;
+  /**
+   * The directory a relative name or `PATH` entry is resolved against. Defaults to
+   * `process.cwd()`: nothing here spawns with a `cwd` of its own.
+   */
+  readonly cwd?: string;
+}
+
+/** Whether a file — not a directory — exists at `path`. */
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The value of each PATH variable of `env` that is set and not empty, in every spelling of its
+ * name: `PATH`, the one Bun reads, and `Path`, which is how Windows spells it and which a copy of
+ * a Windows-launched process's environment keeps.
+ */
+function pathValues(env: Record<string, string | undefined>): string[] {
+  const values: string[] = [];
+  for (const [key, value] of Object.entries(env)) {
+    if (key.toLowerCase() === "path" && value !== undefined && value !== "") {
+      values.push(value);
+    }
+  }
+  return values;
+}
+
+/**
+ * The orders in which a PATH value's directories are searched: its entries as written, which is
+ * how Bun reads them, and — when that differs — with whitespace and surrounding quotes removed
+ * from each, as cmd.exe reads them. An empty entry is skipped, as Bun skips it.
+ */
+function searchOrders(value: string): string[][] {
+  const written = value.split(win32.delimiter).filter((entry) => entry !== "");
+  const cleaned = written
+    .map((entry) => entry.trim().replace(/^"(.*)"$/, "$1"))
+    .filter((entry) => entry !== "");
+  const same =
+    cleaned.length === written.length && cleaned.every((entry, i) => entry === written[i]);
+  return same ? [written] : [written, cleaned];
+}
+
+/**
+ * Whether the first of `bases` that a file `<base>.exe`, `<base>.cmd` or `<base>.bat` exists for
+ * has a `.cmd` or `.bat` one: the lookup stops at the first such place, and that place decides.
+ */
+function firstHolderIsBatch(bases: readonly string[], exists: (path: string) => boolean): boolean {
+  for (const base of bases) {
+    const found = LOOKUP_EXTENSIONS.filter((ext) => exists(base + ext));
+    if (found.length > 0) {
+      return found.some((ext) => ext !== ".exe");
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether spawning `bin` with `env` may start a batch file — whether the file that runs would be a
+ * `.cmd` or a `.bat`.
+ *
+ * That depends on how the runtime turns a name into a file, and this answers it the way Bun does
+ * on Windows: read from its source, unchanged from 1.2.0 to 1.3.14, and held to what the real
+ * lookup does by `windows-batch-args.test.ts` on Windows.
+ *
+ *  - A name ending in `.cmd` or `.bat`, after the trailing dots and spaces Windows drops from a
+ *    file name, is one: every runtime that starts it hands it to cmd.exe.
+ *  - A name ending in `.exe` is looked up as written, and an `.exe` never is one.
+ *  - Bun looks any other name up only when the spawn environment has a non-empty variable spelled
+ *    exactly `PATH`. A bare name is looked for in each of that variable's entries in turn, and a
+ *    name written with a `\` in its own directory alone, each time as `<name>.exe`, `<name>.cmd`
+ *    and `<name>.bat`, and the first file found is what runs. So an `aws.exe` found before any
+ *    `aws.cmd` is not a batch file, whatever comes after it. The current directory is not searched
+ *    for a bare name.
+ *  - Otherwise — and for any name written with a `/` — Bun hands the name to libuv, as Node does,
+ *    and libuv starts only a `.com` or an `.exe`: never a batch file.
+ *
+ * It says yes where Bun could change without notice, and nowhere else: a PATH variable counts in
+ * any spelling, not only `PATH` — today Bun reads no other, and a bare `az` with only `Path` set
+ * does not start at all — and each is searched both as written and with whitespace and quotes
+ * stripped from its entries; a name written with a `/` is looked up in its directory as one with
+ * a `\` is; and the first place holding the name answers yes if it holds a `.cmd` or `.bat` by
+ * that name, even beside an `.exe` Bun would try first.
+ */
+export function mayRunAsBatchFile(
+  bin: string,
+  env: Record<string, string | undefined>,
+  probe: BatchFileProbe = {},
+): boolean {
+  if (isBatchFileName(bin)) {
+    return true;
+  }
+  if (bin === "" || endsWithLookupExtension(bin)) {
+    return false;
+  }
+  const paths = pathValues(env);
+  if (paths.length === 0) {
+    return false;
+  }
+  const exists = probe.exists ?? isFile;
+  const cwd = probe.cwd ?? process.cwd();
+  if (bin.includes("/") || bin.includes("\\")) {
+    return firstHolderIsBatch([win32.resolve(cwd, bin)], exists);
+  }
+  return paths.some((value) =>
+    searchOrders(value).some((dirs) =>
+      firstHolderIsBatch(
+        dirs.map((dir) => win32.resolve(cwd, dir, bin)),
+        exists,
+      ),
+    ),
+  );
+}
+
+/** A character named the way a refusal message can show it. */
+function describeCharacter(ch: string): string {
+  const code = ch.codePointAt(0) ?? 0;
+  return code < 0x20
+    ? `the control character U+${code.toString(16).toUpperCase().padStart(4, "0")}`
+    : JSON.stringify(ch);
+}
+
+/** Options for {@link batchArgumentRefusal}: the filesystem probe, and the platform it applies on. */
+export interface BatchArgumentOptions extends BatchFileProbe {
+  /** Defaults to `process.platform`. The rule applies only on `"win32"`. */
+  readonly platform?: NodeJS.Platform;
+}
+
+/**
+ * Why `command` must not be spawned with `env`, or `undefined` when it may: on Windows, when the
+ * program may start a batch file ({@link mayRunAsBatchFile}) and an argument holds a character
+ * cmd.exe would act on ({@link cmdMetacharacterIn}).
+ *
+ * The arguments are scanned first, so the filesystem is consulted only for a command that would
+ * be refused if its program were a batch file — an ordinary spawn costs no lookups at all. The
+ * message names the argument by position and the character, never the value, which may be long
+ * or private.
+ */
+export function batchArgumentRefusal(
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+  options: BatchArgumentOptions = {},
+): string | undefined {
+  if ((options.platform ?? process.platform) !== "win32") {
+    return undefined;
+  }
+  const [bin, ...args] = command;
+  if (bin === undefined) {
+    return undefined;
+  }
+  for (const [index, arg] of args.entries()) {
+    const ch = cmdMetacharacterIn(arg);
+    if (ch === undefined) {
+      continue;
+    }
+    if (!mayRunAsBatchFile(bin, env, options)) {
+      return undefined;
+    }
+    return (
+      `refused to run ${JSON.stringify(bin)}: it may start a Windows batch file, which cmd.exe ` +
+      `parses again before the CLI sees its arguments, and argument ${String(index + 1)} holds ` +
+      `${describeCharacter(ch)}, which cmd.exe would act on. Nothing was run.`
+    );
+  }
+  return undefined;
+}

package/shared/write-budget.ts

@@ -0,0 +1,100 @@
+/** The variable that sets how many mutations a standalone connector may perform in one session. */
+export const WRITE_BUDGET_ENV = "NIMBUS_MCP_WRITE_BUDGET";
+
+/** Mutations allowed per process lifetime when `NIMBUS_MCP_WRITE_BUDGET` is unset. */
+export const DEFAULT_WRITE_BUDGET = 10;
+
+/**
+ * The largest budget accepted, `2 ** 53 - 1`, which is `Number.MAX_SAFE_INTEGER`.
+ *
+ * Above it a budget stops counting down one mutation at a time: `2 ** 54 - 1` rounds back to
+ * `2 ** 54`, so a budget that large would never run out. That is an unlimited cap spelled as a
+ * number, and it is refused like any other value that cannot be enforced as written.
+ */
+export const MAX_WRITE_BUDGET = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Plain decimal digits: no sign, fraction, exponent, `0x` prefix, separator or `Infinity`. In a
+ * JavaScript regex `\d` is ASCII `0`-`9` only, with or without the `u` flag, so a digit from
+ * another script does not match.
+ */
+const DIGITS = /^\d+$/;
+
+function invalidBudget(raw: string): Error {
+  return new Error(
+    `${WRITE_BUDGET_ENV}=${JSON.stringify(raw)}: expected a whole number of mutations from 0 to ` +
+      `${String(MAX_WRITE_BUDGET)}, where 0 refuses every write; leave it unset for the default, ` +
+      `${String(DEFAULT_WRITE_BUDGET)}`,
+  );
+}
+
+/**
+ * Parse `NIMBUS_MCP_WRITE_BUDGET` into the number of mutations a session may perform.
+ *
+ * STRICT, and an invalid value THROWS at startup, as `parseWriteScope` does on a malformed scope
+ * term. The budget used to be read with `Number()`, and that failed open: `Number("abc")` is
+ * `NaN`, `NaN <= 0` is false, so the budget never ran out. Measured on argocd standalone with 25
+ * approved syncs, unset allowed 10 while `abc`, `ten` and `Infinity` each allowed all 25.
+ *
+ * Throwing rather than falling back to the default is deliberate. A fallback still runs under a
+ * cap the operator did not write, and it can be a LARGER one: an operator who wrote `none` or
+ * `zero` meant no writes at all and would get ten. A typo in a security setting should stop the
+ * connector, which the client reports as a failed server, not be repaired behind a stderr warning
+ * the operator may never see.
+ *
+ * Accepted: unset, meaning `DEFAULT_WRITE_BUDGET`, or plain decimal digits from `0` (every write
+ * refuses) to `MAX_WRITE_BUDGET`, whitespace around them ignored. Everything else throws: a sign,
+ * a fraction (even `10.0`), an exponent, a hex or separator spelling, `Infinity`, a number too
+ * large to count down exactly, and an EMPTY or whitespace-only value. Every other variable in this
+ * package reads empty as unset, but here that reading is not the safe one: `Number("")` is 0, so
+ * an empty budget allowed no writes, and reading it as unset would silently raise it to ten. Empty
+ * is as likely to mean "none" as "the default", so it is refused rather than guessed at.
+ */
+export function parseWriteBudget(raw: string | undefined): number {
+  if (raw === undefined) return DEFAULT_WRITE_BUDGET;
+  const text = raw.trim();
+  // Digits are checked BEFORE `Number()` sees the text: it would read `1e3`, `0x10`, `+5` and
+  // `10.0` as numbers the operator never wrote, `Infinity` as no limit at all, and an empty value
+  // as 0.
+  if (!DIGITS.test(text)) throw invalidBudget(raw);
+  // All digits, so never NaN or negative, but a long enough run of them is above the largest safe
+  // integer or is `Infinity`. Only a safe integer passes, so what comes out can be counted down
+  // exactly, one mutation at a time.
+  const n = Number(text);
+  if (!Number.isSafeInteger(n)) throw invalidBudget(raw);
+  return n;
+}
+
+/**
+ * A session's write budget: how many more mutations it may perform.
+ *
+ * The count lives here and nowhere else, so nothing outside can assign it, and its one check,
+ * `hasLeft`, passes only a positive safe integer. `parseWriteBudget` yields nothing but a safe
+ * whole number, but the check does not rely on that: the count was once tested as
+ * `remaining <= 0`, which is false for NaN, so a NaN count never ran out. Written this way, a NaN,
+ * an `Infinity` or a fraction allows no writes at all, wherever it came from.
+ */
+export type WriteBudget = {
+  /** Whether at least one mutation is left. */
+  hasLeft(): boolean;
+  /**
+   * Spend one mutation if one is left, and report whether one was. The check and the decrement
+   * are one synchronous call, so calls in flight together cannot all pass the check before any
+   * of them spends.
+   */
+  take(): boolean;
+};
+
+/** A budget of `limit` mutations, `limit` being what `parseWriteBudget` returned. */
+export function createWriteBudget(limit: number): WriteBudget {
+  let remaining = limit;
+  const hasLeft = (): boolean => Number.isSafeInteger(remaining) && remaining > 0;
+  return {
+    hasLeft,
+    take(): boolean {
+      if (!hasLeft()) return false;
+      remaining -= 1;
+      return true;
+    },
+  };
+}

package/standalone/src/launcher.ts

@@ -10,7 +10,10 @@ const ID_RE = /^[a-z0-9-]+$/;
  *
  * A registration CALL, or the registrar handed to a shared kit — not a bare substring, which the
  * registrar's own `const registerWriteTool = ...` would satisfy even with nothing registered.
- * Kept in step with the twin in check-connector-consent.ts.
+ *
+ * The ONE copy. `audit:connector-consent` (scripts/check-connector-consent.ts) imports it rather
+ * than keeping a twin, so the launcher's runtime verdict and the audit's static one cannot drift.
+ * They had: the audit's twin learned to tolerate a carriage return (below) and this copy never did.
  *
  * Deliberately NOT a regular expression. The previous pattern was
  * `^\s*register[A-Za-z]*WriteTool\(` under `/m`, and it drew two rounds of ReDoS reports. The
@@ -25,9 +28,15 @@ const ID_RE = /^[a-z0-9-]+$/;
  * bounded work, no star sits next to an overlapping literal, and the accepted language is
  * unchanged — including the trailing-comma form, which still requires the comma to end the line.
  */
-function registersWriteTool(src: string): boolean {
+export function registersWriteTool(src: string): boolean {
   for (const line of src.split("\n")) {
-    const t = line.trimStart();
+    // trim(), not trimStart(): the equality below is exact, and a CRLF checkout leaves a trailing
+    // carriage return that breaks it. Observed in the consent audit on the first run of this repo
+    // on its own, before .gitattributes existed: it reported imap and protonmail as declaring
+    // ungated writes while both register through the kit, on a line reading `registerWriteTool,`
+    // plus a CR. That failed SAFE (a false finding there, a false refusal here — never a false
+    // green), but a verdict that depends on the checkout's line endings is waiting to be wrong.
+    const t = line.trim();
     if (t === "registerWriteTool,") return true;
     if (!t.startsWith("register")) continue;
     const at = t.indexOf("WriteTool(");
@@ -57,13 +66,13 @@ function connectorsDir(): string {
  * The id is validated against a strict allow-list BEFORE being joined into a path. A separator or
  * `..` would otherwise let the id escape the connectors directory and import an arbitrary module.
  */
-export function resolveConnectorEntry(id: string): string {
+export function resolveConnectorEntry(id: string, root: string = connectorsDir()): string {
   if (!ID_RE.test(id)) {
     throw new Error(
       `invalid connector id ${JSON.stringify(id)}: expected only lowercase letters, digits and hyphens`,
     );
   }
-  return join(connectorsDir(), id, "src", "server.ts");
+  return join(root, id, "src", "server.ts");
 }
 
 export type Eligibility =
@@ -154,6 +163,9 @@ export type ConnectorImporter = (entry: string) => Promise<{
 export async function runStandalone(
   argv: readonly string[],
   importConnector: ConnectorImporter = (entry) => import(entry),
+  // Injectable for the same reason as standaloneEligibility's root: every real connector is
+  // migrated, so only a fixture can show the refusal path end to end.
+  root: string = connectorsDir(),
 ): Promise<number> {
   const id = argv[0];
   if (id === undefined) {
@@ -162,7 +174,7 @@ export async function runStandalone(
   }
   let entry: string;
   try {
-    entry = resolveConnectorEntry(id);
+    entry = resolveConnectorEntry(id, root);
   } catch (e) {
     process.stderr.write(`${e instanceof Error ? e.message : String(e)}\n`);
     return 2;
@@ -172,7 +184,7 @@ export async function runStandalone(
     return 2;
   }
 
-  const verdict = standaloneEligibility(id);
+  const verdict = standaloneEligibility(id, root);
   if (!verdict.eligible) {
     process.stderr.write(`${verdict.reason}\n`);
     return 3;