@agent-native/core 0.113.0 → 0.114.1

package/src/integrations/slack-oauth.ts

@@ -0,0 +1,344 @@
+/** Slack OAuth v2 helpers for managed Agent Native messaging installs. */
+
+import type { SecretScope } from "../secrets/register.js";
+import type {
+  IntegrationInstallationHealth,
+  UpsertIntegrationInstallationInput,
+} from "./installations-store.js";
+
+export const SLACK_AUTHORIZE_URL = "https://slack.com/oauth/v2/authorize";
+export const SLACK_TOKEN_URL = "https://slack.com/api/oauth.v2.access";
+export const SLACK_AUTH_TEST_URL = "https://slack.com/api/auth.test";
+
+/** Scopes needed for contextual, file-aware Agent Native conversations. */
+export const SLACK_AGENT_BOT_SCOPES = [
+  "assistant:write",
+  "app_mentions:read",
+  "channels:join",
+  "channels:read",
+  "channels:history",
+  "chat:write",
+  "files:read",
+  "groups:history",
+  "groups:read",
+  "im:history",
+  "im:read",
+  "mpim:history",
+  "mpim:read",
+  "pins:read",
+  "reactions:read",
+  "users:read",
+  "users:read.email",
+] as const;
+
+export interface SlackOAuthAccessResponse {
+  ok?: boolean;
+  error?: string;
+  access_token?: string;
+  refresh_token?: string;
+  expires_in?: number;
+  token_type?: string;
+  scope?: string;
+  bot_user_id?: string;
+  app_id?: string;
+  is_enterprise_install?: boolean;
+  authed_user?: { id?: string };
+  team?: { id?: string; name?: string } | null;
+  enterprise?: { id?: string; name?: string } | null;
+}
+
+interface SlackApiResponse {
+  ok?: boolean;
+  error?: string;
+  team_id?: string;
+  team?: string;
+  enterprise_id?: string;
+  enterprise?: string;
+  user_id?: string;
+  bot_id?: string;
+  url?: string;
+}
+
+export interface SlackAuthHealth {
+  ok: boolean;
+  health: IntegrationInstallationHealth;
+  error: string | null;
+  checkedAt: number;
+  teamId: string | null;
+  enterpriseId: string | null;
+  botId: string | null;
+  userId: string | null;
+}
+
+export interface SlackInstallSession {
+  email?: string | null;
+  orgId?: string | null;
+  orgRole?: string | null;
+}
+
+export interface SlackInstallAccess {
+  ownerEmail: string;
+  orgId: string | null;
+  secretScope: SecretScope;
+  secretScopeId: string;
+}
+
+function safeSlackError(value: unknown, fallback: string): string {
+  return typeof value === "string" && /^[a-z0-9_.-]{1,100}$/i.test(value)
+    ? value
+    : fallback;
+}
+
+export function buildSlackAuthorizeUrl(options: {
+  clientId: string;
+  redirectUri: string;
+  state: string;
+  scopes?: readonly string[];
+  userScopes?: readonly string[];
+  teamId?: string;
+}): string {
+  const params = new URLSearchParams({
+    client_id: options.clientId,
+    redirect_uri: options.redirectUri,
+    response_type: "code",
+    scope: (options.scopes ?? SLACK_AGENT_BOT_SCOPES).join(","),
+    state: options.state,
+  });
+  if (options.userScopes?.length) {
+    params.set("user_scope", options.userScopes.join(","));
+  }
+  if (options.teamId) params.set("team", options.teamId);
+  return `${SLACK_AUTHORIZE_URL}?${params.toString()}`;
+}
+
+/** Exchange an OAuth code using Slack's preferred HTTP Basic authentication. */
+export async function exchangeSlackOAuthCode(options: {
+  code: string;
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  fetchImpl?: typeof fetch;
+}): Promise<SlackOAuthAccessResponse> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const authorization = Buffer.from(
+    `${options.clientId}:${options.clientSecret}`,
+    "utf8",
+  ).toString("base64");
+  const response = await fetchImpl(SLACK_TOKEN_URL, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${authorization}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams({
+      code: options.code,
+      redirect_uri: options.redirectUri,
+    }),
+  });
+  const data = (await response
+    .json()
+    .catch(() => null)) as SlackOAuthAccessResponse | null;
+  if (!response.ok || !data?.ok) {
+    throw new Error(
+      safeSlackError(
+        data?.error,
+        `Slack OAuth exchange failed (${response.status})`,
+      ),
+    );
+  }
+  return data;
+}
+
+/**
+ * Rotate an expiring Slack token. Slack refresh tokens are one-time-use, so
+ * callers must atomically persist the returned access/refresh pair together.
+ */
+export async function refreshSlackOAuthToken(options: {
+  refreshToken: string;
+  clientId: string;
+  clientSecret: string;
+  fetchImpl?: typeof fetch;
+}): Promise<SlackOAuthAccessResponse> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const authorization = Buffer.from(
+    `${options.clientId}:${options.clientSecret}`,
+    "utf8",
+  ).toString("base64");
+  const response = await fetchImpl(SLACK_TOKEN_URL, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${authorization}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: options.refreshToken,
+    }),
+  });
+  const data = (await response
+    .json()
+    .catch(() => null)) as SlackOAuthAccessResponse | null;
+  if (!response.ok || !data?.ok) {
+    throw new Error(
+      safeSlackError(
+        data?.error,
+        `Slack OAuth token refresh failed (${response.status})`,
+      ),
+    );
+  }
+  if (!data.access_token || !data.refresh_token) {
+    throw new Error("Slack OAuth token refresh returned an incomplete bundle");
+  }
+  return data;
+}
+
+/** Validate a bot token without ever including it in an error or result. */
+export async function testSlackAuth(
+  accessToken: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<SlackAuthHealth> {
+  const checkedAt = Date.now();
+  try {
+    const response = await fetchImpl(SLACK_AUTH_TEST_URL, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    const data = (await response
+      .json()
+      .catch(() => null)) as SlackApiResponse | null;
+    if (!response.ok || !data?.ok) {
+      const error = safeSlackError(
+        data?.error,
+        `Slack auth test failed (${response.status})`,
+      );
+      return {
+        ok: false,
+        health:
+          error === "invalid_auth" || error === "token_revoked"
+            ? "revoked"
+            : "degraded",
+        error,
+        checkedAt,
+        teamId: null,
+        enterpriseId: null,
+        botId: null,
+        userId: null,
+      };
+    }
+    return {
+      ok: true,
+      health: "healthy",
+      error: null,
+      checkedAt,
+      teamId: data.team_id ?? null,
+      enterpriseId: data.enterprise_id ?? null,
+      botId: data.bot_id ?? null,
+      userId: data.user_id ?? null,
+    };
+  } catch {
+    return {
+      ok: false,
+      health: "degraded",
+      error: "Slack auth test request failed",
+      checkedAt,
+      teamId: null,
+      enterpriseId: null,
+      botId: null,
+      userId: null,
+    };
+  }
+}
+
+/** Stable team/app key used by webhook payloads and the installation store. */
+export function slackInstallationKey(input: {
+  teamId?: string | null;
+  enterpriseId?: string | null;
+  apiAppId?: string | null;
+  isEnterpriseInstall?: boolean;
+}): string {
+  const workspaceId = input.isEnterpriseInstall
+    ? input.enterpriseId
+    : (input.teamId ?? input.enterpriseId);
+  if (!workspaceId) {
+    throw new Error("Slack OAuth did not return a team or enterprise id");
+  }
+  return `${input.isEnterpriseInstall ? "enterprise" : "team"}:${workspaceId}:app:${input.apiAppId || "default"}`;
+}
+
+/**
+ * Convert a successful Slack response to the generic managed-install input.
+ * The returned token bundle is server-only and must be passed directly to the
+ * encrypted installation store, never to a route response.
+ */
+export function slackOAuthResponseToInstallation(
+  response: SlackOAuthAccessResponse,
+  access: SlackInstallAccess,
+  now = Date.now(),
+): UpsertIntegrationInstallationInput {
+  if (!response.ok || !response.access_token) {
+    throw new Error("Slack OAuth response did not include a bot access token");
+  }
+  const installationKey = slackInstallationKey({
+    teamId: response.team?.id,
+    enterpriseId: response.enterprise?.id,
+    apiAppId: response.app_id,
+    isEnterpriseInstall: response.is_enterprise_install,
+  });
+  const expiresAt =
+    typeof response.expires_in === "number" && response.expires_in > 0
+      ? now + response.expires_in * 1000
+      : undefined;
+  return {
+    platform: "slack",
+    installationKey,
+    teamId: response.team?.id ?? null,
+    teamName: response.team?.name ?? null,
+    enterpriseId: response.enterprise?.id ?? null,
+    enterpriseName: response.enterprise?.name ?? null,
+    isEnterpriseInstall: response.is_enterprise_install === true,
+    apiAppId: response.app_id ?? null,
+    botUserId: response.bot_user_id ?? null,
+    scopes: response.scope?.split(",").map((scope) => scope.trim()) ?? [],
+    installedByExternalUserId: response.authed_user?.id ?? null,
+    ownerEmail: access.ownerEmail,
+    orgId: access.orgId,
+    secretScope: access.secretScope,
+    secretScopeId: access.secretScopeId,
+    tokenBundle: {
+      accessToken: response.access_token,
+      refreshToken: response.refresh_token,
+      tokenType: response.token_type,
+      expiresAt,
+    },
+    tokenExpiresAt: expiresAt ?? null,
+  };
+}
+
+/**
+ * Pure session/role gate for OAuth install routes. The caller must supply a
+ * server-verified session; org membership must be the active org context.
+ */
+export function assertSlackInstallAccess(
+  session: SlackInstallSession | null | undefined,
+): SlackInstallAccess {
+  const ownerEmail = session?.email?.trim().toLowerCase();
+  if (!ownerEmail) throw new Error("Sign in before connecting Slack.");
+  const orgId = session?.orgId?.trim() || null;
+  if (!orgId) {
+    return {
+      ownerEmail,
+      orgId: null,
+      secretScope: "user",
+      secretScopeId: ownerEmail,
+    };
+  }
+  if (session?.orgRole !== "owner" && session?.orgRole !== "admin") {
+    throw new Error("Only organization owners and admins can connect Slack.");
+  }
+  return {
+    ownerEmail,
+    orgId,
+    secretScope: "org",
+    secretScopeId: orgId,
+  };
+}

package/src/integrations/task-queue-stats.ts

@@ -0,0 +1,144 @@
+/**
+ * Read-only observability helpers for the integration task queue.
+ *
+ * Lives in its own file so it stays out of `pending-tasks-store.ts`, which is
+ * actively being edited by the agent that owns the queue itself. These
+ * helpers only SELECT — they never write — and they degrade gracefully if
+ * the `integration_pending_tasks` table doesn't exist yet (returning zeroed
+ * stats instead of throwing).
+ */
+import { getDbExec } from "../db/client.js";
+
+export interface RecentFailure {
+  id: string;
+  platform: string;
+  error: string;
+  attempts: number;
+}
+
+export interface TaskQueueStats {
+  pending: number;
+  processing: number;
+  completed_last_hour: number;
+  failed_last_hour: number;
+  oldest_pending_age_seconds: number;
+  recent_failures: RecentFailure[];
+}
+
+const ZERO_STATS: TaskQueueStats = {
+  pending: 0,
+  processing: 0,
+  completed_last_hour: 0,
+  failed_last_hour: 0,
+  oldest_pending_age_seconds: 0,
+  recent_failures: [],
+};
+
+function isMissingTableError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err ?? "");
+  return /no such table|does not exist|relation .* does not exist|undefined_table/i.test(
+    msg,
+  );
+}
+
+/**
+ * Get a snapshot of the integration task queue health.
+ *
+ * Returns zeros if the table doesn't exist yet — safe to call before the
+ * pending-tasks store has initialised the schema.
+ */
+export async function getTaskQueueStats(): Promise<TaskQueueStats> {
+  const client = getDbExec();
+  const now = Date.now();
+  const oneHourAgo = now - 60 * 60 * 1000;
+
+  try {
+    // Status counts (pending, processing) — only need the live ones.
+    const liveCounts = await client.execute({
+      sql: `SELECT status, COUNT(*) AS c FROM integration_pending_tasks
+            WHERE status IN ('pending', 'processing')
+            GROUP BY status`,
+      args: [],
+    });
+
+    let pending = 0;
+    let processing = 0;
+    for (const row of liveCounts.rows as Array<Record<string, unknown>>) {
+      const status = row.status as string;
+      const count = Number(row.c ?? 0);
+      if (status === "pending") pending = count;
+      else if (status === "processing") processing = count;
+    }
+
+    // Last-hour completion + failure counts. updated_at is the most reliable
+    // column — completed_at can be null on failed tasks, and created_at would
+    // miss tasks queued >1h ago that just finished now.
+    const lastHourCounts = await client.execute({
+      sql: `SELECT status, COUNT(*) AS c FROM integration_pending_tasks
+            WHERE status IN ('completed', 'failed') AND updated_at >= ?
+            GROUP BY status`,
+      args: [oneHourAgo],
+    });
+
+    let completedLastHour = 0;
+    let failedLastHour = 0;
+    for (const row of lastHourCounts.rows as Array<Record<string, unknown>>) {
+      const status = row.status as string;
+      const count = Number(row.c ?? 0);
+      if (status === "completed") completedLastHour = count;
+      else if (status === "failed") failedLastHour = count;
+    }
+
+    // Oldest pending task — used to surface stuck queues.
+    let oldestPendingAgeSeconds = 0;
+    if (pending > 0) {
+      const oldest = await client.execute({
+        sql: `SELECT created_at FROM integration_pending_tasks
+              WHERE status = 'pending'
+              ORDER BY created_at ASC
+              LIMIT 1`,
+        args: [],
+      });
+      const oldestRow = oldest.rows[0] as Record<string, unknown> | undefined;
+      if (oldestRow) {
+        const createdAt = Number(oldestRow.created_at ?? now);
+        oldestPendingAgeSeconds = Math.max(
+          0,
+          Math.floor((now - createdAt) / 1000),
+        );
+      }
+    }
+
+    // Recent failures, capped at 5 — enough to spot patterns without
+    // blowing up the response payload.
+    const failures = await client.execute({
+      sql: `SELECT id, platform, error_message, attempts FROM integration_pending_tasks
+            WHERE status = 'failed' AND updated_at >= ?
+            ORDER BY updated_at DESC
+            LIMIT 5`,
+      args: [oneHourAgo],
+    });
+    const recentFailures: RecentFailure[] = (
+      failures.rows as Array<Record<string, unknown>>
+    ).map((row) => ({
+      id: String(row.id ?? ""),
+      platform: String(row.platform ?? ""),
+      error: String(row.error_message ?? ""),
+      attempts: Number(row.attempts ?? 0),
+    }));
+
+    return {
+      pending,
+      processing,
+      completed_last_hour: completedLastHour,
+      failed_last_hour: failedLastHour,
+      oldest_pending_age_seconds: oldestPendingAgeSeconds,
+      recent_failures: recentFailures,
+    };
+  } catch (err) {
+    if (isMissingTableError(err)) {
+      return { ...ZERO_STATS, recent_failures: [] };
+    }
+    throw err;
+  }
+}

package/src/integrations/thread-mapping-store.ts

@@ -0,0 +1,134 @@
+import { getDbExec, isPostgres, intType } from "../db/client.js";
+import { ensureTableExists } from "../db/ddl-guard.js";
+
+let _initPromise: Promise<void> | undefined;
+
+async function ensureTable(): Promise<void> {
+  if (!_initPromise) {
+    _initPromise = (async () => {
+      const client = getDbExec();
+      const createSql = `
+        CREATE TABLE IF NOT EXISTS integration_thread_mappings (
+          platform TEXT NOT NULL,
+          external_thread_id TEXT NOT NULL,
+          internal_thread_id TEXT NOT NULL,
+          platform_context TEXT NOT NULL DEFAULT '{}',
+          created_at ${intType()} NOT NULL,
+          updated_at ${intType()} NOT NULL,
+          PRIMARY KEY (platform, external_thread_id)
+        )
+      `;
+
+      if (isPostgres()) {
+        // PG guard: probe via information_schema, only issue DDL if missing, bounded lock_timeout
+        await ensureTableExists("integration_thread_mappings", createSql);
+        return;
+      }
+      // SQLite (local dev): keep existing behavior
+      await client.execute(createSql);
+    })().catch((err) => {
+      // Retry init on the next call after a failed startup.
+      _initPromise = undefined;
+      throw err;
+    });
+  }
+  return _initPromise;
+}
+
+export interface ThreadMapping {
+  platform: string;
+  externalThreadId: string;
+  internalThreadId: string;
+  platformContext: Record<string, unknown>;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/**
+ * Look up the internal thread ID for an external platform thread.
+ */
+export async function getThreadMapping(
+  platform: string,
+  externalThreadId: string,
+): Promise<ThreadMapping | null> {
+  await ensureTable();
+  const client = getDbExec();
+  const { rows } = await client.execute({
+    sql: `SELECT platform, external_thread_id, internal_thread_id, platform_context, created_at, updated_at FROM integration_thread_mappings WHERE platform = ? AND external_thread_id = ?`,
+    args: [platform, externalThreadId],
+  });
+  if (rows.length === 0) return null;
+  const row = rows[0];
+  return {
+    platform: row.platform as string,
+    externalThreadId: row.external_thread_id as string,
+    internalThreadId: row.internal_thread_id as string,
+    platformContext: JSON.parse(row.platform_context as string),
+    createdAt: row.created_at as number,
+    updatedAt: row.updated_at as number,
+  };
+}
+
+/**
+ * Create or update a thread mapping.
+ */
+export async function saveThreadMapping(
+  platform: string,
+  externalThreadId: string,
+  internalThreadId: string,
+  platformContext: Record<string, unknown> = {},
+): Promise<void> {
+  await ensureTable();
+  const client = getDbExec();
+  const now = Date.now();
+  await client.execute({
+    sql: isPostgres()
+      ? `INSERT INTO integration_thread_mappings (platform, external_thread_id, internal_thread_id, platform_context, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT (platform, external_thread_id) DO UPDATE SET internal_thread_id=EXCLUDED.internal_thread_id, platform_context=EXCLUDED.platform_context, updated_at=EXCLUDED.updated_at`
+      : `INSERT OR REPLACE INTO integration_thread_mappings (platform, external_thread_id, internal_thread_id, platform_context, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)`,
+    args: [
+      platform,
+      externalThreadId,
+      internalThreadId,
+      JSON.stringify(platformContext),
+      now,
+      now,
+    ],
+  });
+}
+
+/**
+ * Delete a thread mapping.
+ */
+export async function deleteThreadMapping(
+  platform: string,
+  externalThreadId: string,
+): Promise<void> {
+  await ensureTable();
+  const client = getDbExec();
+  await client.execute({
+    sql: `DELETE FROM integration_thread_mappings WHERE platform = ? AND external_thread_id = ?`,
+    args: [platform, externalThreadId],
+  });
+}
+
+/**
+ * List all thread mappings for a platform.
+ */
+export async function listThreadMappings(
+  platform: string,
+): Promise<ThreadMapping[]> {
+  await ensureTable();
+  const client = getDbExec();
+  const { rows } = await client.execute({
+    sql: `SELECT platform, external_thread_id, internal_thread_id, platform_context, created_at, updated_at FROM integration_thread_mappings WHERE platform = ?`,
+    args: [platform],
+  });
+  return rows.map((row) => ({
+    platform: row.platform as string,
+    externalThreadId: row.external_thread_id as string,
+    internalThreadId: row.internal_thread_id as string,
+    platformContext: JSON.parse(row.platform_context as string),
+    createdAt: row.created_at as number,
+    updatedAt: row.updated_at as number,
+  }));
+}