@nimbus-dev/connectors 0.2.0 → 0.2.2

package/connectors/zoom/src/server.ts

@@ -1,98 +1,6 @@
-import { z } from "zod";
-import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
 import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
-import { encodeZoomMeetingPathSegment } from "./encode-meeting-path.ts";
-import { validateZoomRecordingsWindow } from "./recordings-window.ts";
-import { filterZoomMeetings } from "./search-filter.ts";
-
-const BASE = "https://api.zoom.us";
-
-function apiToken(): string {
-  const t = process.env["ZOOM_TOKEN"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("ZOOM_TOKEN is not set");
-  }
-  return t;
-}
-
-function authHeader(): Record<string, string> {
-  return { Authorization: `Bearer ${apiToken()}`, Accept: "application/json" };
-}
-
-async function zoomGet(path: string): Promise<unknown> {
-  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`Zoom ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text) as unknown;
-}
+import { registerZoomTools } from "./tools.ts";
 
 await runReadOnlyMcpConnector("nimbus-zoom", (reg) => {
-  reg(
-    "zoom_list",
-    "List the authenticated user's scheduled Zoom meetings (`GET /v2/users/me/meetings?type=scheduled&page_size=100`). Returns the `{ meetings: [...], next_page_token, page_size, total_records }` envelope — `meetings` holds the meeting objects.",
-    z.object({}),
-    async () => {
-      return jsonResult(await zoomGet("/v2/users/me/meetings?type=scheduled&page_size=100"));
-    },
-  );
-
-  reg(
-    "zoom_get",
-    "Fetch one Zoom meeting by its numeric meeting id OR its UUID (`GET /v2/meetings/{meetingId}`). Returns the meeting object directly (NOT wrapped in `{ meetings }`). Throws when no match is found. UUIDs are auto-double-encoded when they start with `/` or contain `//` (Zoom's documented requirement).",
-    z.object({
-      id: z.string().min(1),
-    }),
-    async (p) => {
-      return jsonResult(await zoomGet(`/v2/meetings/${encodeZoomMeetingPathSegment(p.id)}`));
-    },
-  );
-
-  reg(
-    "zoom_search",
-    "**Substring search over the FIRST PAGE only** (up to 100 most recently-listed scheduled meetings) of the authenticated user's Zoom meetings. The Zoom REST API has no native text-search endpoint for meetings; this tool fetches `GET /v2/users/me/meetings?type=scheduled&page_size=100` once and matches the query locally against the meeting topic, agenda, and host id (case-insensitive). **Meetings older than the first page are not searchable here — query the local Nimbus index instead for full coverage.** Returns a `{ matches: [...] }` envelope.",
-    z.object({
-      query: z.string().min(1),
-      limit: z.number().int().min(1).max(100).optional(),
-    }),
-    async (p) => {
-      const root = await zoomGet("/v2/users/me/meetings?type=scheduled&page_size=100");
-      const meetings = (root as { meetings?: unknown[] } | null)?.meetings;
-      const filterOptions =
-        p.limit === undefined ? { query: p.query } : { query: p.query, limit: p.limit };
-      const matches = Array.isArray(meetings) ? filterZoomMeetings(meetings, filterOptions) : [];
-      return jsonResult({ matches });
-    },
-  );
-
-  reg(
-    "zoom_recordings_list",
-    'List the authenticated user\'s cloud recordings in a date window (`GET /v2/users/me/recordings?from=&to=&page_size=100`). `from` and `to` are ISO-8601 date strings (YYYY-MM-DD or full ISO); **Zoom requires (to - from) <= 1 month** — this tool validates that locally and throws a clear error before consuming a Zoom API call. Returns the `{ meetings: [{ id, uuid, topic, recording_files: [{ id, file_type, recording_start, play_url, download_url, ... }] }], next_page_token, page_size, total_records, from, to }` envelope. **Transcript files (`file_type: "TRANSCRIPT"`) carry the speech-to-text content** — Nimbus indexes those as `zoom:transcript` items; for full transcript text query the local Nimbus index instead of refetching `download_url` from here.',
-    z.object({
-      from: z
-        .string()
-        .min(1)
-        .describe("ISO-8601 start of window (e.g. '2026-05-01' or '2026-05-01T00:00:00Z')"),
-      to: z.string().min(1).describe("ISO-8601 end of window; (to - from) must be <= 31 days"),
-    }),
-    async (p) => {
-      validateZoomRecordingsWindow(p.from, p.to);
-      const params = new URLSearchParams({ from: p.from, to: p.to, page_size: "100" });
-      return jsonResult(await zoomGet(`/v2/users/me/recordings?${params.toString()}`));
-    },
-  );
-
-  reg(
-    "zoom_transcript_get",
-    "Fetch the recording-file inventory for one meeting (`GET /v2/meetings/{meetingId}/recordings`). Use this to discover transcript file ids + metadata for a specific meeting; returns the `{ uuid, id, topic, recording_files: [...] }` shape. UUIDs are auto-double-encoded when they start with `/` or contain `//` (Zoom's documented requirement). **For the actual transcript TEXT, query the local Nimbus index** (`zoom:transcript` items, keyed by `<meeting_uuid>:<recording_file_id>`). This tool does NOT refetch + parse the VTT — that work is owned by the gateway-side syncable.",
-    z.object({
-      id: z.string().min(1).describe("Meeting numeric id (preferred) or meeting UUID"),
-    }),
-    async (p) => {
-      return jsonResult(
-        await zoomGet(`/v2/meetings/${encodeZoomMeetingPathSegment(p.id)}/recordings`),
-      );
-    },
-  );
+  registerZoomTools(reg);
 });

package/connectors/zoom/src/tools.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { createJsonGetter, envAuthHeaders } from "../../../shared/env-json-api.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import { encodeZoomMeetingPathSegment } from "./encode-meeting-path.ts";
+import { validateZoomRecordingsWindow } from "./recordings-window.ts";
+import { filterZoomMeetings } from "./search-filter.ts";
+
+const BASE = "https://api.zoom.us";
+
+const zoomGet = createJsonGetter({
+  base: BASE,
+  label: "Zoom",
+  headers: envAuthHeaders({ env: "ZOOM_TOKEN" }),
+});
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const ZOOM_TOOL_NAMES = [
+  "zoom_list",
+  "zoom_get",
+  "zoom_search",
+  "zoom_recordings_list",
+  "zoom_transcript_get",
+] as const;
+
+export function registerZoomTools(reg: ZodToolRegistrar): void {
+  reg(
+    "zoom_list",
+    "List the authenticated user's scheduled Zoom meetings (`GET /v2/users/me/meetings?type=scheduled&page_size=100`). Returns the `{ meetings: [...], next_page_token, page_size, total_records }` envelope — `meetings` holds the meeting objects.",
+    z.object({}),
+    async () => {
+      return jsonResult(await zoomGet("/v2/users/me/meetings?type=scheduled&page_size=100"));
+    },
+  );
+
+  reg(
+    "zoom_get",
+    "Fetch one Zoom meeting by its numeric meeting id OR its UUID (`GET /v2/meetings/{meetingId}`). Returns the meeting object directly (NOT wrapped in `{ meetings }`). Throws when no match is found. UUIDs are auto-double-encoded when they start with `/` or contain `//` (Zoom's documented requirement).",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await zoomGet(`/v2/meetings/${encodeZoomMeetingPathSegment(p.id)}`));
+    },
+  );
+
+  reg(
+    "zoom_search",
+    "**Substring search over the FIRST PAGE only** (up to 100 most recently-listed scheduled meetings) of the authenticated user's Zoom meetings. The Zoom REST API has no native text-search endpoint for meetings; this tool fetches `GET /v2/users/me/meetings?type=scheduled&page_size=100` once and matches the query locally against the meeting topic, agenda, and host id (case-insensitive). **Meetings older than the first page are not searchable here — query the local Nimbus index instead for full coverage.** Returns a `{ matches: [...] }` envelope.",
+    z.object({
+      query: z.string().min(1),
+      limit: z.number().int().min(1).max(100).optional(),
+    }),
+    async (p) => {
+      const root = await zoomGet("/v2/users/me/meetings?type=scheduled&page_size=100");
+      const meetings = (root as { meetings?: unknown[] } | null)?.meetings;
+      const filterOptions =
+        p.limit === undefined ? { query: p.query } : { query: p.query, limit: p.limit };
+      const matches = Array.isArray(meetings) ? filterZoomMeetings(meetings, filterOptions) : [];
+      return jsonResult({ matches });
+    },
+  );
+
+  reg(
+    "zoom_recordings_list",
+    'List the authenticated user\'s cloud recordings in a date window (`GET /v2/users/me/recordings?from=&to=&page_size=100`). `from` and `to` are ISO-8601 date strings (YYYY-MM-DD or full ISO); **Zoom requires (to - from) <= 1 month** — this tool validates that locally and throws a clear error before consuming a Zoom API call. Returns the `{ meetings: [{ id, uuid, topic, recording_files: [{ id, file_type, recording_start, play_url, download_url, ... }] }], next_page_token, page_size, total_records, from, to }` envelope. **Transcript files (`file_type: "TRANSCRIPT"`) carry the speech-to-text content** — Nimbus indexes those as `zoom:transcript` items; for full transcript text query the local Nimbus index instead of refetching `download_url` from here.',
+    z.object({
+      from: z
+        .string()
+        .min(1)
+        .describe("ISO-8601 start of window (e.g. '2026-05-01' or '2026-05-01T00:00:00Z')"),
+      to: z.string().min(1).describe("ISO-8601 end of window; (to - from) must be <= 31 days"),
+    }),
+    async (p) => {
+      validateZoomRecordingsWindow(p.from, p.to);
+      const params = new URLSearchParams({ from: p.from, to: p.to, page_size: "100" });
+      return jsonResult(await zoomGet(`/v2/users/me/recordings?${params.toString()}`));
+    },
+  );
+
+  reg(
+    "zoom_transcript_get",
+    "Fetch the recording-file inventory for one meeting (`GET /v2/meetings/{meetingId}/recordings`). Use this to discover transcript file ids + metadata for a specific meeting; returns the `{ uuid, id, topic, recording_files: [...] }` shape. UUIDs are auto-double-encoded when they start with `/` or contain `//` (Zoom's documented requirement). **For the actual transcript TEXT, query the local Nimbus index** (`zoom:transcript` items, keyed by `<meeting_uuid>:<recording_file_id>`). This tool does NOT refetch + parse the VTT — that work is owned by the gateway-side syncable.",
+    z.object({
+      id: z.string().min(1).describe("Meeting numeric id (preferred) or meeting UUID"),
+    }),
+    async (p) => {
+      return jsonResult(
+        await zoomGet(`/v2/meetings/${encodeZoomMeetingPathSegment(p.id)}/recordings`),
+      );
+    },
+  );
+}

package/connectors/zotero/src/server.ts

@@ -1,82 +1,6 @@
-import { z } from "zod";
-import { matchesResult, searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
-import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
 import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
-import { filterZoteroItems } from "./search-filter.ts";
-
-const BASE = "https://api.zotero.org";
-
-function apiKey(): string {
-  const k = process.env["ZOTERO_API_KEY"]?.trim();
-  if (k === undefined || k === "") {
-    throw new Error("ZOTERO_API_KEY is not set");
-  }
-  return k;
-}
-
-function library(): string {
-  const l = process.env["ZOTERO_LIBRARY"]?.trim();
-  if (l === undefined || l === "") {
-    throw new Error("ZOTERO_LIBRARY is not set");
-  }
-  return l;
-}
-
-function authHeader(): Record<string, string> {
-  return {
-    "Zotero-API-Key": apiKey(),
-    "Zotero-API-Version": "3",
-    Accept: "application/json",
-  };
-}
-
-async function zoteroGet(path: string): Promise<unknown> {
-  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`Zotero ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text) as unknown;
-}
-
-function itemsBasePath(): string {
-  return `/${library()}/items`;
-}
+import { registerZoteroTools } from "./tools.ts";
 
 await runReadOnlyMcpConnector("nimbus-zotero", (reg) => {
-  reg(
-    "zotero_list",
-    "List the top-level items in the configured Zotero library (`GET /<library>/items?format=json&limit=100&start=0&sort=dateModified&direction=desc`). The `<library>` path segment is the configured library spec (e.g. `users/12345` or `groups/98765`). Returns the raw JSON array of item objects — each is `{ key, version, library, data: { itemType, title, creators, date, dateModified, tags, collections, DOI, url, abstractNote, ... } }`.",
-    z.object({}),
-    async () => {
-      return jsonResult(
-        await zoteroGet(
-          `${itemsBasePath()}?format=json&limit=100&start=0&sort=dateModified&direction=desc`,
-        ),
-      );
-    },
-  );
-
-  reg(
-    "zotero_get",
-    "Fetch one Zotero item by its item key (`GET /<library>/items/{key}`). Returns the item object directly (NOT wrapped in an array). Throws when no match is found.",
-    z.object({
-      key: z.string().min(1),
-    }),
-    async (p) => {
-      return jsonResult(await zoteroGet(`${itemsBasePath()}/${encodeURIComponent(p.key)}`));
-    },
-  );
-
-  reg(
-    "zotero_search",
-    "Substring search across the library's top-level items (first page only). Matches the query against the title, item type, abstract, DOI, publication title, formatted creator names, and tag names (case-insensitive). Returns a `{ matches: [...] }` envelope.",
-    searchToolInputSchema(100),
-    async (p) => {
-      const root = await zoteroGet(
-        `${itemsBasePath()}?format=json&limit=100&start=0&sort=dateModified&direction=desc`,
-      );
-      return matchesResult(root, filterZoteroItems, p);
-    },
-  );
+  registerZoteroTools(reg);
 });

package/connectors/zotero/src/tools.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { createJsonGetter, requiredEnv } from "../../../shared/env-json-api.ts";
+import { matchesResult, searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterZoteroItems } from "./search-filter.ts";
+
+const BASE = "https://api.zotero.org";
+
+function authHeader(): Record<string, string> {
+  return {
+    "Zotero-API-Key": requiredEnv("ZOTERO_API_KEY"),
+    "Zotero-API-Version": "3",
+    Accept: "application/json",
+  };
+}
+
+const zoteroGet = createJsonGetter({
+  base: BASE,
+  label: "Zotero",
+  headers: authHeader,
+});
+
+function itemsBasePath(): string {
+  return `/${requiredEnv("ZOTERO_LIBRARY")}/items`;
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const ZOTERO_TOOL_NAMES = ["zotero_get", "zotero_list", "zotero_search"] as const;
+
+export function registerZoteroTools(reg: ZodToolRegistrar): void {
+  reg(
+    "zotero_list",
+    "List the top-level items in the configured Zotero library (`GET /<library>/items?format=json&limit=100&start=0&sort=dateModified&direction=desc`). The `<library>` path segment is the configured library spec (e.g. `users/12345` or `groups/98765`). Returns the raw JSON array of item objects — each is `{ key, version, library, data: { itemType, title, creators, date, dateModified, tags, collections, DOI, url, abstractNote, ... } }`.",
+    z.object({}),
+    async () => {
+      return jsonResult(
+        await zoteroGet(
+          `${itemsBasePath()}?format=json&limit=100&start=0&sort=dateModified&direction=desc`,
+        ),
+      );
+    },
+  );
+
+  reg(
+    "zotero_get",
+    "Fetch one Zotero item by its item key (`GET /<library>/items/{key}`). Returns the item object directly (NOT wrapped in an array). Throws when no match is found.",
+    z.object({
+      key: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await zoteroGet(`${itemsBasePath()}/${encodeURIComponent(p.key)}`));
+    },
+  );
+
+  reg(
+    "zotero_search",
+    "Substring search across the library's top-level items (first page only). Matches the query against the title, item type, abstract, DOI, publication title, formatted creator names, and tag names (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const root = await zoteroGet(
+        `${itemsBasePath()}?format=json&limit=100&start=0&sort=dateModified&direction=desc`,
+      );
+      return matchesResult(root, filterZoteroItems, p);
+    },
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-dev/connectors",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "publishConfig": {
     "access": "public"
   },
@@ -25,10 +25,10 @@
     "!**/*.test.ts"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.30.0",
-    "@nimbus-dev/sdk": "^1.20.0",
-    "@types/nodemailer": "^7.0.4",
-    "zod": "^4.4.2"
+    "@modelcontextprotocol/sdk": "1.32.0",
+    "@nimbus-dev/sdk": "^2.0.0",
+    "@types/nodemailer": "^8.0.2",
+    "zod": "^4.6.5"
   },
   "exports": {
     ".": "./standalone/src/bin.ts",
@@ -131,6 +131,7 @@
   },
   "scripts": {
     "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-reporter=text",
     "test:sandbox": "bun scripts/run-sandbox-contract.ts",
     "lint": "biome check --error-on-warnings .",
     "lint:fix": "biome check --write .",
@@ -138,20 +139,22 @@
     "audit:connector-consent": "bun scripts/check-connector-consent.ts",
     "audit:connector-deps": "bun scripts/check-connector-deps.ts",
     "audit:connector-entrypoints": "bun scripts/check-connector-entrypoints.ts",
-    "check": "bun run lint && bun run typecheck && bun run audit:connector-consent && bun run audit:connector-deps && bun run audit:connector-entrypoints && bun run test"
+    "audit:tool-names": "bun scripts/sync-tool-names.ts --check",
+    "sync:tool-names": "bun scripts/sync-tool-names.ts",
+    "check": "bun run lint && bun run typecheck && bun run audit:connector-consent && bun run audit:connector-deps && bun run audit:connector-entrypoints && bun run audit:tool-names && bun run test"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.10",
-    "@types/bun": "^1.4.0",
+    "@biomejs/biome": "^2.5.15",
+    "@types/bun": "^1.4.2",
     "typescript": "^7.0.2"
   },
   "engines": {
     "bun": ">=1.2.0"
   },
   "optionalDependencies": {
-    "hyparquet": "^1.29.1",
-    "imapflow": "^1.7.2",
-    "nodemailer": "^9.0.5",
-    "tsdav": "^2.3.1"
+    "hyparquet": "^1.31.2",
+    "imapflow": "^2.2.4",
+    "nodemailer": "^10.0.14",
+    "tsdav": "^2.3.5"
   }
 }

package/shared/access-token-cache.ts

@@ -0,0 +1,123 @@
+/**
+ * access-token-cache — the "exchange credentials for a short-lived access
+ * token, then reuse it" pattern.
+ *
+ * Three connectors reach an API that will not take their configured credential
+ * directly: Ramp and Wiz exchange a client id/secret at an OAuth token
+ * endpoint, Superset posts a username/password to its own `/security/login`.
+ * All three then cache the result for the life of the process, and all three
+ * had written out the same tail by hand —
+ *
+ *   POST → non-2xx? throw `<label> <status>: <body>` → JSON.parse, and throw a
+ *   distinct error when the body is not JSON → reject a missing or empty
+ *   `access_token` → cache → return
+ *
+ * — which is four failure modes each of which is easy to get subtly wrong, and
+ * which Sonar flagged as duplicated between Ramp and Superset.
+ *
+ * The exchange REQUEST is not shared, only its result handling: an OAuth
+ * client-credentials POST and a JSON login POST have genuinely different
+ * bodies, headers and endpoints, and collapsing them would mean a config object
+ * that is really two shapes in a trench coat.
+ */
+
+/** What a successful exchange yields. */
+export interface AccessTokenResponse {
+  readonly ok: boolean;
+  readonly status: number;
+  readonly text: string;
+}
+
+export interface AccessTokenCacheConfig {
+  /**
+   * Prefix for every error, naming the exchange rather than the service — e.g.
+   * `"Ramp token exchange"`, `"Superset login"`. It is what tells a caller that
+   * the failure was authentication, not the request they actually made.
+   */
+  readonly label: string;
+  /** Performs the exchange. Called at most once per process, lazily. */
+  readonly exchange: () => Promise<AccessTokenResponse>;
+  /**
+   * Field holding the token in the parsed body. Defaults to `access_token`,
+   * which is what all three of these APIs return.
+   */
+  readonly tokenField?: string;
+  /** Body-snippet length in the thrown error. */
+  readonly snippetMax?: number;
+}
+
+/** Body-snippet length in the thrown error. The value every connector used. */
+export const DEFAULT_SNIPPET_MAX = 400;
+
+/** The getter {@link createAccessTokenCache} returns: call it for the token. */
+export interface AccessTokenCache {
+  (): Promise<string>;
+  /**
+   * Forget the cached token, so the next call exchanges again. For tests: the
+   * cache lives as long as the module, which in a test run is the whole process,
+   * so a token one test obtained would otherwise answer every later test's call
+   * without that call's credentials ever being read.
+   */
+  clear(): void;
+}
+
+/**
+ * A `() => Promise<string>` that performs the exchange once and then returns
+ * the cached token.
+ *
+ * Only a SUCCESSFUL exchange is cached. Caching a failure would make one
+ * transient 503 at startup poison every later call for the life of the process,
+ * which for a long-running stdio connector means until the client restarts it.
+ *
+ * Concurrent first calls share ONE exchange. An MCP client may have several
+ * tool calls in flight at once, and each would otherwise find an empty cache
+ * and start its own token request — n simultaneous OAuth exchanges for one
+ * connector, which is both wasteful and a good way to meet a rate limit on the
+ * auth endpoint. The in-flight promise is cleared whichever way it settles, so
+ * a failed exchange stays retryable.
+ */
+export function createAccessTokenCache(config: AccessTokenCacheConfig): AccessTokenCache {
+  const field = config.tokenField ?? "access_token";
+  const snippetMax = config.snippetMax ?? DEFAULT_SNIPPET_MAX;
+  let cached: string | null = null;
+  let inFlight: Promise<string> | null = null;
+
+  async function exchangeOnce(): Promise<string> {
+    const res = await config.exchange();
+    if (!res.ok) {
+      throw new Error(`${config.label} ${String(res.status)}: ${res.text.slice(0, snippetMax)}`);
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(res.text) as unknown;
+    } catch {
+      throw new Error(`${config.label}: invalid JSON response`);
+    }
+    const token = (parsed as Record<string, unknown> | null)?.[field];
+    if (typeof token !== "string" || token === "") {
+      throw new Error(`${config.label}: no ${field} in response`);
+    }
+    cached = token;
+    return token;
+  }
+
+  const get = async (): Promise<string> => {
+    if (cached !== null) {
+      return cached;
+    }
+    inFlight ??= exchangeOnce();
+    try {
+      return await inFlight;
+    } finally {
+      // Cleared on BOTH paths. Keeping a rejected promise here would turn one
+      // failed exchange into a permanently failing connector, which is the same
+      // trap as caching the failure.
+      inFlight = null;
+    }
+  };
+  return Object.assign(get, {
+    clear: (): void => {
+      cached = null;
+    },
+  });
+}

package/shared/atlassian-json-fetch.ts

@@ -1,3 +1,4 @@
+import { fetchJsonText } from "./fetch-json-text.ts";
 import { encodeBasicAuthHeader } from "./mcp-tool-kit.ts";
 import { stripTrailingSlashes } from "./strip-trailing-slashes.ts";
 
@@ -23,20 +24,9 @@ export async function fetchAtlassianBasicAuthJsonText(
   token: string,
   init?: RequestInit,
 ): Promise<{ ok: boolean; status: number; text: string }> {
-  const headers: Record<string, string> = {
-    Accept: "application/json",
-    Authorization: encodeBasicAuthHeader(email, token),
-  };
-  if (init?.body !== undefined) {
-    headers["Content-Type"] = "application/json";
-  }
-  const res = await fetch(url, {
-    ...init,
-    headers: {
-      ...headers,
-      ...(init?.headers as Record<string, string> | undefined),
-    },
-  });
-  const text = await res.text();
-  return { ok: res.ok, status: res.status, text };
+  return fetchJsonText(
+    url,
+    { Accept: "application/json", Authorization: encodeBasicAuthHeader(email, token) },
+    init,
+  );
 }

package/shared/audit-chain.ts

@@ -35,12 +35,6 @@ type ChainedLine = {
 /** First link's predecessor. A fixed, all-zero digest, mirroring the gateway's audit chain. */
 export const GENESIS_HASH = "0".repeat(64);
 
-/**
- * Canonical JSON with sorted keys.
- *
- * Two structurally identical entries must hash identically regardless of insertion order —
- * otherwise re-serialising during verification could break a chain that was never tampered with.
- */
 /**
  * Key order for `canonicalJson`. Plain code-unit comparison, NOT `localeCompare`: the order has to
  * be the same on every machine and locale, or a chain written on one host fails to verify on
@@ -52,11 +46,24 @@ function compareKeys(a: string, b: string): number {
   return 0;
 }
 
+/**
+ * Canonical JSON with sorted keys.
+ *
+ * Two structurally identical entries must hash identically regardless of insertion order —
+ * otherwise re-serialising during verification could break a chain that was never tampered with.
+ *
+ * For the same reason a key whose value is `undefined` is left out, as `JSON.stringify` leaves it
+ * out of the line that is actually written. Hashing it as `null` instead hashed something the log
+ * never contained, so verification — which can only re-hash what it reads back — reported the
+ * entry as tampered on its very first read. `kubernetes`' pod delete recorded exactly such a
+ * pre-state whenever the namespace was left to its default.
+ */
 function canonicalJson(value: unknown): string {
   if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
   if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
   const rec = value as Record<string, unknown>;
   const body = Object.keys(rec)
+    .filter((k) => rec[k] !== undefined)
     .sort(compareKeys)
     .map((k) => `${JSON.stringify(k)}:${canonicalJson(rec[k])}`)
     .join(",");