@inkeep/agents-work-apps 0.47.5 → 0.48.0

package/dist/slack/services/nango.js

@@ -0,0 +1,476 @@
+import { env } from "../../env.js";
+import { getLogger } from "../../logger.js";
+import runDbClient_default from "../../db/runDbClient.js";
+import { findWorkAppSlackWorkspaceBySlackTeamId } from "@inkeep/agents-core";
+import { Nango } from "@nangohq/node";
+
+//#region src/slack/services/nango.ts
+/**
+* Nango Service for Slack OAuth Token Management
+*
+* ARCHITECTURE NOTE: PostgreSQL is the authoritative source of truth for:
+* - User linking data (work_app_slack_user_mappings table)
+* - Workspace metadata (work_app_slack_workspaces table)
+* - Channel agent configs (work_app_slack_channel_agent_configs table)
+*
+* Nango is used ONLY for:
+* - OAuth token storage and refresh (bot tokens for workspaces)
+* - OAuth flow management (createConnectSession)
+* - Workspace default agent config (stored in connection metadata)
+*
+* PERFORMANCE: Workspace lookups use PostgreSQL first (O(1)), with Nango
+* fallback only when needed for bot token retrieval.
+*
+* For user data, use the PostgreSQL data access layer:
+* @see packages/agents-core/src/data-access/runtime/workAppSlack.ts
+*/
+const MAX_WORKSPACE_CACHE_SIZE = 1e3;
+const workspaceConnectionCache = /* @__PURE__ */ new Map();
+const CACHE_TTL_MS = 6e4;
+const logger = getLogger("slack-nango");
+/**
+* Retry a function with exponential backoff for transient failures.
+* Retries on AbortError (timeout) and 5xx HTTP errors.
+*/
+async function retryWithBackoff(fn, maxAttempts = 3) {
+	for (let attempt = 1; attempt <= maxAttempts; attempt++) try {
+		return await fn();
+	} catch (error) {
+		const isTimeout = error.name === "AbortError";
+		const isServerError = typeof error.status === "number" && error.status >= 500;
+		if (!(isTimeout || isServerError) || attempt === maxAttempts) throw error;
+		const delay = Math.min(500 * 2 ** (attempt - 1), 2e3) + Math.random() * 100;
+		logger.warn({
+			attempt,
+			maxAttempts,
+			isTimeout,
+			delay: Math.round(delay)
+		}, "Retrying Nango API call after transient failure");
+		await new Promise((resolve) => setTimeout(resolve, delay));
+	}
+	throw new Error("Unreachable");
+}
+/**
+* Evict expired entries from workspace cache to bound memory.
+*/
+function evictWorkspaceCache() {
+	if (workspaceConnectionCache.size <= MAX_WORKSPACE_CACHE_SIZE) return;
+	const now = Date.now();
+	for (const [key, entry] of workspaceConnectionCache) if (entry.expiresAt <= now) workspaceConnectionCache.delete(key);
+	if (workspaceConnectionCache.size > MAX_WORKSPACE_CACHE_SIZE) {
+		const excess = workspaceConnectionCache.size - MAX_WORKSPACE_CACHE_SIZE;
+		const keys = workspaceConnectionCache.keys();
+		for (let i = 0; i < excess; i++) {
+			const { value } = keys.next();
+			if (value) workspaceConnectionCache.delete(value);
+		}
+	}
+}
+function getSlackNango() {
+	const secretKey = env.NANGO_SLACK_SECRET_KEY || env.NANGO_SECRET_KEY;
+	if (!secretKey) throw new Error("NANGO_SLACK_SECRET_KEY or NANGO_SECRET_KEY is required for Slack integration");
+	return new Nango({
+		secretKey,
+		host: env.NANGO_SERVER_URL
+	});
+}
+function getSlackIntegrationId() {
+	return env.NANGO_SLACK_INTEGRATION_ID || "slack-agent";
+}
+async function createConnectSession(params) {
+	try {
+		const nango = getSlackNango();
+		const integrationId = getSlackIntegrationId();
+		const session = await nango.createConnectSession({
+			end_user: {
+				id: params.userId,
+				email: params.userEmail,
+				display_name: params.userName
+			},
+			organization: {
+				id: params.tenantId,
+				display_name: params.tenantId
+			},
+			allowed_integrations: [integrationId]
+		});
+		logger.info({
+			userId: params.userId,
+			userEmail: params.userEmail,
+			integrationId
+		}, "Created Nango connect session");
+		return { sessionToken: session.data.token };
+	} catch (error) {
+		logger.error({ error }, "Failed to create Nango connect session");
+		return null;
+	}
+}
+async function getConnectionAccessToken(connectionId) {
+	try {
+		const nango = getSlackNango();
+		const integrationId = getSlackIntegrationId();
+		return (await nango.getConnection(integrationId, connectionId)).credentials?.access_token || null;
+	} catch (error) {
+		logger.error({
+			error,
+			connectionId
+		}, "Failed to get connection access token");
+		return null;
+	}
+}
+/**
+* Find a workspace connection by Slack team ID.
+* Uses PostgreSQL first (O(1)) with in-memory caching, then falls back to Nango.
+*
+* Performance: This function is called on every @mention and command.
+* The PostgreSQL-first approach with caching provides O(1) lookups.
+*/
+async function findWorkspaceConnectionByTeamId(teamId) {
+	const cached = workspaceConnectionCache.get(teamId);
+	if (cached && cached.expiresAt > Date.now()) {
+		logger.debug({ teamId }, "Workspace connection cache hit");
+		return cached.connection;
+	}
+	try {
+		const dbWorkspace = await findWorkAppSlackWorkspaceBySlackTeamId(runDbClient_default)(teamId);
+		if (dbWorkspace?.nangoConnectionId) {
+			const botToken = await getConnectionAccessToken(dbWorkspace.nangoConnectionId);
+			if (botToken) {
+				const connection = {
+					connectionId: dbWorkspace.nangoConnectionId,
+					teamId,
+					teamName: dbWorkspace.slackTeamName || void 0,
+					botToken,
+					tenantId: dbWorkspace.tenantId,
+					defaultAgent: void 0
+				};
+				const defaultAgentConfig = await getWorkspaceDefaultAgentFromNangoByConnectionId(dbWorkspace.nangoConnectionId);
+				if (defaultAgentConfig) connection.defaultAgent = defaultAgentConfig;
+				evictWorkspaceCache();
+				workspaceConnectionCache.set(teamId, {
+					connection,
+					expiresAt: Date.now() + CACHE_TTL_MS
+				});
+				logger.debug({ teamId }, "Workspace connection found via PostgreSQL");
+				return connection;
+			}
+		}
+		logger.debug({ teamId }, "PostgreSQL lookup failed, falling back to Nango iteration");
+		return findWorkspaceConnectionByTeamIdFromNango(teamId);
+	} catch (error) {
+		logger.error({
+			error,
+			teamId
+		}, "Failed to find workspace connection by team ID");
+		return findWorkspaceConnectionByTeamIdFromNango(teamId);
+	}
+}
+async function getWorkspaceDefaultAgentFromNangoByConnectionId(connectionId) {
+	try {
+		const nango = getSlackNango();
+		const integrationId = getSlackIntegrationId();
+		const metadata = (await nango.getConnection(integrationId, connectionId)).metadata;
+		if (metadata?.default_agent) try {
+			return JSON.parse(metadata.default_agent);
+		} catch {
+			return null;
+		}
+		return null;
+	} catch (error) {
+		logger.warn({ error }, "Failed to get workspace default agent from Nango");
+		return null;
+	}
+}
+/**
+* Legacy fallback: Find workspace by iterating all Nango connections.
+* Only used when PostgreSQL lookup fails.
+*/
+async function findWorkspaceConnectionByTeamIdFromNango(teamId) {
+	try {
+		const nango = getSlackNango();
+		const integrationId = getSlackIntegrationId();
+		const connections = await nango.listConnections();
+		for (const conn of connections.connections) if (conn.provider_config_key === integrationId) try {
+			const fullConn = await nango.getConnection(integrationId, conn.connection_id);
+			const connectionConfig = fullConn.connection_config;
+			const metadata = fullConn.metadata;
+			const credentials = fullConn;
+			if ((connectionConfig?.["team.id"] || metadata?.slack_team_id) === teamId && credentials.credentials?.access_token) {
+				let defaultAgent;
+				if (metadata?.default_agent) try {
+					defaultAgent = JSON.parse(metadata.default_agent);
+				} catch {}
+				const connection = {
+					connectionId: conn.connection_id,
+					teamId,
+					teamName: metadata?.slack_team_name,
+					botToken: credentials.credentials.access_token,
+					tenantId: metadata?.tenant_id || metadata?.inkeep_tenant_id || "",
+					defaultAgent
+				};
+				evictWorkspaceCache();
+				workspaceConnectionCache.set(teamId, {
+					connection,
+					expiresAt: Date.now() + CACHE_TTL_MS
+				});
+				return connection;
+			}
+		} catch (error) {
+			logger.warn({
+				error,
+				connectionId: conn.connection_id
+			}, "Failed to get Nango connection details");
+		}
+		return null;
+	} catch (error) {
+		logger.error({
+			error,
+			teamId
+		}, "Failed to find workspace connection from Nango");
+		return null;
+	}
+}
+function clearWorkspaceConnectionCache(teamId) {
+	if (teamId) workspaceConnectionCache.delete(teamId);
+	else workspaceConnectionCache.clear();
+}
+async function updateConnectionMetadata(connectionId, metadata) {
+	try {
+		const nango = getSlackNango();
+		const integrationId = getSlackIntegrationId();
+		await nango.updateMetadata(integrationId, connectionId, metadata);
+		return true;
+	} catch (error) {
+		logger.error({
+			error,
+			connectionId
+		}, "Failed to update connection metadata");
+		return false;
+	}
+}
+async function setWorkspaceDefaultAgent(teamId, defaultAgent) {
+	try {
+		const workspace = await findWorkspaceConnectionByTeamId(teamId);
+		if (!workspace) {
+			logger.warn({ teamId }, "No workspace connection found to set default agent");
+			return false;
+		}
+		const success = await updateConnectionMetadata(workspace.connectionId, { default_agent: defaultAgent ? JSON.stringify(defaultAgent) : "" });
+		if (success) clearWorkspaceConnectionCache(teamId);
+		return success;
+	} catch (error) {
+		logger.error({
+			error,
+			teamId
+		}, "Failed to set workspace default agent");
+		return false;
+	}
+}
+async function getWorkspaceDefaultAgentFromNango(teamId) {
+	try {
+		return (await findWorkspaceConnectionByTeamId(teamId))?.defaultAgent || null;
+	} catch (error) {
+		logger.error({
+			error,
+			teamId
+		}, "Failed to get workspace default agent");
+		return null;
+	}
+}
+/**
+* Compute a stable, deterministic connection ID for a Slack workspace.
+* Format: "T:<team_id>" or "E:<enterprise_id>:T:<team_id>" for Enterprise Grid
+*/
+function computeWorkspaceConnectionId(params) {
+	const { teamId, enterpriseId } = params;
+	if (enterpriseId) return `E:${enterpriseId}:T:${teamId}`;
+	return `T:${teamId}`;
+}
+/**
+* Store a workspace installation in Nango.
+* Uses upsert semantics - will update if the connection already exists.
+*/
+async function storeWorkspaceInstallation(data) {
+	const connectionId = computeWorkspaceConnectionId({
+		teamId: data.teamId,
+		enterpriseId: data.enterpriseId
+	});
+	try {
+		const integrationId = getSlackIntegrationId();
+		const secretKey = env.NANGO_SLACK_SECRET_KEY || env.NANGO_SECRET_KEY;
+		if (!secretKey) {
+			logger.error({}, "No Nango secret key available");
+			return {
+				connectionId,
+				success: false
+			};
+		}
+		const nangoApiUrl = env.NANGO_SERVER_URL || "https://api.nango.dev";
+		logger.info({
+			integrationId,
+			connectionId,
+			teamId: data.teamId,
+			teamName: data.teamName
+		}, "Importing connection to Nango");
+		const displayName = data.enterpriseName ? `${data.teamName || data.teamId} (${data.enterpriseName})` : data.teamName || data.teamId;
+		const workspaceUrl = data.workspaceUrl || (data.teamDomain ? `https://${data.teamDomain}.slack.com` : "");
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const requestBody = {
+			provider_config_key: integrationId,
+			connection_id: connectionId,
+			credentials: {
+				type: "OAUTH2",
+				access_token: data.botToken
+			},
+			metadata: {
+				display_name: displayName,
+				connection_type: "workspace",
+				slack_team_id: data.teamId,
+				slack_team_name: data.teamName || "",
+				slack_team_domain: data.teamDomain || "",
+				slack_workspace_url: workspaceUrl,
+				slack_workspace_icon_url: data.workspaceIconUrl || "",
+				slack_enterprise_id: data.enterpriseId || "",
+				slack_enterprise_name: data.enterpriseName || "",
+				is_enterprise_install: String(data.isEnterpriseInstall || false),
+				slack_bot_user_id: data.botUserId || "",
+				slack_bot_scopes: data.botScopes || "",
+				slack_app_id: data.appId || "",
+				installed_by_slack_user_id: data.installerUserId || "",
+				installed_by_slack_user_name: data.installerUserName || "",
+				installed_at: now,
+				last_updated_at: now,
+				installation_source: data.installationSource || "dashboard",
+				inkeep_tenant_id: data.tenantId || "",
+				status: "active"
+			},
+			connection_config: { "team.id": data.teamId }
+		};
+		const response = await retryWithBackoff(async () => {
+			const controller = new AbortController();
+			const timeout = setTimeout(() => controller.abort(), 1e4);
+			try {
+				const res = await fetch(`${nangoApiUrl}/connections`, {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${secretKey}`,
+						"Content-Type": "application/json"
+					},
+					body: JSON.stringify(requestBody),
+					signal: controller.signal
+				});
+				if (!res.ok && res.status >= 500) {
+					const errorBody = await res.text().catch(() => "Unknown error");
+					const err = /* @__PURE__ */ new Error(`Nango API error ${res.status}: ${errorBody}`);
+					err.status = res.status;
+					throw err;
+				}
+				return res;
+			} finally {
+				clearTimeout(timeout);
+			}
+		});
+		const responseText = await response.text();
+		if (!response.ok) {
+			logger.error({
+				status: response.status,
+				errorBody: responseText,
+				connectionId
+			}, "Failed to import connection to Nango");
+			return {
+				connectionId,
+				success: false
+			};
+		}
+		logger.info({
+			connectionId,
+			teamId: data.teamId,
+			teamName: data.teamName
+		}, "Stored workspace installation in Nango");
+		return {
+			connectionId,
+			success: true
+		};
+	} catch (error) {
+		logger.error({
+			error,
+			connectionId,
+			teamId: data.teamId
+		}, "Failed to store workspace installation");
+		return {
+			connectionId,
+			success: false
+		};
+	}
+}
+/**
+* List all workspace installations from Nango.
+*/
+async function listWorkspaceInstallations() {
+	try {
+		const nango = getSlackNango();
+		const integrationId = getSlackIntegrationId();
+		const connections = await nango.listConnections();
+		const workspaces = [];
+		for (const conn of connections.connections) if (conn.provider_config_key === integrationId) try {
+			const fullConn = await nango.getConnection(integrationId, conn.connection_id);
+			const metadata = fullConn.metadata;
+			const credentials = fullConn;
+			if (metadata?.connection_type === "workspace" && credentials.credentials?.access_token) {
+				let defaultAgent;
+				if (metadata?.default_agent) try {
+					defaultAgent = JSON.parse(metadata.default_agent);
+				} catch {}
+				workspaces.push({
+					connectionId: conn.connection_id,
+					teamId: metadata.slack_team_id || "",
+					teamName: metadata.slack_team_name,
+					botToken: credentials.credentials.access_token,
+					tenantId: metadata.tenant_id || metadata.inkeep_tenant_id || "",
+					defaultAgent
+				});
+			}
+		} catch (error) {
+			logger.warn({
+				error,
+				connectionId: conn.connection_id
+			}, "Failed to get Nango connection during list");
+		}
+		return workspaces;
+	} catch (error) {
+		logger.error({ error }, "Failed to list workspace installations");
+		return [];
+	}
+}
+/**
+* Delete a workspace installation from Nango.
+*/
+async function deleteWorkspaceInstallation(connectionId) {
+	try {
+		const nango = getSlackNango();
+		const integrationId = getSlackIntegrationId();
+		logger.info({
+			connectionId,
+			integrationId
+		}, "Attempting to delete workspace installation");
+		await nango.deleteConnection(integrationId, connectionId);
+		logger.info({ connectionId }, "Deleted workspace installation from Nango");
+		return true;
+	} catch (error) {
+		const errorObj = error;
+		const errorMessage = errorObj?.message || String(error);
+		const statusCode = errorObj?.status;
+		if (statusCode === 404 || errorMessage.includes("404") || errorMessage.includes("not found")) {
+			logger.warn({ connectionId }, "Connection not found in Nango, treating as already deleted");
+			return true;
+		}
+		logger.error({
+			error: errorMessage,
+			statusCode,
+			connectionId
+		}, "Failed to delete workspace installation");
+		return false;
+	}
+}
+
+//#endregion
+export { clearWorkspaceConnectionCache, computeWorkspaceConnectionId, createConnectSession, deleteWorkspaceInstallation, findWorkspaceConnectionByTeamId, getConnectionAccessToken, getSlackIntegrationId, getSlackNango, getWorkspaceDefaultAgentFromNango, listWorkspaceInstallations, setWorkspaceDefaultAgent, storeWorkspaceInstallation, updateConnectionMetadata };

package/dist/slack/services/security.d.ts

@@ -0,0 +1,35 @@
+//#region src/slack/services/security.d.ts
+/**
+ * Slack Security Utilities
+ *
+ * Provides security functions for verifying Slack requests and parsing payloads.
+ * All incoming Slack requests are verified using HMAC-SHA256 signatures.
+ */
+/**
+ * Verify that a request originated from Slack using HMAC-SHA256 signature.
+ *
+ * @param signingSecret - The Slack signing secret from app settings
+ * @param requestBody - The raw request body string
+ * @param timestamp - The X-Slack-Request-Timestamp header value
+ * @param signature - The X-Slack-Signature header value
+ * @returns true if the signature is valid, false otherwise
+ */
+declare function verifySlackRequest(signingSecret: string, requestBody: string, timestamp: string, signature: string): boolean;
+/**
+ * Parse a URL-encoded Slack command body into key-value pairs.
+ *
+ * @param body - The URL-encoded request body from a slash command
+ * @returns Parsed parameters as a string record
+ */
+declare function parseSlackCommandBody(body: string): Record<string, string>;
+/**
+ * Parse a Slack event body based on content type.
+ * Handles both JSON and URL-encoded payloads (for interactive components).
+ *
+ * @param body - The raw request body
+ * @param contentType - The Content-Type header value
+ * @returns Parsed event payload
+ */
+declare function parseSlackEventBody(body: string, contentType: string): Record<string, unknown>;
+//#endregion
+export { parseSlackCommandBody, parseSlackEventBody, verifySlackRequest };

package/dist/slack/services/security.js

@@ -0,0 +1,65 @@
+import { getLogger } from "../../logger.js";
+import crypto from "node:crypto";
+
+//#region src/slack/services/security.ts
+/**
+* Slack Security Utilities
+*
+* Provides security functions for verifying Slack requests and parsing payloads.
+* All incoming Slack requests are verified using HMAC-SHA256 signatures.
+*/
+const logger = getLogger("slack-security");
+/**
+* Verify that a request originated from Slack using HMAC-SHA256 signature.
+*
+* @param signingSecret - The Slack signing secret from app settings
+* @param requestBody - The raw request body string
+* @param timestamp - The X-Slack-Request-Timestamp header value
+* @param signature - The X-Slack-Signature header value
+* @returns true if the signature is valid, false otherwise
+*/
+function verifySlackRequest(signingSecret, requestBody, timestamp, signature) {
+	try {
+		const fiveMinutesAgo = Math.floor(Date.now() / 1e3) - 300;
+		if (Number.parseInt(timestamp, 10) < fiveMinutesAgo) {
+			logger.warn({}, "Slack request timestamp too old");
+			return false;
+		}
+		const sigBaseString = `v0:${timestamp}:${requestBody}`;
+		const mySignature = `v0=${crypto.createHmac("sha256", signingSecret).update(sigBaseString).digest("hex")}`;
+		return crypto.timingSafeEqual(Buffer.from(mySignature), Buffer.from(signature));
+	} catch (error) {
+		logger.error({ error }, "Error verifying Slack request");
+		return false;
+	}
+}
+/**
+* Parse a URL-encoded Slack command body into key-value pairs.
+*
+* @param body - The URL-encoded request body from a slash command
+* @returns Parsed parameters as a string record
+*/
+function parseSlackCommandBody(body) {
+	const params = new URLSearchParams(body);
+	return Object.fromEntries(params.entries());
+}
+/**
+* Parse a Slack event body based on content type.
+* Handles both JSON and URL-encoded payloads (for interactive components).
+*
+* @param body - The raw request body
+* @param contentType - The Content-Type header value
+* @returns Parsed event payload
+*/
+function parseSlackEventBody(body, contentType) {
+	if (contentType.includes("application/x-www-form-urlencoded")) {
+		const params = new URLSearchParams(body);
+		const payload = params.get("payload");
+		if (payload) return JSON.parse(payload);
+		return Object.fromEntries(params.entries());
+	}
+	return JSON.parse(body);
+}
+
+//#endregion
+export { parseSlackCommandBody, parseSlackEventBody, verifySlackRequest };

package/dist/slack/services/types.d.ts

@@ -0,0 +1,26 @@
+import { MessageAttachment } from "@slack/types";
+
+//#region src/slack/services/types.d.ts
+interface SlackCommandPayload {
+  command: string;
+  text: string;
+  userId: string;
+  userName: string;
+  teamId: string;
+  teamDomain: string;
+  enterpriseId?: string;
+  channelId: string;
+  channelName: string;
+  responseUrl: string;
+  triggerId: string;
+}
+interface SlackCommandResponse {
+  response_type?: 'ephemeral' | 'in_channel';
+  text?: string;
+  blocks?: unknown[];
+  attachments?: MessageAttachment[];
+  replace_original?: boolean;
+  delete_original?: boolean;
+}
+//#endregion
+export { SlackCommandPayload, SlackCommandResponse };

package/dist/slack/services/types.js

@@ -0,0 +1 @@
+export {  };

package/dist/slack/services/workspace-tokens.d.ts

@@ -0,0 +1,25 @@
+//#region src/slack/services/workspace-tokens.d.ts
+/**
+ * Workspace Token Service
+ *
+ * In-memory cache for Slack bot tokens during OAuth installation flow.
+ * Primary token storage is in Nango; this is a temporary fallback.
+ *
+ * Note: Tokens stored here do not persist across server restarts.
+ * Always prefer fetching tokens from Nango for production use.
+ */
+/**
+ * Get the cached bot token for a Slack team.
+ * Falls back to null if not cached (caller should fetch from Nango).
+ */
+declare function getBotTokenForTeam(teamId: string): string | null;
+/**
+ * Cache a bot token for a Slack team (used during OAuth installation).
+ */
+declare function setBotTokenForTeam(teamId: string, data: {
+  botToken: string;
+  teamName: string;
+  installedAt: string;
+}): void;
+//#endregion
+export { getBotTokenForTeam, setBotTokenForTeam };

package/dist/slack/services/workspace-tokens.js

@@ -0,0 +1,27 @@
+//#region src/slack/services/workspace-tokens.ts
+/**
+* Workspace Token Service
+*
+* In-memory cache for Slack bot tokens during OAuth installation flow.
+* Primary token storage is in Nango; this is a temporary fallback.
+*
+* Note: Tokens stored here do not persist across server restarts.
+* Always prefer fetching tokens from Nango for production use.
+*/
+const workspaceBotTokens = /* @__PURE__ */ new Map();
+/**
+* Get the cached bot token for a Slack team.
+* Falls back to null if not cached (caller should fetch from Nango).
+*/
+function getBotTokenForTeam(teamId) {
+	return workspaceBotTokens.get(teamId)?.botToken || null;
+}
+/**
+* Cache a bot token for a Slack team (used during OAuth installation).
+*/
+function setBotTokenForTeam(teamId, data) {
+	workspaceBotTokens.set(teamId, data);
+}
+
+//#endregion
+export { getBotTokenForTeam, setBotTokenForTeam };