@nimbus-dev/connectors 0.1.0

package/shared/run-cli-json.ts

@@ -0,0 +1,55 @@
+import { nimbusSpawn } from "./nimbus-spawn.ts";
+
+export type RunCliJsonResult = { ok: true; data: unknown } | { ok: false; message: string };
+
+export async function runCliOk(
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+): Promise<{ ok: true } | { ok: false; message: string }> {
+  if (command.length === 0) {
+    return { ok: false, message: "empty command" };
+  }
+  const { code, stderr: err } = await nimbusSpawn(command, env);
+  if (code !== 0) {
+    return {
+      ok: false,
+      message: `${command[0] ?? "cli"} exited ${String(code)}: ${err.slice(0, 500)}`,
+    };
+  }
+  return { ok: true };
+}
+
+export async function runCliOkThrowing(
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+): Promise<void> {
+  const r = await runCliOk(command, env);
+  if (!r.ok) {
+    throw new Error(r.message);
+  }
+}
+
+export async function runCliJson(
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+): Promise<RunCliJsonResult> {
+  if (command.length === 0) {
+    return { ok: false, message: "empty command" };
+  }
+  const { code, stdout: out, stderr: err } = await nimbusSpawn(command, env);
+  if (code !== 0) {
+    return {
+      ok: false,
+      message: `${command[0] ?? "cli"} exited ${String(code)}: ${err.slice(0, 500)}`,
+    };
+  }
+  const trimmed = out.trim();
+  if (trimmed === "") {
+    return { ok: true, data: null };
+  }
+  try {
+    return { ok: true, data: JSON.parse(trimmed) as unknown };
+  } catch {
+    return { ok: false, message: `invalid JSON from CLI: ${out.slice(0, 200)}` };
+  }
+}

package/shared/run-read-only-mcp-connector.ts

@@ -0,0 +1,59 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  type McpListResult,
+  type ZodObjectSchema,
+} from "./mcp-tool-kit.ts";
+
+export type ZodToolRegistrar = <T>(
+  name: string,
+  description: string,
+  schema: ZodObjectSchema<T>,
+  handler: (args: T) => Promise<McpListResult>,
+) => void;
+
+export interface BuildReadOnlyMcpConnectorOptions {
+  readonly createServer?: (info: { readonly name: string; readonly version: string }) => unknown;
+}
+
+/**
+ * `createTransport` mirrors the existing `createServer` seam. Without it the
+ * stdio transport was constructed inline, so `runReadOnlyMcpConnector` — the
+ * function every connector's entry point actually calls — could not be executed
+ * from a test at all: it would have opened a real stdio transport on the test
+ * process. That left the wiring between server and transport asserted nowhere.
+ *
+ * Production callers pass nothing and get the real `StdioServerTransport`.
+ */
+export interface RunReadOnlyMcpConnectorOptions extends BuildReadOnlyMcpConnectorOptions {
+  readonly createTransport?: () => unknown;
+}
+
+export function buildReadOnlyMcpConnector(
+  serverName: string,
+  // The SERVER is passed to `register` as a second argument. Despite this helper's name, several
+  // of its connectors expose write tools, and those need the real server to build a consent
+  // registrar — the read-only registrar alone cannot reach capabilities, registerTool or logging.
+  // Optional in the callback's own signature, so the many genuinely read-only connectors that
+  // ignore it are unaffected.
+  register: (reg: ZodToolRegistrar, server: unknown) => void,
+  options?: BuildReadOnlyMcpConnectorOptions,
+): unknown {
+  const make = options?.createServer ?? ((info) => new McpServer(info));
+  const mcp = make({ name: serverName, version: "0.1.0" });
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
+  register(reg, mcp);
+  return mcp;
+}
+
+export async function runReadOnlyMcpConnector(
+  serverName: string,
+  register: (reg: ZodToolRegistrar, server: unknown) => void,
+  options?: RunReadOnlyMcpConnectorOptions,
+): Promise<void> {
+  const mcp = buildReadOnlyMcpConnector(serverName, register, options) as McpServer;
+  const makeTransport = options?.createTransport ?? ((): unknown => new StdioServerTransport());
+  await mcp.connect(makeTransport() as StdioServerTransport);
+}

package/shared/safe-cli-arg.ts

@@ -0,0 +1,55 @@
+/**
+ * Guard a tool-supplied value before it is passed as an argument to a spawned CLI
+ * (`gcloud` / `aws` / `bq` / …).
+ *
+ * Spawns use an argv array (no shell), so there is no classic shell injection — but
+ * a value that begins with `-` would be parsed by the CLI as a FLAG rather than a
+ * positional / flag-value. This "argv flag smuggling" lets tool input inject
+ * arbitrary CLI flags (e.g. a `sinkName` of `--project=attacker` or `-h`). Reject
+ * any value that is empty, over-long, starts with `-`, or contains control
+ * characters.
+ *
+ * Resource-id charsets vary per service (sink ids are `[A-Za-z0-9_.-]`, CloudWatch
+ * log-group names contain `/`, BigQuery refs contain `.`), so this is the UNIVERSAL
+ * guard against flag smuggling; callers may layer a stricter per-resource regex on
+ * top. Returns the value unchanged so it can be used inline:
+ * `cli(["describe", assertSafeCliArg(p.id, "id")])`.
+ *
+ * @throws {Error} when the value is unsafe to pass as a CLI argument.
+ */
+export function assertSafeCliArg(value: string, label = "argument"): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Invalid ${label}: must be a non-empty string`);
+  }
+  if (value.length > 1024) {
+    throw new Error(`Invalid ${label}: exceeds 1024 characters`);
+  }
+  if (value.startsWith("-")) {
+    throw new Error(
+      `Invalid ${label}: must not start with "-" (argv flag smuggling is not allowed)`,
+    );
+  }
+  for (let i = 0; i < value.length; i += 1) {
+    if ((value.codePointAt(i) ?? 0) < 0x20) {
+      throw new Error(`Invalid ${label}: must not contain control characters`);
+    }
+  }
+  return value;
+}
+
+/**
+ * Non-throwing predicate form of {@link assertSafeCliArg}, for use in a Zod
+ * `.refine(...)` so a `-`-prefixed / control-char value is rejected at the tool's
+ * schema boundary before the handler ever shells out.
+ */
+export function isSafeCliArg(value: unknown): value is string {
+  if (typeof value !== "string") {
+    return false;
+  }
+  try {
+    assertSafeCliArg(value);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/shared/search-filter.ts

@@ -0,0 +1,140 @@
+export interface SearchMatchOptions {
+  readonly query: string;
+  readonly limit?: number | undefined;
+}
+
+export interface FilterByQueryOptions<T> {
+  readonly query: string;
+  readonly limit?: number | undefined;
+  readonly fields: (item: T) => readonly (string | null | undefined)[] | null;
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as Record<string, unknown>;
+}
+
+export function asObjectish(value: unknown): Record<string, unknown> | undefined {
+  if (value === null || typeof value !== "object") {
+    return undefined;
+  }
+  return value as Record<string, unknown>;
+}
+
+export function stringField(row: Record<string, unknown>, key: string): string {
+  const v = row[key];
+  return typeof v === "string" ? v : "";
+}
+
+export function tagText(row: Record<string, unknown>): string {
+  const tags = row["tags"];
+  if (!Array.isArray(tags)) {
+    return "";
+  }
+  const names: string[] = [];
+  for (const t of tags) {
+    if (typeof t === "string") {
+      names.push(t);
+    }
+  }
+  return names.join(" ");
+}
+
+/**
+ * Extract tag names from an array of `{name: string}` tag objects (e.g. Airflow, DependencyTrack).
+ * Returns "" when `tags` is absent, not an array, or contains no object entries with a string `name`.
+ */
+export function tagNamesFromObjects(row: Record<string, unknown>): string {
+  const tags = row["tags"];
+  if (!Array.isArray(tags)) {
+    return "";
+  }
+  const names: string[] = [];
+  for (const t of tags) {
+    const tag = asObjectish(t);
+    if (tag === undefined) {
+      continue;
+    }
+    const name = tag["name"];
+    if (typeof name === "string" && name !== "") {
+      names.push(name);
+    }
+  }
+  return names.join(" ");
+}
+
+export function filterByQuery<T>(items: readonly T[], options: FilterByQueryOptions<T>): T[] {
+  const needle = options.query.toLowerCase();
+  const cap = options.limit ?? 50;
+  const out: T[] = [];
+  for (const item of items) {
+    const parts = options.fields(item);
+    if (parts === null) {
+      continue;
+    }
+    const haystack = parts.join(" ").toLowerCase();
+    if (!haystack.includes(needle)) {
+      continue;
+    }
+    out.push(item);
+    if (out.length >= cap) {
+      break;
+    }
+  }
+  return out;
+}
+
+export type FieldExtractor = (item: unknown) => readonly (string | null | undefined)[] | null;
+
+/**
+ * Build a {@link FieldExtractor} that reads a fixed list of string keys off each
+ * objectish row, optionally appending the standard `tags` text. Collapses the
+ * boilerplate `fieldsOf` body shared by the simpler connectors.
+ */
+export function fieldsFromKeys(
+  keys: readonly string[],
+  opts?: { readonly tags?: boolean },
+): FieldExtractor {
+  return (item: unknown) => {
+    const row = asObjectish(item);
+    if (row === undefined) {
+      return null;
+    }
+    const parts = keys.map((key) => stringField(row, key));
+    if (opts?.tags === true) {
+      parts.push(tagText(row));
+    }
+    return parts;
+  };
+}
+
+/**
+ * Read a nested string field by key path off an objectish row, returning `""`
+ * when any path segment is missing or the leaf is not a string. Shared by the
+ * Kubernetes-style connectors (argocd, flux) whose resources nest fields under
+ * `metadata` / `spec` / `status`.
+ */
+export function nestedString(root: Record<string, unknown>, path: readonly string[]): string {
+  let cur: Record<string, unknown> | undefined = root;
+  for (let i = 0; i < path.length - 1; i += 1) {
+    cur = asRecord(cur?.[path[i] ?? ""]);
+    if (cur === undefined) {
+      return "";
+    }
+  }
+  const leaf = cur?.[path.at(-1) ?? ""];
+  return typeof leaf === "string" ? leaf : "";
+}
+
+/**
+ * Build a `filter<Thing>(items, options)` search function from a field
+ * extractor. Connectors with bespoke extraction pass their own `fieldsOf`;
+ * simple ones pair this with {@link fieldsFromKeys}.
+ */
+export function makeQueryFilter(
+  fields: FieldExtractor,
+): (items: readonly unknown[], options: SearchMatchOptions) => unknown[] {
+  return (items, options) => filterByQuery(items, { ...options, fields });
+}

package/shared/strip-trailing-slashes.ts

@@ -0,0 +1,7 @@
+export function stripTrailingSlashes(input: string): string {
+  let s = input.trim();
+  while (s.endsWith("/")) {
+    s = s.slice(0, -1);
+  }
+  return s;
+}

package/shared/write-scope.ts

@@ -0,0 +1,58 @@
+/**
+ * A single allow-list term, e.g. `repo:acme/api` or `dataset:proj.analytics`.
+ *
+ * `owner/repo` reads naturally for GitHub and generalises to nothing else — BigQuery, Notion, Slack
+ * and Jira have no such shape. Left per-connector this would drift into ~34 private syntaxes, so
+ * every scope term is typed.
+ */
+export type ScopeTerm = { readonly kind: string; readonly value: string };
+
+/**
+ * Parse `NIMBUS_MCP_<SERVICE>_WRITE_SCOPE` into terms, rejecting any kind the connector did not
+ * declare.
+ *
+ * An unknown kind THROWS at startup rather than parsing into a term that can never match. A rule
+ * that silently never matches is indistinguishable from no rule at all, which fails open — the one
+ * outcome an allow-list must never have.
+ */
+export function parseWriteScope(
+  raw: string | undefined,
+  allowedKinds: readonly string[],
+): readonly ScopeTerm[] {
+  if (raw === undefined || raw.trim() === "") return [];
+  const allowed = new Set(allowedKinds);
+  const out: ScopeTerm[] = [];
+  for (const piece of raw.split(",")) {
+    const term = piece.trim();
+    if (term === "") continue;
+    const sep = term.indexOf(":");
+    if (sep === -1) {
+      throw new Error(`write scope term ${JSON.stringify(term)}: expected "kind:value"`);
+    }
+    const kind = term.slice(0, sep);
+    // Not `split(":")` — a value may itself contain colons and must survive intact.
+    const value = term.slice(sep + 1).trim();
+    if (!allowed.has(kind)) {
+      throw new Error(
+        `write scope term ${JSON.stringify(term)}: unknown scope kind ${JSON.stringify(kind)}; ` +
+          `this connector accepts: ${allowedKinds.join(", ")}`,
+      );
+    }
+    if (value === "") {
+      throw new Error(`write scope term ${JSON.stringify(term)}: empty value`);
+    }
+    out.push({ kind, value });
+  }
+  return out;
+}
+
+/**
+ * Whether the scope authorises one target. Exact match on both fields.
+ *
+ * An EMPTY scope denies everything: "unset" must mean "no mutations authorised", never
+ * "unrestricted". Prefix matching is deliberately absent — `acme/api` must not authorise
+ * `acme/api-secrets`.
+ */
+export function scopeAllows(scope: readonly ScopeTerm[], kind: string, value: string): boolean {
+  return scope.some((t) => t.kind === kind && t.value === value);
+}

package/standalone/src/bin.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+import { runStandalone } from "./launcher.ts";
+
+/**
+ * The `nimbus-connector` process entry point, and nothing else.
+ *
+ * Split from `launcher.ts` so that file stays pure, fully testable logic. An `import.meta.main`
+ * block cannot be exercised in-process by any test, so leaving it inside the launcher would have
+ * meant either an uncoverable branch or exempting the eligibility logic from coverage with it —
+ * and the eligibility logic is the part worth covering.
+ */
+const code = await runStandalone(process.argv.slice(2));
+// Exit ONLY on failure. Most connectors connect their stdio transport at module scope, so the
+// import inside runStandalone resolves once the server is live and it returns 0 immediately —
+// `process.exit(0)` here would tear down the server it just started. On success we fall through
+// and the connected transport keeps the process alive.
+if (code !== 0) {
+  process.exit(code);
+}

package/standalone/src/launcher.ts

@@ -0,0 +1,186 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Connector ids are directory names: lowercase letters, digits and hyphens only. */
+const ID_RE = /^[a-z0-9-]+$/;
+
+/**
+ * Does this source register a write tool?
+ *
+ * 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.
+ *
+ * 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
+ * first was real: `\s` matches a newline, so under `/m` a run of n newlines gave n start
+ * positions each able to consume the whole run — quadratic, measured at 21s for 128k newlines.
+ * Narrowing the class to horizontal whitespace made it linear, and bounding the star to
+ * `{0,40}` kept it linear, but `typescript:S8786` reported both: a star immediately followed by
+ * a literal built from the same character class is the shape the rule looks for, bounded or not,
+ * and the shape is worth avoiding even where this engine happens not to backtrack.
+ *
+ * Scanning line by line removes the construct rather than arguing with the analyser. Each line is
+ * 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 {
+  for (const line of src.split("\n")) {
+    const t = line.trimStart();
+    if (t === "registerWriteTool,") return true;
+    if (!t.startsWith("register")) continue;
+    const at = t.indexOf("WriteTool(");
+    if (at < 0) continue;
+    // Everything between `register` and `WriteTool(` must be letters, so `registerFoo.WriteTool(`
+    // does not count. Anchored at BOTH ends with nothing following, so it carries none of the
+    // ambiguity the old pattern did.
+    if (/^[A-Za-z]*$/.test(t.slice("register".length, at))) return true;
+  }
+  return false;
+}
+
+/**
+ * The directory holding the 94 connector packages.
+ *
+ * `standalone/src/` -> repo root -> `connectors/`. This used to be just `../..`, back when the
+ * connectors sat directly at the repo root alongside `shared/` and `standalone/` — 97 top-level
+ * entries, which is why they were nested.
+ */
+function connectorsDir(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "connectors");
+}
+
+/**
+ * Resolve a connector id to its server entrypoint.
+ *
+ * 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 {
+  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");
+}
+
+export type Eligibility =
+  | { readonly eligible: true; readonly reason: "no-writes" | "hardened" }
+  | { readonly eligible: false; readonly reason: string };
+
+/**
+ * Whether a connector may run STANDALONE.
+ *
+ * Derived, never curated. A connector qualifies when it declares no mutating capability at all, or
+ * when its write tools have been routed through the consent kit. Anything else would expose
+ * ungated destructive tools the moment it started outside the gateway — the exact outcome this
+ * whole subsystem exists to prevent — so the launcher refuses to start it.
+ *
+ * `hitlRequired` is the AUTHORITATIVE signal, and deliberately the only one. It is authored per
+ * connector and transport independent: ten connectors mutate through a CLI, the filesystem or a
+ * mail protocol, where no scan of the source could see them.
+ *
+ * Scanning for a mutating HTTP verb was tried here and REMOVED. It cannot decide this question in
+ * either direction: seven read-only connectors POST for GraphQL queries, filter endpoints, OAuth
+ * token exchange and login (dagster, google-photos, prefect, ramp, snyk, superset, wiz), so the
+ * verb wrongly refused all seven; and it is blind to the ten that never issue an HTTP request at
+ * all. A connector that mutates without declaring it is a CONNECTOR BUG, caught at authoring time
+ * by `registerWriteTool` and its audit — not by a runtime heuristic that provably cannot tell.
+ *
+ * An unreadable manifest is treated as declaring a write. The cost is refusing one connector that
+ * might have been fine; the alternative is starting one that is not.
+ */
+export function standaloneEligibility(
+  id: string,
+  // Injectable root so a test can point at a fixture. Tests previously used a real connector as
+  // their "unmigrated" example and broke the moment it was migrated — a test whose meaning depends
+  // on unrelated work is a test that will lie eventually.
+  root: string = connectorsDir(),
+): Eligibility {
+  const dir = join(root, id);
+  let declaresWrite: boolean;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(dir, "nimbus.extension.json"), "utf8"));
+    const hitl =
+      typeof parsed === "object" && parsed !== null
+        ? (parsed as Record<string, unknown>)["hitlRequired"]
+        : undefined;
+    declaresWrite = Array.isArray(hitl) && hitl.some((h) => h === "write" || h === "delete");
+  } catch {
+    declaresWrite = true;
+  }
+  if (!declaresWrite) return { eligible: true, reason: "no-writes" };
+
+  // BOTH entrypoint files. 16 connectors register their tools in `src/tools.ts` rather than
+  // `src/server.ts` — apple, fastmail, imap, protonmail and the CLI-backed cloud ones among them —
+  // so reading only server.ts would refuse a connector that IS hardened, in tools.ts.
+  let src = "";
+  for (const f of ["server.ts", "tools.ts"]) {
+    try {
+      src += readFileSync(join(dir, "src", f), "utf8");
+    } catch {
+      /* a connector need not have both; an unreadable pair falls through to the refusal below */
+    }
+  }
+
+  if (registersWriteTool(src)) {
+    return { eligible: true, reason: "hardened" };
+  }
+
+  return {
+    eligible: false,
+    reason:
+      `${id} declares write or delete tools in its manifest that have not been routed through ` +
+      "the consent kit, " +
+      "so running it standalone would expose ungated mutations. Run it through the Nimbus " +
+      "gateway, which gates them, until this connector is migrated.",
+  };
+}
+
+/** How a connector entrypoint is loaded. Injectable so tests need not import a real stdio server. */
+export type ConnectorImporter = (entry: string) => Promise<{
+  startConnector?: (() => Promise<void>) | undefined;
+}>;
+
+/**
+ * Start one connector standalone.
+ *
+ * Deliberately does NOT call `setConnectorMode("standalone")`. Standalone is the DEFAULT, so
+ * asserting it here would add a second production caller — which the `audit:connector-consent`
+ * gate forbids — while changing nothing. Do not "fix" this omission.
+ */
+export async function runStandalone(
+  argv: readonly string[],
+  importConnector: ConnectorImporter = (entry) => import(entry),
+): Promise<number> {
+  const id = argv[0];
+  if (id === undefined) {
+    process.stderr.write("usage: nimbus-connector <connector-id>\n");
+    return 2;
+  }
+  let entry: string;
+  try {
+    entry = resolveConnectorEntry(id);
+  } catch (e) {
+    process.stderr.write(`${e instanceof Error ? e.message : String(e)}\n`);
+    return 2;
+  }
+  if (!existsSync(entry)) {
+    process.stderr.write(`unknown connector ${JSON.stringify(id)}\n`);
+    return 2;
+  }
+
+  const verdict = standaloneEligibility(id);
+  if (!verdict.eligible) {
+    process.stderr.write(`${verdict.reason}\n`);
+    return 3;
+  }
+
+  const mod = await importConnector(entry);
+  // Mirrors run-bundled-connector.ts: most connectors connect their transport at module scope, ten
+  // guard on import.meta.main and export startConnector() instead.
+  await mod.startConnector?.();
+  return 0;
+}

package/standalone/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["bun"]
+  },
+  "include": ["src/**/*", "../shared/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}