@nimbus-dev/connectors 0.2.0 → 0.2.2

package/README.md

@@ -10,6 +10,9 @@ stdio with credentials supplied from the environment.
 npx @nimbus-dev/connectors github
 ```
 
+You need [Bun](https://bun.sh) 1.2 or newer on your `PATH`: the package ships TypeScript, and its
+`nimbus-connector` bin runs under Bun.
+
 ## What you get, and what you do not
 
 Run standalone, a connector gives you:
@@ -62,7 +65,12 @@ Credentials come from the environment. There is no Vault outside the gateway, so
 config holds the secret. Every variable, and the two behaviours that look like bugs and are not, are
 in [Configuration](./docs/configuration.md).
 
-Each connector documents its own tools and credentials at `connectors/<id>/README.md`.
+Each connector has its own README at `connectors/<id>/README.md`. Most list their tools and
+credentials, but some — `github`, `slack` and `jira` among them — are still only a short gateway
+quickstart. Until they are filled in, let the connector tell you: a tool called without its
+credential refuses before sending anything, with an error naming the variable to set
+(`GITHUB_PAT is not set`). Those that drive a CLI — `aws`, `azure`, `gcp`, `kubernetes`, `iac` —
+use that tool's own credentials and configuration instead.
 
 ## Documentation
 
@@ -79,10 +87,15 @@ Each connector documents its own tools and credentials at `connectors/<id>/READM
 
 ```bash
 bun install
-bun run check   # lint, typecheck, consent audit, full suite
+bun run check   # lint, typecheck, the four connector audits, full suite
 ```
 
-CI runs those four on Ubuntu, macOS and Windows — platform equality is a Nimbus non-negotiable.
+CI runs the same gates on Ubuntu, macOS and Windows — platform equality is a Nimbus
+non-negotiable.
+
+See [CONTRIBUTING](./CONTRIBUTING.md) before opening a PR, and
+[SECURITY](./SECURITY.md) before reporting a vulnerability — it states what this package does and
+does **not** claim, which is the difference between a security report and a documentation question.
 
 ## Relationship to the Nimbus monorepo
 
@@ -102,7 +115,8 @@ This repo was a scaffold from 2026-06-18 until the connectors landed. Its origin
 AGPL implications for downstream clients. All three were answered before the move: the connectors are
 consent-gated standalone, credentials come from the environment, and `NOTICE` states the tiering. It
 also proposed a package per connector; one package was chosen instead, because 94 packages means 94
-releases and forces `shared/` to become a versioned dependency that 190 files import by relative path.
+releases and forces `shared/` to become a versioned dependency that 212 shipped connector source
+files import by relative path.
 
 ## License
 

package/connectors/airflow/src/search-filter.ts

@@ -1,6 +1,7 @@
 import {
   asObjectish,
   makeQueryFilter,
+  nonEmptyStringsText,
   type SearchMatchOptions,
   stringField,
   tagNamesFromObjects,
@@ -8,20 +9,6 @@ import {
 
 export type AirflowSearchMatchOptions = SearchMatchOptions;
 
-function ownerNames(row: Record<string, unknown>): string {
-  const owners = row["owners"];
-  if (!Array.isArray(owners)) {
-    return "";
-  }
-  const names: string[] = [];
-  for (const o of owners) {
-    if (typeof o === "string" && o !== "") {
-      names.push(o);
-    }
-  }
-  return names.join(" ");
-}
-
 function fieldsOf(item: unknown): readonly string[] | null {
   const row = asObjectish(item);
   if (row === undefined) {
@@ -30,7 +17,7 @@ function fieldsOf(item: unknown): readonly string[] | null {
   return [
     stringField(row, "dag_id"),
     stringField(row, "description"),
-    ownerNames(row),
+    nonEmptyStringsText(row, "owners"),
     tagNamesFromObjects(row),
   ];
 }

package/connectors/airflow/src/server.ts

@@ -1,91 +1,6 @@
-import { z } from "zod";
-import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
-import {
-  encodeBasicAuthHeader,
-  mcpJsonResult as jsonResult,
-} from "../../../shared/mcp-tool-kit.ts";
 import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
-import { filterAirflowDags } from "./search-filter.ts";
-
-function trimTrailingSlash(s: string): string {
-  return s.endsWith("/") ? s.slice(0, -1) : s;
-}
-
-function apiBase(): string {
-  const v = process.env["AIRFLOW_URL"]?.trim();
-  if (v === undefined || v === "") {
-    throw new Error("AIRFLOW_URL is not set");
-  }
-  return trimTrailingSlash(v);
-}
-
-function authHeader(): Record<string, string> {
-  const user = process.env["AIRFLOW_USERNAME"]?.trim();
-  if (user === undefined || user === "") {
-    throw new Error("AIRFLOW_USERNAME is not set");
-  }
-  const password = process.env["AIRFLOW_PASSWORD"]?.trim();
-  if (password === undefined || password === "") {
-    throw new Error("AIRFLOW_PASSWORD is not set");
-  }
-  return {
-    Authorization: encodeBasicAuthHeader(user, password),
-    Accept: "application/json",
-  };
-}
-
-async function airflowGet(path: string): Promise<unknown> {
-  const res = await fetch(`${apiBase()}${path}`, { headers: authHeader() });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`Airflow ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text) as unknown;
-}
-
-function dagsFrom(root: unknown): unknown[] {
-  const dags = (root as { dags?: unknown } | null)?.dags;
-  return Array.isArray(dags) ? dags : [];
-}
+import { registerAirflowTools } from "./tools.ts";
 
 await runReadOnlyMcpConnector("nimbus-airflow", (reg) => {
-  reg(
-    "airflow_list",
-    "List Airflow DAGs (GET /api/v1/dags?limit=100&offset=<n>). The Airflow stable REST API v1 returns the envelope { dags: [...], total_entries: <int> } — `dags` holds the DAG objects, `total_entries` the total across all pages. The optional offset arg (default 0) selects the page start; limit is fixed at 100.",
-    z.object({
-      offset: z.number().int().min(0).optional(),
-    }),
-    async (p) => {
-      const offset = p.offset ?? 0;
-      const root = await airflowGet(
-        `/api/v1/dags?limit=100&offset=${encodeURIComponent(String(offset))}`,
-      );
-      return jsonResult({ items: dagsFrom(root) });
-    },
-  );
-
-  reg(
-    "airflow_get",
-    "Fetch one Airflow DAG by its dag_id (GET /api/v1/dags/{dag_id}). Returns the DAG object directly (NOT wrapped in an envelope). Throws when no DAG with that id exists.",
-    z.object({
-      dag_id: z.string().min(1),
-    }),
-    async (p) => {
-      return jsonResult(await airflowGet(`/api/v1/dags/${encodeURIComponent(p.dag_id)}`));
-    },
-  );
-
-  reg(
-    "airflow_search",
-    "Substring search across the first page of Airflow DAGs. Matches the query (case-insensitive) against the dag_id, description, owners, and tag names. Returns a matches envelope.",
-    searchToolInputSchema(100),
-    async (p) => {
-      const root = await airflowGet("/api/v1/dags?limit=100&offset=0");
-      const matches = filterAirflowDags(dagsFrom(root), {
-        query: p.query,
-        limit: p.limit,
-      });
-      return jsonResult({ matches });
-    },
-  );
+  registerAirflowTools(reg);
 });

package/connectors/airflow/src/tools.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { createJsonGetter, requiredBaseUrl, requiredEnv } from "../../../shared/env-json-api.ts";
+import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
+import {
+  encodeBasicAuthHeader,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
+import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterAirflowDags } from "./search-filter.ts";
+
+function authHeader(): Record<string, string> {
+  const user = requiredEnv("AIRFLOW_USERNAME");
+  const password = requiredEnv("AIRFLOW_PASSWORD");
+  return {
+    Authorization: encodeBasicAuthHeader(user, password),
+    Accept: "application/json",
+  };
+}
+
+const airflowGet = createJsonGetter({
+  base: () => requiredBaseUrl("AIRFLOW_URL"),
+  label: "Airflow",
+  headers: authHeader,
+});
+
+function dagsFrom(root: unknown): unknown[] {
+  const dags = (root as { dags?: unknown } | null)?.dags;
+  return Array.isArray(dags) ? dags : [];
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const AIRFLOW_TOOL_NAMES = ["airflow_get", "airflow_list", "airflow_search"] as const;
+
+export function registerAirflowTools(reg: ZodToolRegistrar): void {
+  reg(
+    "airflow_list",
+    "List Airflow DAGs (GET /api/v1/dags?limit=100&offset=<n>). The Airflow stable REST API v1 returns the envelope { dags: [...], total_entries: <int> } — `dags` holds the DAG objects, `total_entries` the total across all pages. The optional offset arg (default 0) selects the page start; limit is fixed at 100.",
+    z.object({
+      offset: z.number().int().min(0).optional(),
+    }),
+    async (p) => {
+      const offset = p.offset ?? 0;
+      const root = await airflowGet(
+        `/api/v1/dags?limit=100&offset=${encodeURIComponent(String(offset))}`,
+      );
+      return jsonResult({ items: dagsFrom(root) });
+    },
+  );
+
+  reg(
+    "airflow_get",
+    "Fetch one Airflow DAG by its dag_id (GET /api/v1/dags/{dag_id}). Returns the DAG object directly (NOT wrapped in an envelope). Throws when no DAG with that id exists.",
+    z.object({
+      dag_id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await airflowGet(`/api/v1/dags/${encodeURIComponent(p.dag_id)}`));
+    },
+  );
+
+  reg(
+    "airflow_search",
+    "Substring search across the first page of Airflow DAGs. Matches the query (case-insensitive) against the dag_id, description, owners, and tag names. Returns a matches envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const root = await airflowGet("/api/v1/dags?limit=100&offset=0");
+      const matches = filterAirflowDags(dagsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+}

package/connectors/apple/src/adapters.ts

@@ -0,0 +1,326 @@
+/**
+ * The real iCloud clients: IMAP, SMTP, IMAP-APPEND drafts and CalDAV.
+ *
+ * These used to live in `server.ts`, under a comment explaining that the
+ * imapflow message-shaping helpers were "copied locally; cross-importing
+ * ../../imap/src/* is forbidden … server.ts is coverage-excluded so this copy
+ * is acceptable". Both halves of that reasoning have since stopped holding:
+ * the shared copy now lives in `shared/imapflow-adapter.ts`, which every
+ * connector may import, and `server.ts` is no longer coverage-excluded. What
+ * the copy actually cost was 45 duplicated lines against the imap connector and
+ * a divergence that mattered — the shared `withMailbox` leaked a connection
+ * when the mailbox lock failed, and this file's version was the one that had it
+ * right.
+ *
+ * So the IMAP and SMTP clients are now the shared adapter with iCloud's
+ * configuration, and only what is genuinely Apple-specific is written out here:
+ * the Drafts APPEND and the two-phase CalDAV login.
+ *
+ * Nothing here constructs itself at import time, so a test can build any of it
+ * against a fake and never open a socket.
+ */
+
+import { type ParsedEvent, parseICalendar } from "@nimbus-dev/sdk";
+import { ImapFlow } from "imapflow";
+import { type DAVCalendar, DAVClient } from "tsdav";
+import {
+  createImapFlowClient,
+  createNodemailerMailer,
+  type ImapFlowFactory,
+  type TransportFactory,
+} from "../../../shared/imapflow-adapter.ts";
+import type {
+  DraftAppender,
+  DraftInput,
+  DraftResult,
+  EmailReadClient,
+  EmailSendMailer,
+} from "./apple-mail-core.ts";
+import {
+  type CalDavClient,
+  type CalendarRef,
+  caldavObjectFilename,
+  type EventWindow,
+} from "./caldav-core.ts";
+
+// ---------------------------------------------------------------------------
+// Fixed iCloud endpoints
+// ---------------------------------------------------------------------------
+
+export const ICLOUD_IMAP_HOST = "imap.mail.me.com";
+export const ICLOUD_IMAP_PORT = 993;
+export const ICLOUD_SMTP_HOST = "smtp.mail.me.com";
+export const ICLOUD_SMTP_PORT = 587;
+export const ICLOUD_CALDAV_BOOTSTRAP_URL = "https://caldav.icloud.com";
+export const DRAFTS_MAILBOX = "Drafts";
+
+/** The iCloud IMAP read client. */
+export function createAppleImapClient(
+  user: string,
+  pass: string,
+  newImapFlow?: ImapFlowFactory,
+): EmailReadClient {
+  return createImapFlowClient(
+    { host: ICLOUD_IMAP_HOST, port: ICLOUD_IMAP_PORT, user, pass, secure: true },
+    newImapFlow,
+  );
+}
+
+/**
+ * The iCloud SMTP mailer.
+ *
+ * Port 587 is STARTTLS, not implicit TLS. The shared mailer requires STARTTLS
+ * whenever TLS is not implicit and offers no way to opt out, so the credentials
+ * cannot reach the wire unencrypted; iCloud always advertises it. `from` is
+ * pinned to the authenticated address by the shared mailer.
+ */
+export function createAppleSmtpMailer(
+  user: string,
+  pass: string,
+  makeTransport?: TransportFactory,
+): EmailSendMailer {
+  return createNodemailerMailer(
+    { host: ICLOUD_SMTP_HOST, port: ICLOUD_SMTP_PORT, user, pass, secure: false },
+    makeTransport,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// DraftAppender — IMAP APPEND to "Drafts" via imapflow
+// From is PINNED to the authenticated icloud_email (forced sender contract).
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a minimal RFC 5322 message from the given inputs.
+ * The From header is always set to `from` (the pinned icloud_email).
+ */
+export function buildRfc822Message(from: string, input: DraftInput): string {
+  const lines: string[] = [];
+  lines.push(`From: ${from}`, `To: ${input.to}`);
+  if (input.cc !== undefined && input.cc !== "") {
+    lines.push(`Cc: ${input.cc}`);
+  }
+  if (input.bcc !== undefined && input.bcc !== "") {
+    lines.push(`Bcc: ${input.bcc}`);
+  }
+  // The body may contain non-ASCII (UTF-8) characters, so it cannot be declared
+  // 7bit. Base64-encode it (wrapped at 76 chars per RFC 2045) so the APPENDed
+  // message is well-formed regardless of content.
+  lines.push(
+    `Subject: ${input.subject}`,
+    "MIME-Version: 1.0",
+    "Content-Type: text/plain; charset=UTF-8",
+    "Content-Transfer-Encoding: base64",
+    "",
+  );
+  const encoded = Buffer.from(input.body, "utf8").toString("base64");
+  lines.push(encoded.replace(/.{76}/g, "$&\r\n"));
+  // RFC 5322 uses CRLF line endings.
+  return lines.join("\r\n");
+}
+
+/** Minimal imapflow surface the draft appender uses. */
+export interface AppendCapableFlow {
+  connect(): Promise<void>;
+  logout(): Promise<void>;
+  append(mailbox: string, content: Buffer, flags: string[]): Promise<unknown>;
+}
+
+class AppleDraftAppender implements DraftAppender {
+  constructor(
+    private readonly user: string,
+    private readonly pass: string,
+    private readonly newFlow: (user: string, pass: string) => AppendCapableFlow,
+  ) {}
+
+  async appendDraft(input: DraftInput): Promise<DraftResult> {
+    const flow = this.newFlow(this.user, this.pass);
+    await flow.connect();
+    try {
+      // Build the RFC 5322 message with From pinned to the authenticated email.
+      const raw = buildRfc822Message(this.user, input);
+      const buf = Buffer.from(raw, "utf8");
+
+      // IMAP APPEND to the Drafts mailbox. imapflow returns the assigned UID
+      // when the server supports APPENDUID or UIDPLUS — it may return undefined
+      // when neither is available, which is valid.
+      const result = await flow.append(DRAFTS_MAILBOX, buf, [String.raw`\Draft`]);
+      const uid = (result as { uid?: number } | undefined)?.uid ?? null;
+      return { uid: uid === undefined ? null : uid, mailbox: DRAFTS_MAILBOX };
+    } finally {
+      await flow.logout();
+    }
+  }
+}
+
+function realAppendFlow(user: string, pass: string): AppendCapableFlow {
+  return new ImapFlow({
+    host: ICLOUD_IMAP_HOST,
+    port: ICLOUD_IMAP_PORT,
+    secure: true,
+    auth: { user, pass },
+    logger: false,
+  }) as unknown as AppendCapableFlow;
+}
+
+/** The Drafts-mailbox appender. `newFlow` is overridden in tests. */
+export function createAppleDraftAppender(
+  user: string,
+  pass: string,
+  newFlow: (user: string, pass: string) => AppendCapableFlow = realAppendFlow,
+): DraftAppender {
+  return new AppleDraftAppender(user, pass, newFlow);
+}
+
+// ---------------------------------------------------------------------------
+// CalDavClient — tsdav DAVClient (two-phase: bootstrap discover then working)
+//
+// iCloud CalDAV authenticates against caldav.icloud.com but redirects to a
+// user-specific host (p##-caldav.icloud.com). login() resolves the principal +
+// calendar-home-set and binds the credentials to the resolved host so that
+// Basic auth is applied on every subsequent request — without relying on
+// transparent cross-host redirect forwarding.
+// ---------------------------------------------------------------------------
+
+/** The subset of tsdav's `DAVClient` this adapter drives. Faked in tests. */
+export interface DavClientLike {
+  login(): Promise<unknown>;
+  fetchCalendars(): Promise<DAVCalendar[]>;
+  fetchCalendarObjects(params: {
+    calendar: DAVCalendar;
+    timeRange?: { start: string; end: string };
+    expand?: boolean;
+  }): Promise<{ url: string; data?: unknown }[]>;
+  createCalendarObject(params: {
+    calendar: DAVCalendar;
+    iCalString: string;
+    filename: string;
+  }): Promise<unknown>;
+  deleteCalendarObject(params: { calendarObject: { url: string; etag: string } }): Promise<unknown>;
+}
+
+/** A CalDAV client with the login step the iCloud redirect dance requires. */
+export interface LoggingInCalDavClient extends CalDavClient {
+  login(): Promise<void>;
+}
+
+class TsdavCalDavClient implements LoggingInCalDavClient {
+  /**
+   * Discovered DAVCalendar objects keyed by their url. Populated after the
+   * first listCalendars() call so that putEvent/listEvents can obtain the
+   * full DAVCalendar object (which carries the account reference that tsdav
+   * needs for auth on the resolved p##-caldav.icloud.com host).
+   */
+  private discovered: Map<string, DAVCalendar> = new Map();
+
+  constructor(private readonly davClient: DavClientLike) {}
+
+  async login(): Promise<void> {
+    await this.davClient.login();
+  }
+
+  async listCalendars(): Promise<CalendarRef[]> {
+    const cals = await this.davClient.fetchCalendars();
+    // Refresh the discovery cache.
+    this.discovered = new Map();
+    for (const cal of cals) {
+      this.discovered.set(cal.url, cal);
+    }
+    return cals.map((cal) => ({
+      url: cal.url,
+      displayName:
+        typeof cal.displayName === "string" && cal.displayName !== "" ? cal.displayName : cal.url,
+    }));
+  }
+
+  /**
+   * Resolve a CalendarRef to the underlying DAVCalendar tsdav needs.
+   * If not found in cache, constructs a minimal DAVCalendar using just the url
+   * (tsdav fetchCalendarObjects only strictly requires `calendar.url`).
+   */
+  private toDavCalendar(cal: CalendarRef): DAVCalendar {
+    return this.discovered.get(cal.url) ?? { url: cal.url };
+  }
+
+  async listEvents(
+    cal: CalendarRef,
+    window: EventWindow,
+  ): Promise<{ href: string; event: ParsedEvent }[]> {
+    const objects = await this.davClient.fetchCalendarObjects({
+      calendar: this.toDavCalendar(cal),
+      timeRange: { start: window.startUtc, end: window.endUtc },
+      // expand: true triggers server-side recurrence expansion (C:expand in
+      // the REPORT) — required per spec; no client-side RRULE engine.
+      expand: true,
+    });
+
+    const results: { href: string; event: ParsedEvent }[] = [];
+    for (const obj of objects) {
+      if (typeof obj.data !== "string" || obj.data === "") {
+        continue;
+      }
+      for (const event of parseICalendar(obj.data)) {
+        results.push({ href: obj.url, event });
+      }
+    }
+    return results;
+  }
+
+  async putEvent(cal: CalendarRef, uid: string, ics: string): Promise<{ href: string }> {
+    // The UID is embedded into the object URL path segment; sanitize it so a
+    // summary-derived UID with `/`, `#`, `%`, etc. cannot corrupt the href.
+    const filename = caldavObjectFilename(uid);
+    await this.davClient.createCalendarObject({
+      calendar: this.toDavCalendar(cal),
+      iCalString: ics,
+      filename,
+    });
+    // The href of the newly created object is conventionally the calendar URL
+    // joined with the filename. tsdav does not return a Location header
+    // wrapper, so we construct it from the calendar URL.
+    const href = cal.url.endsWith("/") ? `${cal.url}${filename}` : `${cal.url}/${filename}`;
+    return { href };
+  }
+
+  async deleteEvent(href: string): Promise<void> {
+    // etag: "" means "unconditional delete" — acceptable because we don't track
+    // etags in the CalendarRef/EventWindow flow.
+    await this.davClient.deleteCalendarObject({
+      calendarObject: { url: href, etag: "" },
+    });
+  }
+}
+
+function realDavClient(email: string, appPw: string): DavClientLike {
+  // login() performs principal + calendar-home discovery and binds the
+  // credentials to all subsequent requests against the resolved
+  // p##-caldav.icloud.com host — satisfying the auth-on-redirect requirement.
+  return new DAVClient({
+    serverUrl: ICLOUD_CALDAV_BOOTSTRAP_URL,
+    credentials: { username: email, password: appPw },
+    authMethod: "Basic",
+    defaultAccountType: "caldav",
+  }) as unknown as DavClientLike;
+}
+
+/** The iCloud CalDAV client. `makeDavClient` is overridden in tests. */
+export function createAppleCalDavClient(
+  email: string,
+  appPw: string,
+  makeDavClient: (email: string, appPw: string) => DavClientLike = realDavClient,
+): LoggingInCalDavClient {
+  return new TsdavCalDavClient(makeDavClient(email, appPw));
+}
+
+/**
+ * iCalendar DTSTAMP format (RFC 5545): `YYYYMMDDTHHMMSSZ`.
+ *
+ * `buildVEvent` emits the value verbatim, so it must NOT be ISO-8601 — no
+ * hyphens, colons or milliseconds.
+ */
+export function icalTimestamp(at: Date = new Date()): string {
+  return at
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\.\d+Z$/, "Z");
+}

package/connectors/apple/src/apple-mail-core.ts

@@ -9,6 +9,8 @@
  * the connector must satisfy (EmailReadClient/EmailSendMailer/EmailMessageMeta).
  */
 
+import type { OutgoingMail } from "../../../shared/imap-tool-kit.ts";
+
 export {
   capPreview,
   clampLimit,
@@ -16,7 +18,6 @@ export {
   PREVIEW_FETCH_BYTES,
   PREVIEW_MAX_CHARS,
 } from "../../../shared/imap-mail-core.ts";
-
 // The shared kit already defines the structural client/mailer/message contracts
 // the connector must satisfy (EmailReadClient/EmailSendMailer/EmailMessageMeta).
 export type {
@@ -25,13 +26,8 @@ export type {
   EmailSendMailer,
 } from "../../../shared/imap-tool-kit.ts";
 
-export interface DraftInput {
-  readonly to: string;
-  readonly subject: string;
-  readonly body: string;
-  readonly cc?: string;
-  readonly bcc?: string;
-}
+/** A draft is the same outgoing message a send tool hands its transport. */
+export type DraftInput = OutgoingMail;
 
 export interface DraftResult {
   readonly uid: number | null;

package/connectors/apple/src/calendar-tools.ts

@@ -1,4 +1,8 @@
-import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  type ConsentServer,
+  createWriteToolRegistrar,
+  type WriteToolRegistrar,
+} from "../../../shared/consent-kit.ts";
 /**
  * Apple Calendar tool handlers (read + write) over an injected CalDavClient.
  *
@@ -76,6 +80,22 @@ interface ViewEvent {
 
 const DEFAULT_MAX_INSTANCES = 200;
 
+/**
+ * The apple connector's ONE write-scope configuration, for its mail and calendar writes alike.
+ *
+ * Both read NIMBUS_MCP_APPLE_WRITE_SCOPE, and the consent kit refuses at startup a scope term
+ * whose kind its registrar did not declare. They used to be built by two registrars declaring one
+ * kind each, so every non-empty scope was fatal: a `recipient:` term crashed the calendar
+ * registrar and a `calendar:` term the mail one, leaving standalone apple unable to enable any
+ * write at all. One registrar declaring both kinds also gives the connector one write budget,
+ * where two had silently doubled it.
+ */
+export const APPLE_WRITE_SCOPE = {
+  connector: "apple",
+  scopeEnv: "NIMBUS_MCP_APPLE_WRITE_SCOPE",
+  scopeKinds: ["recipient", "calendar"],
+} as const;
+
 // ---------------------------------------------------------------------------
 // registerAppleCalendarTools
 // ---------------------------------------------------------------------------
@@ -86,7 +106,9 @@ const DEFAULT_MAX_INSTANCES = 200;
  * @param server  - The MCP server instance.
  * @param options - Injected dependencies: the CalDAV client, a `now` factory
  *                  (returns the current UTC timestamp in iCalendar DTSTAMP
- *                  format, e.g. "20260601T090000Z"), and optional config.
+ *                  format, e.g. "20260601T090000Z"), optional config, and the
+ *                  write registrar to share with the connector's mail writes
+ *                  (built from {@link APPLE_WRITE_SCOPE} when omitted).
  */
 export function registerAppleCalendarTools(
   // Widened: the consent kit needs the real server surface, not just the `.tool` shim.
@@ -95,6 +117,7 @@ export function registerAppleCalendarTools(
     calendar: CalDavClient;
     now: () => string;
     config?: CalendarToolConfig | undefined;
+    registerWriteTool?: WriteToolRegistrar | undefined;
   },
 ): void {
   const { calendar, now, config } = options;
@@ -132,7 +155,7 @@ export function registerAppleCalendarTools(
       const items: ViewEvent[] = [];
 
       for (const cal of allCals) {
-        const rows = await calendar.listEvents(cal, window);
+        const rows = await calendar.listEvents(cal, window); // NOSONAR S9382: calendars are queried in order until maxInstances is reached — each clamp depends on how many events the earlier calendars returned, and a calendar past the cap is never queried at all.
         const clamped = clampInstances(rows, maxInstances - items.length);
 
         for (const { href, event } of clamped) {
@@ -166,11 +189,8 @@ export function registerAppleCalendarTools(
   // apple_calendar_event_create
   // -------------------------------------------------------------------------
 
-  const registerWriteTool = createWriteToolRegistrar(server, {
-    connector: "apple",
-    scopeEnv: "NIMBUS_MCP_APPLE_WRITE_SCOPE",
-    scopeKinds: ["calendar"],
-  });
+  const registerWriteTool =
+    options.registerWriteTool ?? createWriteToolRegistrar(server, APPLE_WRITE_SCOPE);
 
   registerWriteTool(
     "apple_calendar_event_create",