@nimbus-dev/connectors 0.2.1 → 0.2.3

package/shared/imapflow-adapter.ts

@@ -0,0 +1,417 @@
+/**
+ * imapflow-adapter — the real IMAP client + SMTP mailer over `imapflow` and
+ * `nodemailer`, shared by every IMAP-based mail connector (imap, protonmail).
+ *
+ * These two class bodies were previously written out in full in each
+ * connector's `server.ts`. `imap-tool-kit.ts` deliberately left them alone at
+ * the time ("class bodies … are out of scope per the dedup brief"), and the
+ * cost of that was measurable on both axes Sonar reports:
+ *
+ *   - duplication: `imap/src/server.ts` 41.2% and `protonmail/src/server.ts`
+ *     38.8%, 186 duplicated lines between them — the largest pair in the repo;
+ *   - coverage: both files were 0%. An entry point that constructs its adapters
+ *     at module scope cannot be imported by a test without opening real
+ *     sockets, so every line of transport logic in them was unasserted.
+ *
+ * Extracting the classes here fixes both: one copy, and one that a test can
+ * construct because the `imapflow` client and the `nodemailer` transport are
+ * injected seams rather than direct `new` calls. The two connectors differ only
+ * in configuration (TLS mode, ports, env var names, mailbox default), so all of
+ * it is passed in.
+ *
+ * HARD SCOPE CONSTRAINT (security), inherited from both connectors: the fetch
+ * query below requests ONLY `envelope` + `bodyStructure` + a `PREVIEW_FETCH_BYTES`-
+ * capped text part. There is no surface here to request `BODY[]` or an
+ * attachment part, so no caller can make this adapter download message bodies
+ * or attachment bytes.
+ */
+
+import {
+  type FetchMessageObject,
+  type FetchQueryObject,
+  ImapFlow,
+  type MessageAddressObject,
+} from "imapflow";
+import { createTransport, type Transporter } from "nodemailer";
+import {
+  type BodyStructureNode,
+  extractAttachments,
+  findTextPlainPart,
+} from "./imap-bodystructure.ts";
+import { clampLimit, type MailAddress, PREVIEW_FETCH_BYTES } from "./imap-mail-core.ts";
+import {
+  type EmailMessageMeta,
+  type EmailReadClient,
+  type EmailSendMailer,
+  previewFromParts,
+} from "./imap-tool-kit.ts";
+
+/** Mailbox used when a tool call does not name one. */
+export const DEFAULT_MAILBOX = "INBOX";
+
+/** Connection settings for one IMAP endpoint. Read from `process.env` by the caller. */
+export interface ImapEndpointConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly user: string;
+  readonly pass: string;
+  /**
+   * Implicit TLS on connect. `true` for a normal IMAPS endpoint on 993; `false`
+   * for the ProtonMail Bridge, which speaks STARTTLS on loopback.
+   */
+  readonly secure: boolean;
+  /**
+   * Chain verification. Omit (the default) for a real endpoint. Only the
+   * ProtonMail Bridge passes `false`, for its self-signed loopback certificate;
+   * the connection never leaves 127.0.0.1.
+   */
+  readonly rejectUnauthorized?: boolean;
+  /** Mailbox used when a call does not name one. Defaults to {@link DEFAULT_MAILBOX}. */
+  readonly defaultMailbox?: string;
+}
+
+/** Connection settings for one SMTP endpoint. */
+export interface SmtpEndpointConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly user: string;
+  readonly pass: string;
+  readonly secure: boolean;
+  readonly rejectUnauthorized?: boolean;
+}
+
+/**
+ * There is deliberately no `requireTLS` option.
+ *
+ * When `secure` is false this adapter ALWAYS demands STARTTLS, and that is not
+ * a default a caller can override — an unencrypted SMTP session is not a
+ * configuration this module offers. Without it nodemailer falls back to
+ * plaintext when the server does not advertise STARTTLS, and the password goes
+ * out in the clear.
+ *
+ * The gap was live, not hypothetical: `imap` computes `secure: port === 465`,
+ * so an operator setting `IMAP_SMTP_PORT=587` — the standard submission port —
+ * got `secure: false` with no `requireTLS` at all. Of the three copies this
+ * adapter replaced, only Apple's set it.
+
+/** Constructs the `imapflow` client. Overridden in tests so no socket is opened. */
+export type ImapFlowFactory = (options: ConstructorParameters<typeof ImapFlow>[0]) => ImapFlow;
+
+/**
+ * The transport options this adapter builds. Declared here rather than reused
+ * from nodemailer: `Parameters<typeof createTransport>[0]` resolves to the
+ * union `Transport | TransportOptions`, and a plain SMTP option literal is not
+ * assignable to that union.
+ */
+export interface SmtpTransportOptions {
+  readonly host: string;
+  readonly port: number;
+  readonly secure: boolean;
+  readonly auth: { readonly user: string; readonly pass: string };
+  /** Always set by this module, and always `true` when `secure` is false. */
+  readonly requireTLS: boolean;
+  readonly tls?: { readonly rejectUnauthorized: boolean };
+}
+
+/** Constructs the `nodemailer` transport. Overridden in tests so no socket is opened. */
+export type TransportFactory = (options: SmtpTransportOptions) => Transporter;
+
+/**
+ * Build a {@link MailAddress} from an imapflow envelope address, omitting
+ * `name`/`address` when absent — the interface uses `exactOptionalPropertyTypes`,
+ * so an explicit `undefined` is not assignable.
+ *
+ * The parameter is imapflow's own `MessageAddressObject`, not a restated
+ * `{ name?: string; address?: string }`. imapflow 2 generates its declarations,
+ * which spell the fields `name?: string | undefined`, and under
+ * `exactOptionalPropertyTypes` a hand-written shape without the `| undefined`
+ * stops accepting the library's value.
+ */
+function toMailAddress(a: MessageAddressObject): MailAddress {
+  const out: { name?: string; address?: string } = {};
+  if (a.name !== undefined) {
+    out.name = a.name;
+  }
+  if (a.address !== undefined) {
+    out.address = a.address;
+  }
+  return out;
+}
+
+function envelopeFromImap(env: FetchMessageObject["envelope"]): EmailMessageMeta["envelope"] {
+  if (env === undefined) {
+    return {};
+  }
+  return {
+    date: env.date ?? null,
+    subject: env.subject ?? null,
+    messageId: env.messageId ?? null,
+    from: (env.from ?? []).map(toMailAddress),
+    to: (env.to ?? []).map(toMailAddress),
+    cc: (env.cc ?? []).map(toMailAddress),
+  };
+}
+
+/** Reduce one fetched message to the header + attachment-metadata + preview view. */
+export function toMessageMeta(
+  msg: FetchMessageObject,
+  mailbox: string,
+  uidValidity: string | null,
+): EmailMessageMeta {
+  const structure = (msg.bodyStructure ?? null) as BodyStructureNode | null;
+  const partKey = findTextPlainPart(structure);
+  return {
+    uid: msg.uid,
+    mailbox,
+    uidValidity,
+    envelope: envelopeFromImap(msg.envelope),
+    attachments: extractAttachments(structure),
+    preview: previewFromParts(msg.bodyParts, partKey),
+  };
+}
+
+/**
+ * Fetch query that requests ONLY headers + structure + a truncated text body
+ * part. There is no `source` / full-body request here by construction.
+ */
+export function previewFetchQuery(): FetchQueryObject {
+  return {
+    uid: true,
+    envelope: true,
+    bodyStructure: true,
+    internalDate: true,
+    // Two candidate text part keys, each capped to PREVIEW_FETCH_BYTES bytes.
+    bodyParts: [
+      { key: "1", start: 0, maxLength: PREVIEW_FETCH_BYTES },
+      { key: "TEXT", start: 0, maxLength: PREVIEW_FETCH_BYTES },
+    ],
+  };
+}
+
+/**
+ * imapflow answers `undefined` from `fetchOne` and `search` when it has no
+ * mailbox selected — reachable under the lock `withMailbox` holds only if the
+ * connection closed after it was taken.
+ *
+ * imapflow 1.x did the same at runtime but declared no such return, so the
+ * value reached `toMessageMeta` / `.length` and failed as a bare TypeError. The
+ * generated declarations of 2.x surface it. It stays a FAILURE, now one that
+ * says what happened — not "no such message" or "no results", which would
+ * report a dropped connection as an answer.
+ */
+function mailboxNotSelected(mailbox: string): Error {
+  return new Error(`imap: mailbox "${mailbox}" is no longer selected (connection closed?)`);
+}
+
+/**
+ * Real IMAP client over imapflow. Per-call connect/lock/logout keeps it
+ * stateless, so nothing is held open between tool calls.
+ */
+class ImapFlowClient implements EmailReadClient {
+  private readonly defaultMailbox: string;
+
+  constructor(
+    private readonly config: ImapEndpointConfig,
+    private readonly newImapFlow: ImapFlowFactory,
+  ) {
+    this.defaultMailbox = config.defaultMailbox ?? DEFAULT_MAILBOX;
+  }
+
+  private newClient(): ImapFlow {
+    const { host, port, secure, user, pass, rejectUnauthorized } = this.config;
+    return this.newImapFlow({
+      host,
+      port,
+      secure,
+      auth: { user, pass },
+      logger: false,
+      // Only set when the caller asked to relax it — see ImapEndpointConfig.
+      ...(rejectUnauthorized === undefined ? {} : { tls: { rejectUnauthorized } }),
+    });
+  }
+
+  private async withMailbox<T>(
+    mailbox: string,
+    fn: (client: ImapFlow, uidValidity: string | null) => Promise<T>,
+  ): Promise<T> {
+    const client = this.newClient();
+    await client.connect();
+    // `logout` sits in an OUTER finally so the connection is closed even when
+    // `getMailboxLock` throws. Acquiring the lock BEFORE the try — which is how
+    // imap and protonmail both had it — leaks the connected socket on a locking
+    // failure (a mailbox that does not exist, or one another client holds), and
+    // this client connects per call, so every such failure leaks another.
+    // Apple's copy already nested it this way; the correction travelled the
+    // wrong direction when these were three separate copies.
+    try {
+      const lock = await client.getMailboxLock(mailbox);
+      try {
+        const mb = client.mailbox;
+        const uidValidity = mb === false ? null : String(mb.uidValidity);
+        return await fn(client, uidValidity);
+      } finally {
+        lock.release();
+      }
+    } finally {
+      await client.logout();
+    }
+  }
+
+  async list(options: { mailbox?: string; limit?: number }): Promise<EmailMessageMeta[]> {
+    const mailbox = options.mailbox ?? this.defaultMailbox;
+    const limit = clampLimit(options.limit);
+    return this.withMailbox(mailbox, async (client, uidValidity) => {
+      const out: EmailMessageMeta[] = [];
+      const status = await client.status(mailbox, { messages: true });
+      // `false` is a STATUS the server rejected, read as an empty mailbox. That
+      // is what this did under imapflow 1.x too, which returned the same `false`
+      // but declared only `StatusObject`, so `status.messages ?? 0` made it 0.
+      const total = status === false ? 0 : (status.messages ?? 0);
+      if (total === 0) {
+        return out;
+      }
+      const start = Math.max(1, total - limit + 1);
+      const range = `${start}:${total}`;
+      for await (const msg of client.fetch(range, previewFetchQuery())) {
+        out.push(toMessageMeta(msg, mailbox, uidValidity));
+      }
+      // Most-recent first.
+      out.sort((a, b) => b.uid - a.uid);
+      return out;
+    });
+  }
+
+  async get(uid: number, mailbox?: string): Promise<EmailMessageMeta | null> {
+    const box = mailbox ?? this.defaultMailbox;
+    return this.withMailbox(box, async (client, uidValidity) => {
+      const msg = await client.fetchOne(String(uid), previewFetchQuery(), { uid: true });
+      if (msg === undefined) {
+        throw mailboxNotSelected(box);
+      }
+      return msg === false ? null : toMessageMeta(msg, box, uidValidity);
+    });
+  }
+
+  async search(options: {
+    query: string;
+    mailbox?: string;
+    limit?: number;
+  }): Promise<EmailMessageMeta[]> {
+    const mailbox = options.mailbox ?? this.defaultMailbox;
+    const limit = clampLimit(options.limit);
+    const q = options.query;
+    return this.withMailbox(mailbox, async (client, uidValidity) => {
+      const uids = await client.search(
+        { or: [{ subject: q }, { from: q }, { to: q }] },
+        { uid: true },
+      );
+      if (uids === undefined) {
+        throw mailboxNotSelected(mailbox);
+      }
+      if (uids === false || uids.length === 0) {
+        return [];
+      }
+      const picked = uids.slice(-limit).sort((a, b) => b - a);
+      const out: EmailMessageMeta[] = [];
+      for await (const msg of client.fetch(picked, previewFetchQuery(), { uid: true })) {
+        out.push(toMessageMeta(msg, mailbox, uidValidity));
+      }
+      out.sort((a, b) => b.uid - a.uid);
+      return out;
+    });
+  }
+}
+
+/**
+ * Real SMTP mailer over nodemailer.
+ *
+ * The envelope `from` is PINNED to the authenticated user and is not a `send`
+ * parameter, so no caller can send as someone else (the forced-sender contract
+ * the mail connectors document).
+ */
+class NodemailerMailer implements EmailSendMailer {
+  private readonly transport: Transporter;
+  private readonly from: string;
+
+  constructor(config: SmtpEndpointConfig, makeTransport: TransportFactory) {
+    const { host, port, secure, user, pass, rejectUnauthorized } = config;
+    this.from = user;
+    this.transport = makeTransport({
+      host,
+      port,
+      secure,
+      auth: { user, pass },
+      // Implicit TLS already encrypts the session; otherwise STARTTLS is
+      // required. Not a default — there is no input to this mailer that
+      // produces a transport willing to send in the clear.
+      requireTLS: !secure,
+      ...(rejectUnauthorized === undefined ? {} : { tls: { rejectUnauthorized } }),
+    });
+  }
+
+  async send(input: {
+    to: string;
+    subject: string;
+    body: string;
+    cc?: string;
+    bcc?: string;
+  }): Promise<{
+    messageId: string | null;
+    accepted: readonly string[];
+    rejected: readonly string[];
+  }> {
+    const info = await this.transport.sendMail({
+      from: this.from,
+      to: input.to,
+      subject: input.subject,
+      text: input.body,
+      ...(input.cc === undefined ? {} : { cc: input.cc }),
+      ...(input.bcc === undefined ? {} : { bcc: input.bcc }),
+    });
+    return {
+      messageId: info.messageId ?? null,
+      accepted: (info.accepted ?? []).map(String),
+      rejected: (info.rejected ?? []).map(String),
+    };
+  }
+}
+
+/**
+ * The IMAP read client for `config`. `newImapFlow` defaults to the real
+ * `imapflow` constructor; tests pass a fake so no socket is opened.
+ */
+export function createImapFlowClient(
+  config: ImapEndpointConfig,
+  newImapFlow: ImapFlowFactory = (options) => new ImapFlow(options),
+): EmailReadClient {
+  return new ImapFlowClient(config, newImapFlow);
+}
+
+/**
+ * Construct the real nodemailer transport.
+ *
+ * Written as two explicit branches rather than passing `options` straight
+ * through. `NodemailerMailer` has already computed the guarantee, but a
+ * computed value is not something a reader — or a static analyser — can check
+ * at the call that actually opens the socket. Here it is a literal on both
+ * paths: implicit TLS, or STARTTLS required. There is no third branch.
+ */
+function realTransport(options: SmtpTransportOptions): Transporter {
+  const { host, port, auth } = options;
+  const tls = options.tls === undefined ? {} : { tls: options.tls };
+  if (options.secure) {
+    return createTransport({ host, port, auth, ...tls, secure: true });
+  }
+  return createTransport({ host, port, auth, ...tls, secure: false, requireTLS: true });
+}
+
+/**
+ * The SMTP mailer for `config`. `makeTransport` defaults to the real nodemailer
+ * transport; tests pass a fake so no socket is opened.
+ */
+export function createNodemailerMailer(
+  config: SmtpEndpointConfig,
+  makeTransport: TransportFactory = realTransport,
+): EmailSendMailer {
+  return new NodemailerMailer(config, makeTransport);
+}

package/shared/nimbus-spawn.ts

@@ -1,7 +1,70 @@
-import { spawn } from "node:child_process";
+/**
+ * nimbus-spawn — the one place this package starts a process.
+ *
+ * Every connector that reaches its service through a CLI spawns it through {@link nimbusSpawn},
+ * directly or by way of `run-cli-json.ts` and `cli-json-kit.ts`, and `scripts/spawn-chokepoint.test.ts`
+ * fails any other shipped file that imports a module able to start a process, in any import form,
+ * or refers to the `Bun` global at all. That is what makes a rule enforced here hold for every
+ * connector: today, `windows-batch-args.ts`'s refusal of an argument cmd.exe would act on, when the
+ * program may start a Windows batch file. Both implementations build the child's environment once
+ * and hand the SAME object to that check and to the spawn, so the environment that was checked is
+ * the one the child gets.
+ */
+
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { batchArgumentRefusal } from "./windows-batch-args.ts";
 
 export type SpawnResult = { code: number; stdout: string; stderr: string };
 
+/**
+ * The child's environment for `env`, and why `command` must not be spawned with it, if it must
+ * not. Nothing is spawned for a refused command: it resolves as a failure whose stderr says so.
+ */
+function prepareSpawn(
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+): { childEnv: Record<string, string | undefined>; refusal: SpawnResult | undefined } {
+  const childEnv = { ...process.env, ...env };
+  const refusal = batchArgumentRefusal(command, childEnv);
+  return {
+    childEnv,
+    refusal: refusal === undefined ? undefined : { code: 1, stdout: "", stderr: refusal },
+  };
+}
+
+/**
+ * Collect a child's output and resolve with it once the child closes or fails to start.
+ *
+ * Output is accumulated as raw `Buffer`s and decoded ONCE at the end. Decoding each chunk with
+ * `chunk.toString("utf8")` corrupts any multi-byte character that straddles a chunk boundary, and
+ * chunk boundaries are a function of pipe timing — so it fails intermittently, on non-ASCII data,
+ * in production.
+ */
+function collectOutput(
+  child: ChildProcessWithoutNullStreams,
+  resolveP: (result: SpawnResult) => void,
+): void {
+  const outChunks: Buffer[] = [];
+  const errChunks: Buffer[] = [];
+  child.stdout.on("data", (c: Buffer) => {
+    outChunks.push(c);
+  });
+  child.stderr.on("data", (c: Buffer) => {
+    errChunks.push(c);
+  });
+  const decode = (): { stdout: string; stderr: string } => ({
+    stdout: Buffer.concat(outChunks).toString("utf8"),
+    stderr: Buffer.concat(errChunks).toString("utf8"),
+  });
+  child.on("error", (e: Error) => {
+    const d = decode();
+    resolveP({ code: 1, stdout: d.stdout, stderr: `${d.stderr}${e.message}` });
+  });
+  child.on("close", (code: number | null) => {
+    resolveP({ code: code ?? 1, ...decode() });
+  });
+}
+
 /**
  * Node implementation. Exported so it can be tested directly: the suite runs under Bun, so
  * `nimbusSpawn` would otherwise never exercise this branch and it would ship unverified.
@@ -15,11 +78,6 @@ export type SpawnResult = { code: number; stdout: string; stderr: string };
  *    `Bun.spawn` path reads stdout uncapped, and `aws logs` / `gcloud logging` JSON routinely
  *    exceeds 1 MB, so `execFile` would be a silent-truncation regression dressed up as a
  *    portability fix.
- *
- * Output is accumulated as raw `Buffer`s and decoded ONCE at the end. Decoding each chunk with
- * `chunk.toString("utf8")` corrupts any multi-byte character that straddles a chunk boundary, and
- * chunk boundaries are a function of pipe timing — so it fails intermittently, on non-ASCII data,
- * in production.
  */
 export function spawnViaNode(
   command: readonly string[],
@@ -29,27 +87,20 @@ export function spawnViaNode(
   if (bin === undefined) {
     return Promise.resolve({ code: 1, stdout: "", stderr: "empty command" });
   }
+  const { childEnv, refusal } = prepareSpawn(command, env);
+  if (refusal !== undefined) {
+    return Promise.resolve(refusal);
+  }
   return new Promise((resolveP) => {
-    const child = spawn(bin, args, { env: { ...process.env, ...env } });
-    const outChunks: Buffer[] = [];
-    const errChunks: Buffer[] = [];
-    child.stdout.on("data", (c: Buffer) => {
-      outChunks.push(c);
-    });
-    child.stderr.on("data", (c: Buffer) => {
-      errChunks.push(c);
-    });
-    const decode = (): { stdout: string; stderr: string } => ({
-      stdout: Buffer.concat(outChunks).toString("utf8"),
-      stderr: Buffer.concat(errChunks).toString("utf8"),
-    });
-    child.on("error", (e: Error) => {
-      const d = decode();
-      resolveP({ code: 1, stdout: d.stdout, stderr: `${d.stderr}${e.message}` });
-    });
-    child.on("close", (code: number | null) => {
-      resolveP({ code: code ?? 1, ...decode() });
-    });
+    // `spawn` THROWS, rather than emitting "error", for a command it cannot start at all: an
+    // argument holding a NUL byte, or — on Node, though not in Bun's `node:child_process` — a
+    // `.cmd` or `.bat` without a shell, which Node refuses with EINVAL. Uncaught, the throw would
+    // REJECT this promise, against the contract both implementations keep.
+    try {
+      collectOutput(spawn(bin, args, { env: childEnv }), resolveP);
+    } catch (e) {
+      resolveP({ code: 1, stdout: "", stderr: e instanceof Error ? e.message : String(e) });
+    }
   });
 }
 
@@ -61,12 +112,16 @@ export async function spawnViaBun(
   if (command.length === 0) {
     return { code: 1, stdout: "", stderr: "empty command" };
   }
+  const { childEnv, refusal } = prepareSpawn(command, env);
+  if (refusal !== undefined) {
+    return refusal;
+  }
   // `Bun.spawn` THROWS synchronously when the binary does not exist, where `child_process` emits
   // an "error" event instead. Both branches must honour the same contract — resolve with a
   // non-zero code, never reject — or a caller's behaviour would depend on the runtime.
   try {
     const proc = Bun.spawn([...command], {
-      env: { ...process.env, ...env },
+      env: childEnv,
       stdout: "pipe",
       stderr: "pipe",
     });
@@ -119,6 +174,8 @@ export function selectSpawnImpl(g: unknown = globalThis): SpawnImpl {
  * routing unconditionally through Node made it spawn a real `aws` and hang the suite.
  *
  * Never rejects: a spawn failure resolves with a non-zero code, matching the previous behaviour.
+ * So does a REFUSED spawn — on Windows, an argument cmd.exe would act on, for a program that may
+ * start a batch file — whose stderr says why and that nothing was run.
  */
 export function nimbusSpawn(
   command: readonly string[],

package/shared/rest-tool-kit.ts

@@ -1,18 +1,88 @@
 /**
- * rest-tool-kit — re-export of the shared REST fetch wrapper for Bearer-auth
- * connectors, now owned by `@nimbus-dev/sdk/connector-kit`.
+ * rest-tool-kit — the REST tool plumbing for token-auth connectors.
  *
- * 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.
+ * `makeRestFetcher` and `makeRestToolRegistrar` originated here and were upstreamed
+ * to the SDK in 1.11.0. The SDK is now their single owner; this module re-exports
+ * them so the ~99 connectors keep their existing relative imports. Named
+ * re-exports, deliberately not `export *` — see the note in `mcp-tool-kit.ts`.
  *
- * Named re-exports, deliberately not `export *` — see the note in
- * `mcp-tool-kit.ts`.
+ * The two helpers defined BELOW are this repository's own and stay here:
+ * {@link makeRestWriteToolRegistrar} registers through the consent kit, which the
+ * SDK does not have, and {@link toRestFetchResult} is the tail of the connector
+ * fetches whose credential is not a Bearer token, which the SDK's fetch cannot send.
  */
 
+import {
+  type HttpJsonBodyResponse,
+  mcpJsonResultIfOk,
+  type RestFetchResult,
+  requireProcessEnv,
+  type ZodObjectSchema,
+} from "@nimbus-dev/sdk/connector-kit";
+import type { WriteToolConfig, WriteToolRegistrar } from "./consent-kit.ts";
+
 export type {
   RestFetcherConfig,
   RestFetchResult,
   RestToolRegistrar,
 } from "@nimbus-dev/sdk/connector-kit";
 export { makeRestFetcher, makeRestToolRegistrar } from "@nimbus-dev/sdk/connector-kit";
+
+/** The per-connector registrar {@link makeRestWriteToolRegistrar} builds. */
+export type RestWriteToolRegistrar = <T>(
+  name: string,
+  cfg: WriteToolConfig<T>,
+  description: string,
+  schema: ZodObjectSchema<T>,
+  buildPath: (args: T) => string,
+  buildInit?: (args: T) => RequestInit,
+) => void;
+
+/**
+ * The write twin of `makeRestToolRegistrar`: the same standard tool body —
+ * `token = requireProcessEnv(<env>)`, `res = await <fetch>(token, buildPath(args)
+ * [, buildInit(args)])`, `return mcpJsonResultIfOk(<label>, res, <snippetMax>)` —
+ * registered through the connector's consent-kit write registrar instead of its
+ * read-only one, so every mutation it registers is gated.
+ *
+ * The connector passes its OWN `registerWriteTool` in rather than this kit building
+ * one: the standalone launcher decides whether a connector's mutations are gated by
+ * reading that connector's own `server.ts`/`tools.ts`, and a registrar constructed in
+ * here would be invisible to it.
+ */
+export function makeRestWriteToolRegistrar(cfg: {
+  readonly registerWriteTool: WriteToolRegistrar;
+  readonly tokenEnv: string;
+  readonly serviceLabel: string;
+  readonly fetch: (
+    token: string,
+    pathOrUrl: string,
+    init?: RequestInit,
+  ) => Promise<HttpJsonBodyResponse>;
+  /** Body-snippet length for the `<label> <status>: <snippet>` error (mcpJsonResultIfOk default 300). */
+  readonly snippetMax?: number;
+}): RestWriteToolRegistrar {
+  return (name, toolCfg, description, schema, buildPath, buildInit) => {
+    cfg.registerWriteTool(name, toolCfg, description, schema, async (args) => {
+      const token = requireProcessEnv(cfg.tokenEnv);
+      const res = await cfg.fetch(token, buildPath(args), buildInit?.(args));
+      return mcpJsonResultIfOk(cfg.serviceLabel, res, cfg.snippetMax);
+    });
+  };
+}
+
+/**
+ * Read a response into the {@link RestFetchResult} shape a REST tool's fetch
+ * returns. `json` is the parsed body, or `null` when the body is not JSON (an empty
+ * 204, an HTML error page): what that means is the tool's decision, not this one's.
+ */
+export async function toRestFetchResult(res: Response): Promise<RestFetchResult> {
+  const text = await res.text();
+  let json: unknown;
+  try {
+    json = JSON.parse(text) as unknown;
+  } catch {
+    json = null;
+  }
+  return { ok: res.ok, status: res.status, json, text };
+}