@lobu/gateway 3.0.5 → 3.0.6

package/src/permissions/approval-policy.ts

@@ -0,0 +1,36 @@
+/**
+ * MCP Tool Approval Policy
+ *
+ * Uses MCP protocol tool annotations to determine whether a tool call
+ * requires explicit user approval (grant) before execution.
+ *
+ * Per the MCP spec, the default assumption is destructiveHint=true,
+ * so tools without annotations require approval (conservative default).
+ */
+
+export interface McpToolAnnotations {
+  readOnlyHint?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+}
+
+/**
+ * Determine if a tool call requires user approval based on its annotations.
+ *
+ * Returns false (no approval needed) when:
+ *   - readOnlyHint is explicitly true
+ *   - destructiveHint is explicitly false
+ *
+ * Returns true (approval required) otherwise, including when:
+ *   - No annotations provided (conservative default)
+ *   - destructiveHint is true (default per MCP spec)
+ */
+export function requiresToolApproval(
+  annotations?: McpToolAnnotations
+): boolean {
+  if (!annotations) return true;
+  if (annotations.readOnlyHint === true) return false;
+  if (annotations.destructiveHint === false) return false;
+  return true;
+}

package/src/permissions/grant-store.ts

@@ -0,0 +1,219 @@
+import { createLogger } from "@lobu/core";
+
+const logger = createLogger("grant-store");
+
+export interface Grant {
+  pattern: string;
+  expiresAt: number | null; // Absolute timestamp (ms). null = never expires.
+  grantedAt: number;
+  denied?: boolean; // true = explicitly deny this pattern
+}
+
+const KEY_PREFIX = "grant:";
+
+/**
+ * Unified grant store for URL-pattern permissions.
+ *
+ * Patterns can be:
+ *   - Domain: "api.openai.com", "*.npmjs.org"
+ *   - MCP tool: "/mcp/gmail/tools/send_email"
+ *   - MCP wildcard: "/mcp/gmail/tools/*"
+ *
+ * Grants are stored in Redis with TTL matching expiresAt for automatic cleanup.
+ */
+export class GrantStore {
+  constructor(private readonly redis: any) {}
+
+  /**
+   * Grant access to a pattern for an agent.
+   * If expiresAt is null, the grant never expires (no Redis TTL).
+   * If denied is true, the grant explicitly denies access.
+   */
+  async grant(
+    agentId: string,
+    pattern: string,
+    expiresAt: number | null,
+    denied?: boolean
+  ): Promise<void> {
+    const key = this.buildKey(agentId, pattern);
+    const value = JSON.stringify({
+      expiresAt,
+      grantedAt: Date.now(),
+      ...(denied && { denied: true }),
+    });
+
+    try {
+      if (expiresAt === null) {
+        await this.redis.set(key, value);
+      } else {
+        const ttlSeconds = Math.max(
+          1,
+          Math.ceil((expiresAt - Date.now()) / 1000)
+        );
+        await this.redis.set(key, value, "EX", ttlSeconds);
+      }
+      logger.info("Granted access", { agentId, pattern, expiresAt });
+    } catch (error) {
+      logger.error("Failed to grant access", { agentId, pattern, error });
+      throw error;
+    }
+  }
+
+  /**
+   * Parse a raw Redis value into its stored object.
+   * Returns null if the value is missing or malformed.
+   */
+  private parseValue(
+    raw: string | null
+  ): { expiresAt: number | null; grantedAt: number; denied?: boolean } | null {
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Check if an agent has a grant for a pattern.
+   * Checks exact match first, then wildcard parents.
+   * Returns false if the grant has `denied: true`.
+   */
+  async hasGrant(agentId: string, pattern: string): Promise<boolean> {
+    // Exact match
+    const exactKey = this.buildKey(agentId, pattern);
+    try {
+      const parsed = this.parseValue(await this.redis.get(exactKey));
+      if (parsed) return !parsed.denied;
+    } catch (error) {
+      logger.error("Failed to check grant", { agentId, pattern, error });
+      return false;
+    }
+
+    // Wildcard check for MCP tool patterns:
+    // "/mcp/gmail/tools/send_email" is covered by "/mcp/gmail/tools/*"
+    if (pattern.startsWith("/mcp/")) {
+      const lastSlash = pattern.lastIndexOf("/");
+      if (lastSlash > 0) {
+        const wildcardPattern = `${pattern.substring(0, lastSlash)}/*`;
+        const wildcardKey = this.buildKey(agentId, wildcardPattern);
+        try {
+          const parsed = this.parseValue(await this.redis.get(wildcardKey));
+          if (parsed) return !parsed.denied;
+        } catch (error) {
+          logger.error("Failed to check wildcard grant", {
+            agentId,
+            pattern: wildcardPattern,
+            error,
+          });
+        }
+      }
+    }
+
+    // Wildcard check for domain patterns:
+    // "sub.example.com" is covered by "*.example.com"
+    if (!pattern.startsWith("/")) {
+      const parts = pattern.split(".");
+      if (parts.length > 2) {
+        const wildcardDomain = `*.${parts.slice(1).join(".")}`;
+        const wildcardKey = this.buildKey(agentId, wildcardDomain);
+        try {
+          const parsed = this.parseValue(await this.redis.get(wildcardKey));
+          if (parsed) return !parsed.denied;
+        } catch (error) {
+          logger.error("Failed to check wildcard domain grant", {
+            agentId,
+            pattern: wildcardDomain,
+            error,
+          });
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if a pattern is explicitly denied for an agent.
+   */
+  async isDenied(agentId: string, pattern: string): Promise<boolean> {
+    const key = this.buildKey(agentId, pattern);
+    try {
+      const parsed = this.parseValue(await this.redis.get(key));
+      return parsed?.denied === true;
+    } catch (error) {
+      logger.error("Failed to check denied grant", {
+        agentId,
+        pattern,
+        error,
+      });
+      return false;
+    }
+  }
+
+  /**
+   * List all active grants for an agent.
+   * Uses Redis SCAN to find matching keys.
+   */
+  async listGrants(agentId: string): Promise<Grant[]> {
+    const prefix = `${KEY_PREFIX}${agentId}:`;
+    const grants: Grant[] = [];
+
+    try {
+      let cursor = "0";
+      do {
+        const [nextCursor, keys] = await this.redis.scan(
+          cursor,
+          "MATCH",
+          `${prefix}*`,
+          "COUNT",
+          100
+        );
+        cursor = nextCursor;
+
+        if (keys.length > 0) {
+          const values = await this.redis.mget(...keys);
+          for (let i = 0; i < keys.length; i++) {
+            const val = values[i];
+            if (!val) continue;
+
+            try {
+              const parsed = JSON.parse(val);
+              const pattern = (keys[i] as string).substring(prefix.length);
+              grants.push({
+                pattern,
+                expiresAt: parsed.expiresAt ?? null,
+                grantedAt: parsed.grantedAt,
+                ...(parsed.denied && { denied: true }),
+              });
+            } catch {
+              // Skip malformed entries
+            }
+          }
+        }
+      } while (cursor !== "0");
+    } catch (error) {
+      logger.error("Failed to list grants", { agentId, error });
+    }
+
+    return grants;
+  }
+
+  /**
+   * Revoke a grant for an agent.
+   */
+  async revoke(agentId: string, pattern: string): Promise<void> {
+    const key = this.buildKey(agentId, pattern);
+    try {
+      await this.redis.del(key);
+      logger.info("Revoked grant", { agentId, pattern });
+    } catch (error) {
+      logger.error("Failed to revoke grant", { agentId, pattern, error });
+      throw error;
+    }
+  }
+
+  private buildKey(agentId: string, pattern: string): string {
+    return `${KEY_PREFIX}${agentId}:${pattern}`;
+  }
+}

package/src/platform/file-handler.ts

@@ -0,0 +1,66 @@
+/**
+ * File handler interface for platform-specific file operations.
+ */
+
+import type { Readable } from "node:stream";
+
+export interface FileMetadata {
+  id: string;
+  name: string;
+  mimetype?: string;
+  size: number;
+  url: string;
+  downloadUrl?: string;
+  permalink?: string;
+  timestamp?: number;
+}
+
+export interface FileUploadResult {
+  fileId: string;
+  permalink: string;
+  name: string;
+  size: number;
+}
+
+export interface FileUploadOptions {
+  filename: string;
+  channelId: string;
+  threadTs?: string;
+  title?: string;
+  initialComment?: string;
+  sessionKey?: string;
+  /** Send as voice message (ptt) on platforms that support it */
+  voiceMessage?: boolean;
+}
+
+export interface IFileHandler {
+  /**
+   * Download a file by its platform-specific ID.
+   * Each platform implementation handles its own authentication internally.
+   */
+  downloadFile(
+    fileId: string
+  ): Promise<{ stream: Readable; metadata: FileMetadata }>;
+
+  uploadFile(
+    fileStream: Readable,
+    options: FileUploadOptions
+  ): Promise<FileUploadResult>;
+
+  generateFileToken(
+    sessionKey: string,
+    fileId: string,
+    expiresIn?: number
+  ): string;
+
+  validateFileToken(token: string): {
+    valid: boolean;
+    sessionKey?: string;
+    fileId?: string;
+    error?: string;
+  };
+
+  getSessionFiles(sessionKey: string): string[];
+
+  cleanupSession(sessionKey: string): void;
+}

package/src/platform/link-buttons.ts

@@ -0,0 +1,57 @@
+/**
+ * Extract settings link buttons from markdown content.
+ *
+ * Scans for markdown links pointing to `/connect/claim?claim=...` URLs and
+ * returns them as structured button data, stripping the link syntax
+ * from the content so platforms can render native buttons instead.
+ */
+
+const SETTINGS_LINK_RE =
+  /\[([^\]]+)\]\((https?:\/\/[^)]*\/(?:connect\/claim|agent)\?claim=[^)]+)\)/g;
+
+/**
+ * Returns true when the URL points to a loopback address that
+ * Telegram (and other platforms) reject for inline keyboard buttons.
+ */
+function isLocalhostUrl(url: string): boolean {
+  try {
+    const u = new URL(url);
+    return (
+      u.hostname === "localhost" ||
+      u.hostname === "127.0.0.1" ||
+      u.hostname === "::1"
+    );
+  } catch {
+    return true;
+  }
+}
+
+export interface LinkButton {
+  text: string;
+  url: string;
+}
+
+/**
+ * Extract `[label](settingsUrl)` markdown links and return them as
+ * structured buttons.  The link syntax is replaced with just the label
+ * text so the surrounding prose still reads naturally.
+ */
+export function extractSettingsLinkButtons(content: string): {
+  processedContent: string;
+  linkButtons: LinkButton[];
+} {
+  const linkButtons: LinkButton[] = [];
+
+  const processedContent = content.replace(
+    SETTINGS_LINK_RE,
+    (_match, text: string, url: string) => {
+      if (!isLocalhostUrl(url)) {
+        linkButtons.push({ text, url });
+      }
+      // Replace the markdown link with just the label text
+      return text;
+    }
+  );
+
+  return { processedContent, linkButtons };
+}

package/src/platform/renderer-utils.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared renderer and markdown utilities.
+ * Extracts common helpers duplicated across Telegram, WhatsApp, and Slack converters/renderers.
+ */
+
+/**
+ * Chunk a long message into smaller parts, breaking at natural boundaries.
+ */
+export function chunkMessage(text: string, maxLength: number): string[] {
+  if (text.length <= maxLength) {
+    return [text];
+  }
+
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLength) {
+      chunks.push(remaining);
+      break;
+    }
+
+    let breakPoint = maxLength;
+
+    const newlineIndex = remaining.lastIndexOf("\n", maxLength);
+    if (newlineIndex > maxLength * 0.5) {
+      breakPoint = newlineIndex + 1;
+    } else {
+      const spaceIndex = remaining.lastIndexOf(" ", maxLength);
+      if (spaceIndex > maxLength * 0.5) {
+        breakPoint = spaceIndex + 1;
+      }
+    }
+
+    chunks.push(remaining.substring(0, breakPoint).trim());
+    remaining = remaining.substring(breakPoint).trim();
+  }
+
+  return chunks.filter((c) => c.length > 0);
+}
+
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/platform/response-renderer.ts

@@ -0,0 +1,84 @@
+/**
+ * Response renderer interface for platform-specific message rendering.
+ * Each platform implements this interface to handle thread responses
+ * in a platform-appropriate way (streaming, buffering, formatting).
+ */
+
+import type { ThreadResponsePayload } from "../infrastructure/queue/types";
+
+/**
+ * Interface for rendering thread responses to a specific platform.
+ * Implementations handle platform-specific concerns like:
+ * - Streaming vs buffered messages
+ * - Rich formatting (Slack blocks) vs plain text (WhatsApp)
+ * - Status indicators (thread status vs typing)
+ */
+export interface ResponseRenderer {
+  /**
+   * Handle streaming delta content.
+   * Platforms that support streaming (Slack) update messages in real-time.
+   * Platforms without streaming (WhatsApp) buffer content for later delivery.
+   *
+   * @param payload - The thread response payload containing delta content
+   * @param sessionKey - Unique key for this response session (userId:messageId)
+   * @returns Message ID/timestamp if a message was created/updated, null otherwise
+   */
+  handleDelta?(
+    payload: ThreadResponsePayload,
+    sessionKey: string
+  ): Promise<string | null>;
+
+  /**
+   * Handle completion of response processing.
+   * Called when all content has been processed (processedMessageIds is set).
+   * Should finalize any streams, send buffered content, clear status indicators.
+   *
+   * @param payload - The thread response payload
+   * @param sessionKey - Unique key for this response session
+   */
+  handleCompletion(
+    payload: ThreadResponsePayload,
+    sessionKey: string
+  ): Promise<void>;
+
+  /**
+   * Handle error response.
+   * Display error in platform-appropriate format.
+   *
+   * @param payload - The thread response payload containing error
+   * @param sessionKey - Unique key for this response session
+   */
+  handleError(
+    payload: ThreadResponsePayload,
+    sessionKey: string
+  ): Promise<void>;
+
+  /**
+   * Handle status updates (heartbeat with elapsed time).
+   * Used to show "is running...", progress indicators, etc.
+   *
+   * @param payload - The thread response payload with statusUpdate field
+   */
+  handleStatusUpdate?(payload: ThreadResponsePayload): Promise<void>;
+
+  /**
+   * Handle ephemeral messages (visible only to specific user).
+   * Used for OAuth/auth flows, temporary notifications.
+   *
+   * @param payload - The thread response payload with ephemeral content
+   */
+  handleEphemeral?(payload: ThreadResponsePayload): Promise<void>;
+
+  /**
+   * Stop any active streams for a conversation.
+   * Called when an interaction is created to prevent messages appearing
+   * after the interaction prompt.
+   *
+   * @param userId - User ID
+   * @param conversationId - Conversation identifier
+   */
+  stopStreamForConversation?(
+    userId: string,
+    conversationId: string
+  ): Promise<void>;
+}

package/src/platform/unified-thread-consumer.ts

@@ -0,0 +1,187 @@
+/**
+ * Unified thread response consumer.
+ * Single consumer that routes responses to platform-specific renderers
+ * via the PlatformRegistry, eliminating duplicate queue filtering logic.
+ */
+
+import { createLogger } from "@lobu/core";
+import type { ChatResponseBridge } from "../connections/chat-response-bridge";
+import type {
+  IMessageQueue,
+  QueueJob,
+  ThreadResponsePayload,
+} from "../infrastructure/queue";
+import type { PlatformRegistry } from "../platform";
+import type { ResponseRenderer } from "./response-renderer";
+
+const logger = createLogger("unified-thread-consumer");
+
+/**
+ * Unified consumer for thread_response queue.
+ * Routes responses to the appropriate platform adapter based on payload.platform field.
+ */
+export class UnifiedThreadResponseConsumer {
+  private isRunning = false;
+
+  private chatResponseBridge?: ChatResponseBridge;
+
+  constructor(
+    private queue: IMessageQueue,
+    private platformRegistry: PlatformRegistry
+  ) {}
+
+  setChatResponseBridge(bridge: ChatResponseBridge): void {
+    this.chatResponseBridge = bridge;
+  }
+
+  /**
+   * Start consuming thread_response messages.
+   */
+  async start(): Promise<void> {
+    try {
+      await this.queue.start();
+      await this.queue.createQueue("thread_response");
+
+      await this.queue.work(
+        "thread_response",
+        this.handleThreadResponse.bind(this)
+      );
+
+      this.isRunning = true;
+      logger.debug("Unified thread response consumer started");
+    } catch (error) {
+      logger.error("Failed to start unified thread response consumer:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Stop the consumer.
+   */
+  async stop(): Promise<void> {
+    this.isRunning = false;
+    await this.queue.stop();
+    logger.info("Unified thread response consumer stopped");
+  }
+
+  /**
+   * Handle a thread response job by routing to the appropriate platform renderer.
+   */
+  private async handleThreadResponse(
+    job: QueueJob<ThreadResponsePayload>
+  ): Promise<void> {
+    const data = job.data;
+
+    if (!data || !data.messageId) {
+      logger.error(`Invalid thread response data: ${JSON.stringify(data)}`);
+      return;
+    }
+
+    // Check if this response belongs to a Chat SDK connection — handle before legacy routing
+    if (this.chatResponseBridge?.canHandle(data)) {
+      const sessionKey = `${data.userId}:${data.originalMessageId || data.messageId}`;
+      try {
+        await this.routeToRenderer(this.chatResponseBridge, data, sessionKey);
+      } catch (error) {
+        logger.error("Error processing Chat SDK response:", error);
+        throw error;
+      }
+      return;
+    }
+
+    // Use platform field, fall back to teamId
+    const platformName = data.platform || data.teamId;
+    if (!platformName) {
+      logger.warn(
+        `Missing platform in thread response for message ${data.messageId}, skipping`
+      );
+      return;
+    }
+
+    // Get platform adapter from registry
+    const platform = this.platformRegistry.get(platformName);
+    if (!platform) {
+      logger.warn(
+        `No platform adapter registered for: ${platformName}, skipping message ${data.messageId}`
+      );
+      return;
+    }
+
+    // Get renderer from platform
+    const renderer = platform.getResponseRenderer?.();
+    if (!renderer) {
+      logger.warn(
+        `Platform ${platformName} does not provide a response renderer, skipping message ${data.messageId}`
+      );
+      return;
+    }
+
+    // Create session key for tracking
+    const sessionKey = `${data.userId}:${data.originalMessageId || data.messageId}`;
+
+    logger.info(
+      `Processing thread response for platform=${platformName}, message=${data.messageId}, session=${sessionKey}`
+    );
+
+    try {
+      await this.routeToRenderer(renderer, data, sessionKey);
+    } catch (error) {
+      logger.error(
+        `Error processing thread response for ${platformName}:`,
+        error
+      );
+      // Let queue handle retry logic
+      throw error;
+    }
+  }
+
+  /**
+   * Route the payload to the appropriate renderer method.
+   */
+  private async routeToRenderer(
+    renderer: ResponseRenderer,
+    data: ThreadResponsePayload,
+    sessionKey: string
+  ): Promise<void> {
+    // Handle ephemeral messages (OAuth/auth flows)
+    if (data.ephemeral && data.content && renderer.handleEphemeral) {
+      await renderer.handleEphemeral(data);
+      return;
+    }
+
+    // Handle status updates (heartbeat with elapsed time)
+    if (data.statusUpdate && renderer.handleStatusUpdate) {
+      await renderer.handleStatusUpdate(data);
+      return;
+    }
+
+    // Handle streaming delta
+    if (data.delta && renderer.handleDelta) {
+      await renderer.handleDelta(data, sessionKey);
+      // Early return if no error - delta processing is complete
+      if (!data.error) {
+        return;
+      }
+    }
+
+    // Handle error
+    if (data.error) {
+      await renderer.handleError(data, sessionKey);
+      // Also complete session on error
+      await renderer.handleCompletion(data, sessionKey);
+      return;
+    }
+
+    // Handle completion
+    if (data.processedMessageIds?.length) {
+      await renderer.handleCompletion(data, sessionKey);
+    }
+  }
+
+  /**
+   * Check if consumer is healthy.
+   */
+  isHealthy(): boolean {
+    return this.isRunning;
+  }
+}