@nimbus-dev/connectors 0.2.1 → 0.2.3

package/connectors/slack/src/tools.ts

@@ -0,0 +1,376 @@
+import { z } from "zod";
+import type { ConsentServer } from "../../../shared/consent-kit.ts";
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+  type McpListResult,
+  putOptionalBoolean,
+  putOptionalNonEmptyString,
+  requireProcessEnv,
+} from "../../../shared/mcp-tool-kit.ts";
+import { asRecord } from "../../../shared/search-filter.ts";
+
+type SlackApiRecord = Record<string, unknown>;
+
+async function slackApi(
+  token: string,
+  method: string,
+  body: Record<string, unknown>,
+): Promise<{ ok: boolean; json: SlackApiRecord; text: string }> {
+  const res = await fetch(`https://slack.com/api/${method}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json; charset=utf-8",
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text) as unknown;
+  } catch {
+    return { ok: false, json: {}, text };
+  }
+  const json: SlackApiRecord = asRecord(parsed) ?? {};
+  const okField = json["ok"];
+  return { ok: okField === true && res.ok, json, text };
+}
+
+async function slackInvokeJsonWithToken(
+  token: string,
+  method: string,
+  body: Record<string, unknown>,
+  errorLabel: string,
+): Promise<McpListResult> {
+  const res = await slackApi(token, method, body);
+  if (!res.ok) {
+    throw new Error(`${errorLabel}: ${res.text.slice(0, 400)}`);
+  }
+  return jsonResult(res.json);
+}
+
+async function slackInvokeJson(
+  method: string,
+  body: Record<string, unknown>,
+  errorLabel: string,
+): Promise<McpListResult> {
+  return slackInvokeJsonWithToken(
+    requireProcessEnv("SLACK_USER_ACCESS_TOKEN"),
+    method,
+    body,
+    errorLabel,
+  );
+}
+
+const slackConversationsHistorySchema = z.object({
+  channel: z.string().min(1),
+  limit: z.number().int().min(1).max(200).optional(),
+  cursor: z.string().optional(),
+  oldest: z.string().optional(),
+  inclusive: z.boolean().optional(),
+});
+
+type SlackConversationsHistoryParsed = z.infer<typeof slackConversationsHistorySchema>;
+
+function buildConversationsHistoryBody(
+  parsed: SlackConversationsHistoryParsed,
+): Record<string, unknown> {
+  const body: Record<string, unknown> = {
+    channel: parsed.channel,
+    limit: parsed.limit ?? 50,
+  };
+  putOptionalNonEmptyString(body, "cursor", parsed.cursor);
+  putOptionalNonEmptyString(body, "oldest", parsed.oldest);
+  putOptionalBoolean(body, "inclusive", parsed.inclusive);
+  return body;
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const SLACK_TOOL_NAMES = [
+  "slack_channel_list",
+  "slack_channel_history",
+  "slack_thread_replies",
+  "slack_dm_list",
+  "slack_dm_history",
+  "slack_user_list",
+  "slack_user_get",
+  "slack_search",
+  "slack_message_post",
+  "slack_message_post_dm",
+  "slack_user_info",
+  "slack_chat_post",
+  "slack_socket_open",
+] as const;
+
+export function registerSlackTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const registerSimpleTool = createRegisterSimpleTool(server);
+
+  const reg = createZodToolRegistrar(registerSimpleTool);
+
+  /**
+   * Every MUTATING slack tool goes through here. Outside the gateway this adds the
+   * consent gate, the write-scope allow-list, the mutation budget and the audit record; inside
+   * the gateway it is a pass-through, because executor.ts (I2) is the gate there.
+   */
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "slack",
+    scopeEnv: "NIMBUS_MCP_SLACK_WRITE_SCOPE",
+    // `user` scopes a direct message by the recipient's user id, which is all a DM has before
+    // `conversations.open` creates its channel.
+    scopeKinds: ["channel", "user"],
+  });
+
+  const slackChannelListSchema = z.object({
+    types: z.string().optional(),
+    limit: z.number().int().min(1).max(200).optional(),
+    cursor: z.string().optional(),
+  });
+
+  reg(
+    "slack_channel_list",
+    "List channels the user is a member of (public, private, mpim, im).",
+    slackChannelListSchema,
+    async (parsed) => {
+      const body: Record<string, unknown> = {
+        types: parsed.types ?? "public_channel,private_channel,mpim,im",
+        limit: parsed.limit ?? 200,
+        exclude_archived: true,
+      };
+      putOptionalNonEmptyString(body, "cursor", parsed.cursor);
+      return slackInvokeJson("conversations.list", body, "Slack conversations.list");
+    },
+  );
+
+  reg(
+    "slack_channel_history",
+    "Fetch message history for a channel, DM, or mpim.",
+    slackConversationsHistorySchema,
+    async (parsed) =>
+      slackInvokeJson(
+        "conversations.history",
+        buildConversationsHistoryBody(parsed),
+        "Slack conversations.history",
+      ),
+  );
+
+  const slackThreadRepliesSchema = z.object({
+    channel: z.string().min(1),
+    ts: z.string().min(1),
+    limit: z.number().int().min(1).max(200).optional(),
+    cursor: z.string().optional(),
+  });
+
+  reg(
+    "slack_thread_replies",
+    "Fetch replies in a thread (channel + thread parent ts).",
+    slackThreadRepliesSchema,
+    async (parsed) => {
+      const body: Record<string, unknown> = {
+        channel: parsed.channel,
+        ts: parsed.ts,
+        limit: parsed.limit ?? 50,
+      };
+      putOptionalNonEmptyString(body, "cursor", parsed.cursor);
+      return slackInvokeJson("conversations.replies", body, "Slack conversations.replies");
+    },
+  );
+
+  const slackDmListSchema = z.object({
+    limit: z.number().int().min(1).max(200).optional(),
+    cursor: z.string().optional(),
+  });
+
+  reg(
+    "slack_dm_list",
+    "List direct message conversations (im + mpim).",
+    slackDmListSchema,
+    async (parsed) => {
+      const body: Record<string, unknown> = {
+        types: "im,mpim",
+        limit: parsed.limit ?? 200,
+        exclude_archived: true,
+      };
+      putOptionalNonEmptyString(body, "cursor", parsed.cursor);
+      return slackInvokeJson("conversations.list", body, "Slack dm list");
+    },
+  );
+
+  reg(
+    "slack_dm_history",
+    "Fetch DM / mpim history (same as channel history; convenience alias).",
+    slackConversationsHistorySchema,
+    async (parsed) =>
+      slackInvokeJson(
+        "conversations.history",
+        buildConversationsHistoryBody(parsed),
+        "Slack dm history",
+      ),
+  );
+
+  const slackUserListSchema = z.object({
+    limit: z.number().int().min(1).max(200).optional(),
+    cursor: z.string().optional(),
+  });
+
+  reg(
+    "slack_user_list",
+    "List users in the workspace (paginated).",
+    slackUserListSchema,
+    async (parsed) => {
+      const body: Record<string, unknown> = { limit: parsed.limit ?? 100 };
+      putOptionalNonEmptyString(body, "cursor", parsed.cursor);
+      return slackInvokeJson("users.list", body, "Slack users.list");
+    },
+  );
+
+  const slackUserGetSchema = z.object({ user: z.string().min(1) });
+
+  reg("slack_user_get", "Get a single user profile by ID.", slackUserGetSchema, async (parsed) =>
+    slackInvokeJson("users.info", { user: parsed.user }, "Slack users.info"),
+  );
+
+  const slackSearchSchema = z.object({
+    query: z.string().min(1),
+    count: z.number().int().min(1).max(100).optional(),
+    page: z.number().int().min(1).optional(),
+    sort: z.enum(["timestamp", "score"]).optional(),
+    sort_dir: z.enum(["asc", "desc"]).optional(),
+  });
+
+  reg("slack_search", "Search messages (workspace search).", slackSearchSchema, async (parsed) => {
+    const body: Record<string, unknown> = {
+      query: parsed.query,
+      count: parsed.count ?? 20,
+      page: parsed.page ?? 1,
+    };
+    if (parsed.sort !== undefined) {
+      body["sort"] = parsed.sort;
+    }
+    if (parsed.sort_dir !== undefined) {
+      body["sort_dir"] = parsed.sort_dir;
+    }
+    return slackInvokeJson("search.messages", body, "Slack search.messages");
+  });
+
+  const slackMessagePostSchema = z.object({
+    channel: z.string().min(1),
+    text: z.string().min(1),
+    thread_ts: z.string().optional(),
+  });
+
+  registerWriteTool(
+    "slack_message_post",
+    {
+      mutates: "slack.message.post",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "channel", value: p.channel }),
+    },
+    "Post a message to a channel.",
+    slackMessagePostSchema,
+    async (parsed) => {
+      const body: Record<string, unknown> = {
+        channel: parsed.channel,
+        text: parsed.text,
+      };
+      putOptionalNonEmptyString(body, "thread_ts", parsed.thread_ts);
+      return slackInvokeJson("chat.postMessage", body, "Slack chat.postMessage");
+    },
+  );
+
+  const slackMessagePostDmSchema = z.object({
+    user_ids: z.string().min(1),
+    text: z.string().min(1),
+  });
+
+  // A WRITE: it sends a message. It was registered as a read, which in standalone mode offered it
+  // to every client with no consent prompt, scope check, budget or audit record.
+  registerWriteTool(
+    "slack_message_post_dm",
+    {
+      mutates: "slack.message.post",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "user", value: p.user_ids }),
+    },
+    "Open or find a DM with user id(s) and send a message.",
+    slackMessagePostDmSchema,
+    async (parsed) => {
+      const token = requireProcessEnv("SLACK_USER_ACCESS_TOKEN");
+      const open = await slackApi(token, "conversations.open", {
+        users: parsed.user_ids,
+        return_im: true,
+      });
+      if (!open.ok) {
+        throw new Error(`Slack conversations.open: ${open.text.slice(0, 400)}`);
+      }
+      const chRec = asRecord(open.json["channel"]);
+      const channelId = chRec !== undefined && typeof chRec["id"] === "string" ? chRec["id"] : "";
+      if (channelId === "") {
+        throw new Error("Slack conversations.open: missing channel id");
+      }
+      const post = await slackApi(token, "chat.postMessage", {
+        channel: channelId,
+        text: parsed.text,
+      });
+      if (!post.ok) {
+        throw new Error(`Slack chat.postMessage (dm): ${post.text.slice(0, 400)}`);
+      }
+      return jsonResult({ open: open.json, post: post.json });
+    },
+  );
+
+  // --- ChatOps operational tools (Slice 5) -------------------------------------------------------
+  // These use the bot/app tokens (xoxb-/xapp-), distinct from the user token the read tools use.
+  // Only `chatops/reply-dispatcher.ts` + `chatops/transport/` reference `slack_chat_post` (static D17).
+
+  const slackUserInfoSchema = z.object({ user: z.string().min(1) });
+  reg(
+    "slack_user_info",
+    "Fetch a Slack user's profile (incl. email) by user id (ChatOps identity mapping; bot token).",
+    slackUserInfoSchema,
+    async (parsed) =>
+      slackInvokeJsonWithToken(
+        requireProcessEnv("SLACK_BOT_TOKEN"),
+        "users.info",
+        { user: parsed.user },
+        "Slack users.info",
+      ),
+  );
+
+  const slackChatPostSchema = z.object({ channel: z.string().min(1), text: z.string().min(1) });
+  registerWriteTool(
+    "slack_chat_post",
+    {
+      mutates: "slack.chat.post",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "channel", value: p.channel }),
+    },
+    "Post an operational bot message to a channel (ChatOps reply surface; bot token).",
+    slackChatPostSchema,
+    async (parsed) =>
+      slackInvokeJsonWithToken(
+        requireProcessEnv("SLACK_BOT_TOKEN"),
+        "chat.postMessage",
+        { channel: parsed.channel, text: parsed.text },
+        "Slack chat.postMessage",
+      ),
+  );
+
+  const slackSocketOpenSchema = z.object({});
+  reg(
+    "slack_socket_open",
+    "Open a Slack Socket Mode connection and return the short-lived wss:// URL (app-level token).",
+    slackSocketOpenSchema,
+    async () =>
+      slackInvokeJsonWithToken(
+        requireProcessEnv("SLACK_APP_TOKEN"), // xapp-… (Socket Mode app-level token)
+        "apps.connections.open",
+        {},
+        "Slack apps.connections.open",
+      ),
+  );
+}

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

@@ -1,26 +1,11 @@
 import {
-  asRecord,
   makeQueryFilter,
+  recordFieldsFromKeys,
   type SearchMatchOptions,
 } from "../../../shared/search-filter.ts";
 
 export type SnowflakeSearchMatchOptions = SearchMatchOptions;
 
-function stringAt(row: Record<string, unknown>, key: string): string {
-  const v = row[key];
-  return typeof v === "string" ? v : "";
-}
-
-function fieldsOf(item: unknown): readonly string[] | null {
-  const row = asRecord(item);
-  if (row === undefined) {
-    return null;
-  }
-  return [
-    stringAt(row, "table_name"),
-    stringAt(row, "schema_name"),
-    stringAt(row, "database_name"),
-  ];
-}
-
-export const filterSnowflakeTables = makeQueryFilter(fieldsOf);
+export const filterSnowflakeTables = makeQueryFilter(
+  recordFieldsFromKeys(["table_name", "schema_name", "database_name"]),
+);

package/connectors/snowflake/src/server.ts

@@ -1,28 +1,19 @@
 import { z } from "zod";
 import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { cursorListInputSchema } from "../../../shared/cursor-list-tool.ts";
+import { requiredEnv } from "../../../shared/env-json-api.ts";
 import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
 import { fetchWithTimeout, mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
 import {
   runReadOnlyMcpConnector,
   type ZodToolRegistrar,
 } from "../../../shared/run-read-only-mcp-connector.ts";
+import { asRecord } from "../../../shared/search-filter.ts";
 import { filterSnowflakeTables } from "./search-filter.ts";
 
-function snowflakeAccount(): string {
-  const v = process.env["SNOWFLAKE_ACCOUNT"]?.trim();
-  if (v === undefined || v === "") {
-    throw new Error("SNOWFLAKE_ACCOUNT is not set");
-  }
-  return v;
-}
-
 function authHeader(): Record<string, string> {
-  const t = process.env["SNOWFLAKE_TOKEN"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("SNOWFLAKE_TOKEN is not set");
-  }
   return {
-    Authorization: `Bearer ${t}`,
+    Authorization: `Bearer ${requiredEnv("SNOWFLAKE_TOKEN")}`,
     "Content-Type": "application/json",
     Accept: "application/json",
   };
@@ -34,7 +25,7 @@ function authHeader(): Record<string, string> {
  * the read-only `fetchTables` path and the HITL-gated write tools so auth/transport stays in one place.
  */
 async function executeStatement(statement: string): Promise<unknown> {
-  const url = `https://${snowflakeAccount()}.snowflakecomputing.com/api/v2/statements`;
+  const url = `https://${requiredEnv("SNOWFLAKE_ACCOUNT")}.snowflakecomputing.com/api/v2/statements`;
   const res = await fetchWithTimeout(url, {
     method: "POST",
     headers: authHeader(),
@@ -68,13 +59,6 @@ const TABLES_SQL =
   "SELECT table_catalog AS database_name, table_schema AS schema_name, table_name, " +
   "row_count, last_altered FROM information_schema.tables WHERE table_schema <> 'INFORMATION_SCHEMA'";
 
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    return undefined;
-  }
-  return value as Record<string, unknown>;
-}
-
 function rowsFromStatementsResponse(parsed: unknown): Record<string, unknown>[] {
   const root = asRecord(parsed);
   const meta = asRecord(root?.["resultSetMetaData"]);
@@ -141,10 +125,7 @@ export function registerSnowflakeTools(reg: ZodToolRegistrar, server: unknown):
   reg(
     "snowflake_list",
     "List Snowflake tables across all databases and schemas. Paginated: `cursor` (opaque offset) + `limit` (default 200, max 500) → `{ items, nextCursor }`.",
-    z.object({
-      cursor: z.string().nullable().optional(),
-      limit: z.number().int().min(1).max(500).optional(),
-    }),
+    cursorListInputSchema(),
     async (p) => {
       const limit = p.limit ?? 200;
       const offset =

package/connectors/snyk/src/server.ts

@@ -1,144 +1,6 @@
-import { z } from "zod";
-import { matchesResult } 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 { filterSnykAggregatedIssues } from "./search-filter.ts";
-
-const SNYK_API = "https://api.snyk.io";
-
-function authHeader(): Record<string, string> {
-  const t = process.env["SNYK_TOKEN"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("SNYK_TOKEN is not set");
-  }
-  return { Authorization: `token ${t}`, Accept: "application/json" };
-}
-
-async function snykGet(path: string): Promise<unknown> {
-  const res = await fetch(`${SNYK_API}${path}`, { headers: authHeader() });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`Snyk ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text) as unknown;
-}
-
-async function snykPost(path: string, body: unknown): Promise<unknown> {
-  const res = await fetch(`${SNYK_API}${path}`, {
-    method: "POST",
-    headers: { ...authHeader(), "Content-Type": "application/json" },
-    body: JSON.stringify(body),
-  });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`Snyk ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  if (text.trim() === "") {
-    return {};
-  }
-  return JSON.parse(text) as unknown;
-}
+import { registerSnykTools } from "./tools.ts";
 
 await runReadOnlyMcpConnector("nimbus-snyk", (reg) => {
-  reg(
-    "snyk_list",
-    "List Snyk projects for an org, or aggregated issues for a project. When projectId is omitted, returns the org's project list. Severities default to all four (critical/high/medium/low).",
-    z.object({
-      orgId: z.string().min(1),
-      projectId: z.string().min(1).optional(),
-      severities: z
-        .array(z.enum(["critical", "high", "medium", "low"]))
-        .min(1)
-        .optional(),
-      limit: z.number().int().min(1).max(1000).optional(),
-    }),
-    async (p) => {
-      if (p.projectId === undefined) {
-        return jsonResult(await snykGet(`/v1/org/${encodeURIComponent(p.orgId)}/projects`));
-      }
-      const severities = p.severities ?? ["critical", "high", "medium", "low"];
-      const body = {
-        filters: {
-          severities,
-          types: ["vuln", "license"],
-          ignored: false,
-          patched: false,
-        },
-      };
-      const path = `/v1/org/${encodeURIComponent(p.orgId)}/project/${encodeURIComponent(p.projectId)}/aggregated-issues`;
-      const data = await snykPost(path, body);
-      if (p.limit !== undefined && data !== null && typeof data === "object") {
-        const issues = (data as { issues?: unknown[] }).issues;
-        if (Array.isArray(issues) && issues.length > p.limit) {
-          return jsonResult({
-            ...(data as Record<string, unknown>),
-            issues: issues.slice(0, p.limit),
-          });
-        }
-      }
-      return jsonResult(data);
-    },
-  );
-
-  reg(
-    "snyk_get",
-    "Fetch one Snyk issue by id from an org + project. Returns the aggregated-issue envelope for the matching `issue.id`; throws when no match is found.",
-    z.object({
-      orgId: z.string().min(1),
-      projectId: z.string().min(1),
-      issueId: z.string().min(1),
-    }),
-    async (p) => {
-      const body = {
-        filters: {
-          severities: ["critical", "high", "medium", "low"],
-          types: ["vuln", "license"],
-          ignored: false,
-          patched: false,
-        },
-      };
-      const path = `/v1/org/${encodeURIComponent(p.orgId)}/project/${encodeURIComponent(p.projectId)}/aggregated-issues`;
-      const root = await snykPost(path, body);
-      const issues = (root as { issues?: unknown[] } | null)?.issues;
-      if (!Array.isArray(issues)) {
-        throw new TypeError(`Snyk: project ${p.projectId} returned no issues envelope`);
-      }
-      const match = issues.find((it) => {
-        if (it === null || typeof it !== "object") {
-          return false;
-        }
-        const id = (it as { id?: unknown }).id;
-        return typeof id === "string" && id === p.issueId;
-      });
-      if (match === undefined) {
-        throw new Error(`Snyk: issue ${p.issueId} not found in project ${p.projectId}`);
-      }
-      return jsonResult(match);
-    },
-  );
-
-  reg(
-    "snyk_search",
-    "Substring search across a project's aggregated issues. Matches the query against `issueData.title`, `issueData.cve`, and `pkgName` (case-insensitive). Returns a `{ matches: [...] }` envelope.",
-    z.object({
-      orgId: z.string().min(1),
-      projectId: z.string().min(1),
-      query: z.string().min(1),
-      limit: z.number().int().min(1).max(200).optional(),
-    }),
-    async (p) => {
-      const body = {
-        filters: {
-          severities: ["critical", "high", "medium", "low"],
-          types: ["vuln", "license"],
-          ignored: false,
-          patched: false,
-        },
-      };
-      const path = `/v1/org/${encodeURIComponent(p.orgId)}/project/${encodeURIComponent(p.projectId)}/aggregated-issues`;
-      const root = await snykPost(path, body);
-      const issues = (root as { issues?: unknown[] } | null)?.issues;
-      return matchesResult(issues, filterSnykAggregatedIssues, p);
-    },
-  );
+  registerSnykTools(reg);
 });