@nimbus-dev/connectors 0.1.0

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

@@ -0,0 +1,42 @@
+import { stringField } from "../../../shared/search-filter.ts";
+
+export interface ZoomSearchOptions {
+  readonly query: string;
+  readonly limit?: number;
+}
+
+function asRecord(v: unknown): Record<string, unknown> | undefined {
+  return v !== null && typeof v === "object" && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : undefined;
+}
+
+export function filterZoomMeetings(
+  meetings: readonly unknown[],
+  options: ZoomSearchOptions,
+): unknown[] {
+  const q = options.query.trim().toLowerCase();
+  if (q === "") {
+    return [];
+  }
+  const limit = options.limit ?? 50;
+  if (limit <= 0) {
+    return [];
+  }
+  const matches: unknown[] = [];
+  for (const m of meetings) {
+    const row = asRecord(m);
+    if (row === undefined) {
+      continue;
+    }
+    const haystack =
+      `${stringField(row, "topic")} ${stringField(row, "agenda")} ${stringField(row, "host_id")}`.toLowerCase();
+    if (haystack.includes(q)) {
+      matches.push(m);
+      if (matches.length >= limit) {
+        break;
+      }
+    }
+  }
+  return matches;
+}

package/connectors/zoom/src/server.ts

@@ -0,0 +1,98 @@
+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;
+}
+
+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`),
+      );
+    },
+  );
+});

package/connectors/zotero/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.zotero",
+  "displayName": "Zotero",
+  "version": "0.1.0",
+  "description": "Zotero connector (read-only). Surfaces the user's bibliographic references from a Zotero library (`users/<id>` or `groups/<id>`) as `zotero:reference` items in the local index — the title, the formatted creator/author list, the publication date, the item type (journalArticle / book / conferencePaper / …), tags, collections, DOI, source URL, and a truncated abstract. Useful for answering research questions (\"what did I save about retrieval-augmented generation?\", \"find my reference with DOI 10.1145/…\") without leaving Nimbus. Two-identifier auth (mirrors the Stack Overflow shape): `Zotero-API-Key: <key>` header (the secret) plus a non-secret `zotero.library` spec selecting the library path. The SaaS host (api.zotero.org) is fixed; Zotero-API-Version is pinned to 3. The Zotero Web API v3 `/<library>/items` endpoint paginates by `start`/`limit` (limit max 100, `sort=dateModified&direction=desc`); the connector walks a single forward pass per cycle, page-capped. Attachments and standalone notes are skipped — v1 indexes top-level bibliographic references only.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.zotero.org"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,81 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type ZoteroSearchMatchOptions = SearchMatchOptions;
+
+function nonEmptyString(v: unknown): string | null {
+  return typeof v === "string" && v !== "" ? v : null;
+}
+
+function creatorName(c: unknown): string | null {
+  if (c === null || typeof c !== "object") {
+    return null;
+  }
+  const row = c as Record<string, unknown>;
+  const name = nonEmptyString(row["name"]);
+  if (name !== null) {
+    return name;
+  }
+  const parts = [nonEmptyString(row["firstName"]), nonEmptyString(row["lastName"])].filter(
+    (p): p is string => p !== null,
+  );
+  return parts.length > 0 ? parts.join(" ") : null;
+}
+
+function creatorNames(data: Record<string, unknown>): string {
+  const creators = data["creators"];
+  if (!Array.isArray(creators)) {
+    return "";
+  }
+  const names: string[] = [];
+  for (const c of creators) {
+    const name = creatorName(c);
+    if (name !== null) {
+      names.push(name);
+    }
+  }
+  return names.join(" ");
+}
+
+function tagNames(data: Record<string, unknown>): string {
+  const tags = data["tags"];
+  if (!Array.isArray(tags)) {
+    return "";
+  }
+  const names: string[] = [];
+  for (const t of tags) {
+    if (t !== null && typeof t === "object") {
+      const tag = (t as Record<string, unknown>)["tag"];
+      if (typeof tag === "string") {
+        names.push(tag);
+      }
+    }
+  }
+  return names.join(" ");
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  const data = asObjectish(row["data"]);
+  if (data === undefined) {
+    return null;
+  }
+  return [
+    stringField(data, "title"),
+    stringField(data, "itemType"),
+    stringField(data, "abstractNote"),
+    stringField(data, "DOI"),
+    stringField(data, "publicationTitle"),
+    creatorNames(data),
+    tagNames(data),
+  ];
+}
+
+export const filterZoteroItems = makeQueryFilter(fieldsOf);

package/connectors/zotero/src/server.ts

@@ -0,0 +1,82 @@
+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`;
+}
+
+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);
+    },
+  );
+});

package/package.json

@@ -0,0 +1,152 @@
+{
+  "name": "@nimbus-dev/connectors",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "description": "Nimbus first-party MCP connectors, runnable standalone by any MCP client.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nimbus-agent/nimbus-mcp-servers.git"
+  },
+  "bin": {
+    "nimbus-connector": "./standalone/src/bin.ts"
+  },
+  "files": [
+    "connectors/*/src/**",
+    "connectors/*/nimbus.extension.json",
+    "shared/**",
+    "standalone/**",
+    "NOTICE",
+    "README.md",
+    "!standalone/package.json",
+    "!**/*.test.ts"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@nimbus-dev/sdk": "^1.20.0",
+    "zod": "^4.4.2"
+  },
+  "exports": {
+    ".": "./standalone/src/bin.ts",
+    "./airflow": "./connectors/airflow/src/server.ts",
+    "./apple": "./connectors/apple/src/server.ts",
+    "./argocd": "./connectors/argocd/src/server.ts",
+    "./athena": "./connectors/athena/src/server.ts",
+    "./aws": "./connectors/aws/src/server.ts",
+    "./azure": "./connectors/azure/src/server.ts",
+    "./bigeye": "./connectors/bigeye/src/server.ts",
+    "./bigquery": "./connectors/bigquery/src/server.ts",
+    "./bitbucket": "./connectors/bitbucket/src/server.ts",
+    "./bitrise": "./connectors/bitrise/src/server.ts",
+    "./canva": "./connectors/canva/src/server.ts",
+    "./circleci": "./connectors/circleci/src/server.ts",
+    "./cloud-logging": "./connectors/cloud-logging/src/server.ts",
+    "./cloudwatch": "./connectors/cloudwatch/src/server.ts",
+    "./codemagic": "./connectors/codemagic/src/server.ts",
+    "./confluence": "./connectors/confluence/src/server.ts",
+    "./dagster": "./connectors/dagster/src/server.ts",
+    "./databricks": "./connectors/databricks/src/server.ts",
+    "./datadog": "./connectors/datadog/src/server.ts",
+    "./dataprofile": "./connectors/dataprofile/src/server.ts",
+    "./dbt": "./connectors/dbt/src/server.ts",
+    "./dependencytrack": "./connectors/dependencytrack/src/server.ts",
+    "./discord": "./connectors/discord/src/server.ts",
+    "./elasticsearch": "./connectors/elasticsearch/src/server.ts",
+    "./fastmail": "./connectors/fastmail/src/server.ts",
+    "./figma": "./connectors/figma/src/server.ts",
+    "./firebase": "./connectors/firebase/src/server.ts",
+    "./flagsmith": "./connectors/flagsmith/src/server.ts",
+    "./flux": "./connectors/flux/src/server.ts",
+    "./gcp": "./connectors/gcp/src/server.ts",
+    "./github": "./connectors/github/src/server.ts",
+    "./github-actions": "./connectors/github-actions/src/server.ts",
+    "./gitlab": "./connectors/gitlab/src/server.ts",
+    "./gmail": "./connectors/gmail/src/server.ts",
+    "./google-drive": "./connectors/google-drive/src/server.ts",
+    "./google-meet": "./connectors/google-meet/src/server.ts",
+    "./google-photos": "./connectors/google-photos/src/server.ts",
+    "./grafana": "./connectors/grafana/src/server.ts",
+    "./great-expectations": "./connectors/great-expectations/src/server.ts",
+    "./greenhouse": "./connectors/greenhouse/src/server.ts",
+    "./hubspot": "./connectors/hubspot/src/server.ts",
+    "./iac": "./connectors/iac/src/server.ts",
+    "./imap": "./connectors/imap/src/server.ts",
+    "./intercom": "./connectors/intercom/src/server.ts",
+    "./jenkins": "./connectors/jenkins/src/server.ts",
+    "./jira": "./connectors/jira/src/server.ts",
+    "./kubernetes": "./connectors/kubernetes/src/server.ts",
+    "./launchdarkly": "./connectors/launchdarkly/src/server.ts",
+    "./lever": "./connectors/lever/src/server.ts",
+    "./linear": "./connectors/linear/src/server.ts",
+    "./localdb": "./connectors/localdb/src/server.ts",
+    "./looker": "./connectors/looker/src/server.ts",
+    "./mendeley": "./connectors/mendeley/src/server.ts",
+    "./mercury": "./connectors/mercury/src/server.ts",
+    "./metabase": "./connectors/metabase/src/server.ts",
+    "./miro": "./connectors/miro/src/server.ts",
+    "./mlflow": "./connectors/mlflow/src/server.ts",
+    "./monte-carlo": "./connectors/monte-carlo/src/server.ts",
+    "./netlify": "./connectors/netlify/src/server.ts",
+    "./newrelic": "./connectors/newrelic/src/server.ts",
+    "./notion": "./connectors/notion/src/server.ts",
+    "./obsidian": "./connectors/obsidian/src/server.ts",
+    "./onedrive": "./connectors/onedrive/src/server.ts",
+    "./outlook": "./connectors/outlook/src/server.ts",
+    "./pagerduty": "./connectors/pagerduty/src/server.ts",
+    "./pipedrive": "./connectors/pipedrive/src/server.ts",
+    "./powerbi": "./connectors/powerbi/src/server.ts",
+    "./prefect": "./connectors/prefect/src/server.ts",
+    "./protonmail": "./connectors/protonmail/src/server.ts",
+    "./raindrop": "./connectors/raindrop/src/server.ts",
+    "./ramp": "./connectors/ramp/src/server.ts",
+    "./readwise": "./connectors/readwise/src/server.ts",
+    "./sagemaker": "./connectors/sagemaker/src/server.ts",
+    "./salesforce": "./connectors/salesforce/src/server.ts",
+    "./semgrep": "./connectors/semgrep/src/server.ts",
+    "./sentry": "./connectors/sentry/src/server.ts",
+    "./slack": "./connectors/slack/src/server.ts",
+    "./snowflake": "./connectors/snowflake/src/server.ts",
+    "./snyk": "./connectors/snyk/src/server.ts",
+    "./sonarqube": "./connectors/sonarqube/src/server.ts",
+    "./stackoverflow": "./connectors/stackoverflow/src/server.ts",
+    "./storybook": "./connectors/storybook/src/server.ts",
+    "./stripe": "./connectors/stripe/src/server.ts",
+    "./superset": "./connectors/superset/src/server.ts",
+    "./tableau": "./connectors/tableau/src/server.ts",
+    "./teams": "./connectors/teams/src/server.ts",
+    "./testflight": "./connectors/testflight/src/server.ts",
+    "./vercel": "./connectors/vercel/src/server.ts",
+    "./vertex-ai": "./connectors/vertex-ai/src/server.ts",
+    "./wiz": "./connectors/wiz/src/server.ts",
+    "./workday": "./connectors/workday/src/server.ts",
+    "./zendesk": "./connectors/zendesk/src/server.ts",
+    "./zoom": "./connectors/zoom/src/server.ts",
+    "./zotero": "./connectors/zotero/src/server.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "lint": "biome check --error-on-warnings .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc -p tsconfig.json",
+    "audit:connector-consent": "bun scripts/check-connector-consent.ts",
+    "check": "bun run lint && bun run typecheck && bun run audit:connector-consent && bun run test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.10",
+    "@types/bun": "^1.4.0",
+    "@types/nodemailer": "^7.0.4",
+    "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"
+  }
+}

package/shared/atlassian-json-fetch.ts

@@ -0,0 +1,42 @@
+import { encodeBasicAuthHeader } from "./mcp-tool-kit.ts";
+import { stripTrailingSlashes } from "./strip-trailing-slashes.ts";
+
+export function normalizeRequiredSiteBaseUrl(raw: string, emptyMessage: string): string {
+  const t = stripTrailingSlashes(raw);
+  if (t === "") {
+    throw new Error(emptyMessage);
+  }
+  return t.startsWith("http") ? t : `https://${t}`;
+}
+
+export function requireTrimmedEnv(name: string, notSetMessage: string): string {
+  const v = process.env[name];
+  if (v === undefined || v.trim() === "") {
+    throw new Error(notSetMessage);
+  }
+  return v.trim();
+}
+
+export async function fetchAtlassianBasicAuthJsonText(
+  url: string,
+  email: string,
+  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 };
+}

package/shared/audit-chain.ts

@@ -0,0 +1,133 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { appendFile, readFile } from "node:fs/promises";
+
+/**
+ * What happened to one gated action.
+ *
+ * `refused` is a server-side denial (out of scope, budget exhausted, or no elicitation-capable
+ * client); `declined` is a human saying no. They are kept distinct because only one of them means a
+ * person was actually asked.
+ */
+export type AuditOutcome =
+  | "requested"
+  | "accepted"
+  | "declined"
+  | "refused"
+  | "executed"
+  | "failed";
+
+export type AuditEntry = {
+  readonly ts: string;
+  readonly connector: string;
+  readonly tool: string;
+  readonly outcome: AuditOutcome;
+  /** Free-form per-outcome detail: resolved params, refusal reason, captured pre-state. */
+  readonly detail: Record<string, unknown>;
+};
+
+type ChainedLine = {
+  readonly seq: number;
+  readonly prev: string;
+  readonly hash: string;
+  readonly entry: AuditEntry;
+};
+
+/** 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
+ * another.
+ */
+function compareKeys(a: string, b: string): number {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+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)
+    .sort(compareKeys)
+    .map((k) => `${JSON.stringify(k)}:${canonicalJson(rec[k])}`)
+    .join(",");
+  return `{${body}}`;
+}
+
+/**
+ * Hash over the predecessor plus the entry's canonical JSON.
+ *
+ * SHA-256 via `node:crypto`, deliberately NOT the gateway's BLAKE3: `@noble/hashes` is not in
+ * `ALLOWED_CONNECTOR_DEPS`, and the standalone artifact must run under Node. Same construction,
+ * different primitive.
+ */
+function linkHash(prev: string, entry: AuditEntry): string {
+  return createHash("sha256").update(prev).update(canonicalJson(entry)).digest("hex");
+}
+
+/** Constant-time digest comparison (I10). A length mismatch is a mismatch, checked first. */
+function hashEquals(a: string, b: string): boolean {
+  const ab = Buffer.from(a, "utf8");
+  const bb = Buffer.from(b, "utf8");
+  return ab.length === bb.length && timingSafeEqual(ab, bb);
+}
+
+async function readLines(path: string): Promise<string[]> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    return [];
+  }
+  const trimmed = text.trimEnd();
+  return trimmed === "" ? [] : trimmed.split("\n");
+}
+
+/** Append one entry, linked to the current tail. */
+export async function appendAuditEntry(path: string, entry: AuditEntry): Promise<void> {
+  const lines = await readLines(path);
+  const last = lines.at(-1);
+  const prev = last === undefined ? GENESIS_HASH : (JSON.parse(last) as ChainedLine).hash;
+  const line: ChainedLine = {
+    seq: lines.length + 1,
+    prev,
+    hash: linkHash(prev, entry),
+    entry,
+  };
+  await appendFile(path, `${JSON.stringify(line)}\n`, "utf8");
+}
+
+/**
+ * Walk the chain.
+ *
+ * Returns the 1-based line where the links first stop agreeing, which covers both a tampered entry
+ * and a deleted one — a deletion breaks the successor's `prev` link.
+ */
+export async function verifyAuditChain(
+  path: string,
+): Promise<{ ok: true; count: number } | { ok: false; brokenAtLine: number }> {
+  const lines = await readLines(path);
+  let prev = GENESIS_HASH;
+  for (const [i, raw] of lines.entries()) {
+    let line: ChainedLine;
+    try {
+      line = JSON.parse(raw) as ChainedLine;
+    } catch {
+      return { ok: false, brokenAtLine: i + 1 };
+    }
+    if (!hashEquals(line.prev, prev) || !hashEquals(line.hash, linkHash(prev, line.entry))) {
+      return { ok: false, brokenAtLine: i + 1 };
+    }
+    prev = line.hash;
+  }
+  return { ok: true, count: lines.length };
+}