@nimbus-dev/connectors 0.1.0

package/shared/connector-mode.ts

@@ -0,0 +1,60 @@
+/**
+ * Which entrypoint started this connector process, and therefore whether the connector's own
+ * consent gate is in force.
+ *
+ * `"gateway"` — started by `run-bundled-connector.ts` as the gateway's `__nimbus-connector` role.
+ * The gateway's executor provides HITL (I2), so the connector registers its full tool surface.
+ *
+ * `"standalone"` — anything else. The connector hardens itself: write tools register only behind a
+ * client that can prompt a human, and every mutation is scope-checked, budgeted and audited.
+ *
+ * Standalone is the DEFAULT deliberately. If the gateway's one wiring line is ever lost, the
+ * gateway degrades to read-only — loud and safe — rather than the standalone build silently
+ * ungating. The failure mode must point that way.
+ *
+ * The mode is derived from which entrypoint ran, never from an env var: Non-Negotiable #2 forbids a
+ * consent gate that can be "configured away", and an env var in a client's JSON config is exactly
+ * that.
+ */
+export type ConnectorMode = "gateway" | "standalone";
+
+let current: ConnectorMode | undefined;
+
+/**
+ * Lock the mode for this process.
+ *
+ * Set-once: re-asserting the same value is a no-op, but a CONFLICTING change throws. Reading via
+ * `getConnectorMode` also locks, so a gateway wire that runs too late — after a connector module
+ * has already registered tools against the default — fails loudly instead of leaving a surface that
+ * half-registered under one mode and half under another.
+ */
+export function setConnectorMode(mode: ConnectorMode): void {
+  if (current !== undefined && current !== mode) {
+    throw new Error(
+      `connector mode already locked to "${current}"; refusing to change it to "${mode}"`,
+    );
+  }
+  current = mode;
+}
+
+/** The active mode, locking in the standalone default on first read. */
+export function getConnectorMode(): ConnectorMode {
+  current ??= "standalone";
+  return current;
+}
+
+/**
+ * TEST-ONLY: clear the lock between cases. Never called from production code — the
+ * `audit:connector-consent` gate permits `setConnectorMode` only in the two sanctioned entrypoints,
+ * and this function exists so tests never need to reach for it.
+ *
+ * This matters more than it looks. `bun test` runs MANY TEST FILES IN ONE PROCESS — verified: two
+ * files sharing a module observed the same pid, and state set by the first was visible to the
+ * second. So a file that locks the mode and does not clear it changes the behaviour of every file
+ * that runs after it. Any test file that touches the mode must reset in BOTH `beforeEach` and
+ * `afterEach`: `beforeEach` protects this file from its predecessors, `afterEach` protects the
+ * suite from this one.
+ */
+export function resetConnectorModeForTests(): void {
+  current = undefined;
+}

package/shared/consent-kit.ts

@@ -0,0 +1,323 @@
+import type { McpListResult, ZodObjectSchema } from "@nimbus-dev/sdk/connector-kit";
+
+import { type AuditOutcome, appendAuditEntry } from "./audit-chain.ts";
+import { getConnectorMode } from "./connector-mode.ts";
+import { parseWriteScope, scopeAllows } from "./write-scope.ts";
+
+/** Mutations allowed per process lifetime when NIMBUS_MCP_WRITE_BUDGET is unset. */
+const DEFAULT_BUDGET = 10;
+
+/** The subset of the SDK's `RegisteredTool` this kit needs. */
+export type ToolHandle = { disable(): void };
+
+/**
+ * The structural subset of `McpServer` the consent kit uses.
+ *
+ * Narrowed deliberately so tests can supply a fake without a transport, and so the kit's real
+ * dependencies are visible in one place.
+ */
+export type ConsentServer = {
+  readonly server: {
+    getClientCapabilities(): { elicitation?: unknown } | undefined;
+    /** Fired after the client's `initialize` — the FIRST moment capabilities are knowable. */
+    oninitialized?: (() => void) | undefined;
+    /**
+     * `requestedSchema` is typed to the restricted JSON-Schema subset the MCP spec allows, not
+     * `Record<string, unknown>`. The loose form does not satisfy the real `McpServer.elicitInput`,
+     * which is only discoverable by passing a real server — a hand-written fake accepts anything.
+     */
+    elicitInput(
+      params: {
+        mode: "form";
+        message: string;
+        requestedSchema: {
+          type: "object";
+          properties: Record<
+            string,
+            { type: "boolean"; title?: string; description?: string; default?: boolean }
+          >;
+          required?: string[];
+        };
+      },
+      options?: { timeout?: number },
+    ): Promise<{
+      action: "accept" | "decline" | "cancel";
+      content?: Record<string, unknown> | undefined;
+    }>;
+  };
+  /**
+   * `inputSchema` is `unknown` on purpose. The real signature wants the SDK's
+   * `ZodRawShapeCompat | AnySchema`, and the connector kit's `ZodObjectSchema["shape"]` is
+   * `Record<string, unknown>` — neither is assignable to the other, so a concrete type here makes
+   * a real `McpServer` fail to satisfy this interface. The value is passed straight through and
+   * never inspected by this kit.
+   */
+  registerTool(
+    name: string,
+    config: { description?: string; inputSchema?: unknown },
+    cb: (args: unknown) => Promise<McpListResult>,
+  ): ToolHandle;
+  sendToolListChanged(): void;
+  sendLoggingMessage(params: { level: "info" | "warning"; data: unknown }): Promise<void>;
+};
+
+export type WriteToolConfig<T> = {
+  /** Action type this tool performs, e.g. "repo.branch.delete". Machine-readable, not prose. */
+  readonly mutates: string;
+  /** False when the mutation cannot be undone — which is when pre-state capture is mandatory. */
+  readonly recoverable: boolean;
+  /** Required when `recoverable` is false. Runs BEFORE the mutation; result is audited verbatim. */
+  readonly capturePreState?: (args: T) => Promise<Record<string, unknown>>;
+  /** The scope target this invocation would touch, checked against the allow-list. */
+  readonly scopeTargetOf: (args: T) => { kind: string; value: string };
+};
+
+export type WriteToolRegistrar = <T>(
+  name: string,
+  cfg: WriteToolConfig<T>,
+  description: string,
+  schema: ZodObjectSchema<T>,
+  handler: (args: T) => Promise<McpListResult>,
+) => void;
+
+function refused(why: string): McpListResult {
+  return { content: [{ type: "text", text: JSON.stringify({ ok: false, error: why }) }] };
+}
+
+/**
+ * Ask the human, through the client, and report whether they said yes.
+ *
+ * The prompt carries the VERBATIM operation and resolved parameters, never a digest — a digest is
+ * a rubber stamp with extra steps, and the human is the entire trust boundary here.
+ */
+async function consented(
+  server: ConsentServer,
+  mutates: string,
+  params: unknown,
+): Promise<boolean> {
+  let res: { action: string; content?: Record<string, unknown> | undefined };
+  try {
+    res = await server.server.elicitInput({
+      mode: "form",
+      message:
+        `Nimbus is about to perform ${mutates} with:\n` +
+        `${JSON.stringify(params, null, 2)}\n\nApprove?`,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          confirm: { type: "boolean", title: "Approve this action", description: mutates },
+        },
+        required: ["confirm"],
+      },
+    });
+  } catch {
+    // Timeout, transport failure, or a client that rejects the request: fail CLOSED.
+    return false;
+  }
+  // `action: "accept"` alone is not consent — the form's own answer must also be true, so a client
+  // that auto-accepts without answering the question does not clear the gate.
+  return res.action === "accept" && res.content?.["confirm"] === true;
+}
+
+function registerOn<T>(
+  server: ConsentServer,
+  name: string,
+  description: string,
+  schema: ZodObjectSchema<T>,
+  handler: (args: T) => Promise<McpListResult>,
+  handles: ToolHandle[],
+): void {
+  const handle = server.registerTool(
+    name,
+    { description, inputSchema: schema.shape },
+    async (args: unknown): Promise<McpListResult> => {
+      const parsed = schema.safeParse(args);
+      if (!parsed.success) {
+        throw new Error(parsed.error.message);
+      }
+      return handler(parsed.data);
+    },
+  );
+  // Collected so budget exhaustion can disable every write tool at once.
+  handles.push(handle);
+}
+
+/**
+ * Build a connector's write-tool registrar.
+ *
+ * In `"gateway"` mode the raw handler is registered immediately: `executor.ts` (I2) is the gate
+ * there, client capabilities are irrelevant, and the connector adds nothing.
+ *
+ * In `"standalone"` mode registration is QUEUED and flushed on `oninitialized`, because client
+ * capabilities are not knowable at module scope — verified against the real SDK, where
+ * `getClientCapabilities()` returns `undefined` before `initialize`. Deciding at registration time
+ * would register nothing, for every client, forever.
+ */
+export function createWriteToolRegistrar(
+  server: ConsentServer,
+  cfg: {
+    readonly connector: string;
+    readonly scopeEnv: string;
+    /**
+     * Scope kinds this connector accepts. Declared once per connector rather than per tool: the
+     * allow-list is parsed at registrar construction, before any tool has registered, so a
+     * per-tool declaration would arrive too late to validate the env value.
+     */
+    readonly scopeKinds: readonly string[];
+  },
+): WriteToolRegistrar {
+  const handles: ToolHandle[] = [];
+  const pending: Array<() => void> = [];
+  let flushed = false;
+
+  const scope = parseWriteScope(process.env[cfg.scopeEnv], cfg.scopeKinds);
+  const auditLog = process.env["NIMBUS_MCP_AUDIT_LOG"];
+  let remaining = Number(process.env["NIMBUS_MCP_WRITE_BUDGET"] ?? DEFAULT_BUDGET);
+
+  async function record(
+    tool: string,
+    outcome: AuditOutcome,
+    detail: Record<string, unknown>,
+  ): Promise<void> {
+    // Client-visible channel: any MCP client can display or persist this.
+    await server.sendLoggingMessage({
+      level: outcome === "executed" ? "info" : "warning",
+      data: { connector: cfg.connector, tool, outcome },
+    });
+    // Durable channel: only when the operator configured a path.
+    if (auditLog !== undefined && auditLog !== "") {
+      await appendAuditEntry(auditLog, {
+        ts: new Date().toISOString(),
+        connector: cfg.connector,
+        tool,
+        outcome,
+        detail,
+      });
+    }
+  }
+
+  /**
+   * Decide the write surface, once, at the first moment client capabilities are knowable.
+   *
+   * Default-DENY: if the client cannot prompt a human, the queued tools are dropped and never
+   * appear in `tools/list` at all. Refusing at call time instead would still advertise a tool the
+   * model must not use.
+   */
+  function flushWriteTools(): void {
+    if (flushed) return;
+    flushed = true;
+    const caps = server.server.getClientCapabilities();
+    if (caps?.elicitation === undefined) {
+      pending.length = 0;
+      return;
+    }
+    for (const register of pending) register();
+    pending.length = 0;
+    // The tool list changed after `initialize`, so the client must be told to re-read it.
+    if (handles.length > 0) server.sendToolListChanged();
+  }
+
+  if (getConnectorMode() === "standalone") {
+    // An empty scope denies every mutation, which is the correct default but looks identical to a
+    // broken connector from the outside. Say so on stderr — safe for a stdio server, whose
+    // PROTOCOL channel is stdout; writing this to stdout would corrupt the JSON-RPC stream.
+    if (scope.length === 0) {
+      process.stderr.write(
+        `nimbus-connector ${cfg.connector}: ${cfg.scopeEnv} is unset or empty, so every write tool ` +
+          `will refuse. Set it to a comma-separated list of ${cfg.scopeKinds.join("|")}:value ` +
+          "terms to enable writes.\n",
+      );
+    }
+    // Chain rather than overwrite: another module may already own this hook, and clobbering it
+    // would silently disable whatever it did.
+    const prev = server.server.oninitialized;
+    server.server.oninitialized = (): void => {
+      prev?.();
+      flushWriteTools();
+    };
+  }
+
+  return <T>(
+    name: string,
+    toolCfg: WriteToolConfig<T>,
+    description: string,
+    schema: ZodObjectSchema<T>,
+    handler: (args: T) => Promise<McpListResult>,
+  ): void => {
+    // Checked at REGISTRATION, not on first call: a missing capture on a destructive tool is a
+    // programming error, and it must surface at boot rather than on the one call that needed it.
+    if (!toolCfg.recoverable && toolCfg.capturePreState === undefined) {
+      throw new Error(
+        `${name}: capturePreState is required when recoverable is false — an unrecoverable ` +
+          "mutation must record enough pre-state to be undone",
+      );
+    }
+
+    if (getConnectorMode() === "gateway") {
+      registerOn(server, name, description, schema, handler, handles);
+      return;
+    }
+
+    const guarded = async (args: T): Promise<McpListResult> => {
+      const target = toolCfg.scopeTargetOf(args);
+
+      // 1. SCOPE FIRST — before prompting. Asking a human to approve something the operator
+      //    already forbade cannot change the outcome, and training people to click through
+      //    prompts that do not matter is how you make the prompts that do matter ineffective.
+      if (!scopeAllows(scope, target.kind, target.value)) {
+        await record(name, "refused", { reason: "out of scope", target });
+        return refused(`out of scope: ${target.kind}:${target.value} is not in ${cfg.scopeEnv}`);
+      }
+
+      // 2. BUDGET — same reasoning: a refusal that consent cannot lift comes before consent.
+      if (remaining <= 0) {
+        await record(name, "refused", { reason: "budget exhausted", target });
+        return refused("write budget exhausted for this session");
+      }
+
+      // 3. CONSENT.
+      await record(name, "requested", { target, params: args });
+      if (!(await consented(server, toolCfg.mutates, args))) {
+        await record(name, "declined", { target });
+        return refused("not approved: the operation was declined, cancelled, or timed out");
+      }
+      await record(name, "accepted", { target });
+
+      // 4. PRE-STATE — after approval, before the mutation, so an unrecoverable action leaves a
+      //    record of what it destroyed. Capture failure is NOT fatal: refusing here would turn a
+      //    transient read error into a blocked action the owner already approved.
+      let preState: Record<string, unknown> = {};
+      if (toolCfg.capturePreState !== undefined) {
+        try {
+          preState = await toolCfg.capturePreState(args);
+        } catch (e) {
+          preState = { captureFailed: e instanceof Error ? e.message : String(e) };
+        }
+      }
+
+      // 5. MUTATE. Decrement BEFORE the call so a throwing mutation still consumes budget —
+      //    otherwise a failing destructive tool could be retried without limit.
+      remaining -= 1;
+      if (remaining <= 0) {
+        for (const h of handles) h.disable();
+        server.sendToolListChanged();
+      }
+      try {
+        const result = await handler(args);
+        await record(name, "executed", { target, preState });
+        return result;
+      } catch (e) {
+        await record(name, "failed", {
+          target,
+          preState,
+          error: e instanceof Error ? e.message : String(e),
+        });
+        throw e;
+      }
+    };
+
+    pending.push(() => {
+      registerOn(server, name, description, schema, guarded, handles);
+    });
+  };
+}

package/shared/fetch-bearer-json.ts

@@ -0,0 +1,18 @@
+/**
+ * fetch-bearer-json — re-export of the Bearer-auth JSON fetch helpers now owned
+ * by `@nimbus-dev/sdk/connector-kit`.
+ *
+ * These helpers originated here and were upstreamed to the SDK in 1.11.0. The
+ * SDK is now the single owner; this module stays as the connector-facing import
+ * path so the ~99 connectors keep their existing relative imports.
+ *
+ * Named re-exports, deliberately not `export *` — see the note in
+ * `mcp-tool-kit.ts`.
+ *
+ * `resolveUrlWithBase` remains the SSRF chokepoint that refuses a cross-origin
+ * absolute URL before a credential-bearing fetch; that behaviour now lives in
+ * the SDK and is covered by `fetch-bearer-json.test.ts` through this re-export.
+ */
+
+export type { BearerJsonFetchResult } from "@nimbus-dev/sdk/connector-kit";
+export { fetchBearerAuthorizedJson, resolveUrlWithBase } from "@nimbus-dev/sdk/connector-kit";

package/shared/header-safe.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+/**
+ * Rejects any string containing a carriage return or line feed. CR/LF in an
+ * email header field (`To`/`Cc`/`Bcc`/`Subject`/attendee list) is the classic
+ * header / recipient-injection vector: a folded line can smuggle extra headers
+ * or recipients into the outgoing message. Body text legitimately contains
+ * newlines and must NOT use this guard.
+ */
+const NO_CRLF = /^[^\r\n]*$/;
+
+/**
+ * A Zod string constrained to a single header line (no CR/LF), with optional
+ * length bounds. Use for every user-supplied field that flows into an email
+ * header — `to`, `cc`, `bcc`, `subject`, and comma-separated recipient/attendee
+ * lists. The single shared definition keeps the guard consistent across every
+ * send/draft connector (imap, protonmail, fastmail, gmail, outlook).
+ */
+export function headerLine(opts?: { min?: number; max?: number }): z.ZodString {
+  let s = z.string().regex(NO_CRLF, "must not contain a line break (CR/LF)");
+  if (opts?.min !== undefined) {
+    s = s.min(opts.min);
+  }
+  if (opts?.max !== undefined) {
+    s = s.max(opts.max);
+  }
+  return s;
+}

package/shared/imap-bodystructure.ts

@@ -0,0 +1,113 @@
+/**
+ * Pure BODYSTRUCTURE walkers shared by the IMAP-based mail connectors (imap,
+ * protonmail-via-Bridge) — extract attachment METADATA (filename, size,
+ * mimetype) and locate the first text/plain part for the preview. NEVER touches
+ * attachment bytes; operates only on the structure tree imapflow returns.
+ */
+
+/**
+ * imapflow's parsed BODYSTRUCTURE node. Multipart nodes carry `childNodes`; leaf
+ * nodes carry `type` (mimetype), `size`, and `disposition`/`dispositionParameters`
+ * for attachments. We type the fields we read; the rest is `unknown`.
+ */
+export interface BodyStructureNode {
+  readonly part?: string;
+  readonly type?: string;
+  readonly size?: number;
+  readonly disposition?: string | null;
+  readonly dispositionParameters?: Record<string, unknown> | null;
+  readonly parameters?: Record<string, unknown> | null;
+  readonly childNodes?: readonly BodyStructureNode[] | null;
+}
+
+/** Attachment METADATA only — filename, size, mimetype. NEVER the bytes. */
+export interface AttachmentMeta {
+  readonly filename: string | null;
+  readonly sizeBytes: number | null;
+  readonly mimeType: string | null;
+}
+
+function asString(v: unknown): string | null {
+  return typeof v === "string" && v !== "" ? v : null;
+}
+
+function filenameOf(node: BodyStructureNode): string | null {
+  const fromDisp = asString(node.dispositionParameters?.["filename"]);
+  if (fromDisp !== null) {
+    return fromDisp;
+  }
+  // Some servers put the name in the content-type `name` parameter instead.
+  return asString(node.parameters?.["name"]);
+}
+
+function isAttachment(node: BodyStructureNode): boolean {
+  const disp = (node.disposition ?? "").toLowerCase();
+  if (disp === "attachment" || disp === "inline") {
+    return filenameOf(node) !== null;
+  }
+  // No disposition but a filename present → treat as attachment metadata.
+  return filenameOf(node) !== null;
+}
+
+/**
+ * Walk the BODYSTRUCTURE tree and collect attachment METADATA only — filename,
+ * size, mimetype. Never reads or requests the part body.
+ */
+export function extractAttachments(root: BodyStructureNode | null | undefined): AttachmentMeta[] {
+  const out: AttachmentMeta[] = [];
+  const stack: BodyStructureNode[] = root ? [root] : [];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (node === undefined) {
+      continue;
+    }
+    const children = node.childNodes ?? null;
+    if (children !== null) {
+      for (const c of children) {
+        stack.push(c);
+      }
+      continue;
+    }
+    if (isAttachment(node)) {
+      out.push({
+        filename: filenameOf(node),
+        sizeBytes: typeof node.size === "number" && Number.isFinite(node.size) ? node.size : null,
+        mimeType: asString(node.type),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Find the IMAP part key of the first `text/plain` leaf that is NOT an
+ * attachment. Used to fetch a single truncated body part for the preview.
+ * Returns `"1"` as a conservative default when no structure is available
+ * (a single-part text message has an implicit part "1" / "TEXT").
+ */
+export function findTextPlainPart(root: BodyStructureNode | null | undefined): string {
+  const stack: BodyStructureNode[] = root ? [root] : [];
+  let firstAnyText: string | null = null;
+  while (stack.length > 0) {
+    const node = stack.shift();
+    if (node === undefined) {
+      continue;
+    }
+    const children = node.childNodes ?? null;
+    if (children !== null) {
+      for (const c of children) {
+        stack.push(c);
+      }
+      continue;
+    }
+    const type = (node.type ?? "").toLowerCase();
+    const part = node.part ?? "1";
+    if (type === "text/plain" && !isAttachment(node)) {
+      return part;
+    }
+    if (type.startsWith("text/") && firstAnyText === null && !isAttachment(node)) {
+      firstAnyText = part;
+    }
+  }
+  return firstAnyText ?? "1";
+}

package/shared/imap-mail-core.ts

@@ -0,0 +1,57 @@
+/**
+ * Pure, transport-agnostic helpers shared by the IMAP-based mail connectors
+ * (imap, protonmail-via-Bridge). ProtonMail Bridge exposes a standard IMAP/SMTP
+ * interface, so both connectors share the same preview-capping, limit-clamping,
+ * and address-formatting logic. No external deps; never touches message bodies
+ * or attachment bytes.
+ */
+
+/** Max characters of the plain-text body preview that is ever indexed/returned. */
+export const PREVIEW_MAX_CHARS = 2000;
+/** Max bytes of the text/plain body part fetched for the preview (~2 KB). */
+export const PREVIEW_FETCH_BYTES = 2048;
+
+/** One parsed address (name optional). */
+export interface MailAddress {
+  readonly name?: string;
+  readonly address?: string;
+}
+
+const DEFAULT_LIST_LIMIT = 50;
+const MAX_LIST_LIMIT = 200;
+
+export function clampLimit(limit: number | undefined, fallback = DEFAULT_LIST_LIMIT): number {
+  if (limit === undefined || !Number.isFinite(limit)) {
+    return fallback;
+  }
+  const n = Math.trunc(limit);
+  if (n < 1) {
+    return 1;
+  }
+  return Math.min(n, MAX_LIST_LIMIT);
+}
+
+/**
+ * Cap a body preview to {@link PREVIEW_MAX_CHARS}. Normalizes CRLF and collapses
+ * whitespace/blank-line runs so the preview stays compact; never lengthens the
+ * input.
+ */
+export function capPreview(text: string): string {
+  const normalized = text
+    .replaceAll("\r\n", "\n")
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n{2,}/g, "\n")
+    .trim();
+  return normalized.length > PREVIEW_MAX_CHARS
+    ? normalized.slice(0, PREVIEW_MAX_CHARS)
+    : normalized;
+}
+
+/** Format one address as `Name <addr>` / `<addr>` for envelope display. */
+export function formatAddress(a: MailAddress): string {
+  const addr = a.address ?? "";
+  if (a.name !== undefined && a.name !== "") {
+    return addr === "" ? a.name : `${a.name} <${addr}>`;
+  }
+  return addr;
+}