@lobu/core 3.0.12 → 3.0.13

package/src/utils/retry.ts

@@ -0,0 +1,91 @@
+import { createLogger } from "../logger";
+
+const logger = createLogger("retry");
+
+export interface RetryOptions {
+  maxRetries?: number;
+  baseDelay?: number;
+  strategy?: "exponential" | "linear";
+  jitter?: boolean;
+  onRetry?: (attempt: number, error: Error) => void;
+}
+
+/**
+ * Retry a function with configurable backoff strategy
+ *
+ * @param fn - The async function to retry
+ * @param options - Retry configuration
+ * @returns The result of the function
+ * @throws The last error if all retries fail
+ *
+ * @example
+ * ```typescript
+ * // Exponential backoff (default)
+ * const result = await retryWithBackoff(
+ *   () => fetch('https://api.example.com'),
+ *   { maxRetries: 3, baseDelay: 1000 }
+ * );
+ *
+ * // Linear backoff with jitter
+ * const result = await retryWithBackoff(
+ *   () => createDeployment(),
+ *   {
+ *     maxRetries: 3,
+ *     strategy: 'linear',
+ *     jitter: true,
+ *     baseDelay: 2000,
+ *     onRetry: (attempt, error) => {
+ *       logger.warn(`Attempt ${attempt} failed: ${error.message}`);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const {
+    maxRetries = 3,
+    baseDelay = 1000,
+    strategy = "exponential",
+    jitter = false,
+    onRetry,
+  } = options;
+
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error as Error;
+
+      if (attempt < maxRetries) {
+        // Calculate delay based on strategy
+        const delay =
+          strategy === "exponential"
+            ? baseDelay * 2 ** attempt
+            : baseDelay * (attempt + 1);
+
+        // Add jitter if requested (0-1000ms random)
+        const jitterMs = jitter ? Math.random() * 1000 : 0;
+        const finalDelay = delay + jitterMs;
+
+        // Notify caller of retry
+        if (onRetry) {
+          onRetry(attempt + 1, lastError);
+        } else {
+          logger.warn(
+            `Retry attempt ${attempt + 1}/${maxRetries} after ${Math.round(finalDelay)}ms`,
+            { error: lastError.message }
+          );
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, finalDelay));
+      }
+    }
+  }
+
+  throw lastError;
+}

package/src/utils/sanitize.ts

@@ -0,0 +1,127 @@
+/**
+ * Sanitize filename to prevent path traversal attacks
+ * Removes directory separators and dangerous characters
+ *
+ * @param filename - The filename to sanitize
+ * @param maxLength - Maximum filename length (default: 255)
+ * @returns Safe filename
+ *
+ * @example
+ * ```typescript
+ * sanitizeFilename("../../etc/passwd") // "etc_passwd"
+ * sanitizeFilename("file<>|name.txt") // "file___name.txt"
+ * ```
+ */
+export function sanitizeFilename(
+  filename: string,
+  maxLength: number = 255
+): string {
+  // Remove any directory path components
+  const basename = filename.replace(/^.*[\\/]/, "");
+
+  // Remove null bytes and other dangerous characters
+  const sanitized = basename.replace(/[^\w\s.-]/g, "_");
+
+  // Prevent hidden files and parent directory references
+  const safe = sanitized.replace(/^\.+/, "").replace(/\.{2,}/g, ".");
+
+  // Ensure filename is not empty after sanitization
+  if (!safe || safe.length === 0) {
+    return "unnamed_file";
+  }
+
+  // Limit filename length
+  return safe.length > maxLength ? safe.substring(0, maxLength) : safe;
+}
+
+/**
+ * Sanitize conversation ID for filesystem usage
+ * Removes any characters that aren't safe for directory names
+ *
+ * @param conversationId - The conversation ID to sanitize
+ * @returns Safe conversation ID
+ *
+ * @example
+ * ```typescript
+ * sanitizeConversationId("1756766056.836119") // "1756766056.836119"
+ * sanitizeConversationId("thread/123/../456") // "thread_123___456"
+ * ```
+ */
+export function sanitizeConversationId(conversationId: string): string {
+  return conversationId.replace(/[^a-zA-Z0-9.-]/g, "_");
+}
+
+/**
+ * Sanitize sensitive data from objects before logging
+ * Redacts API keys, tokens, and other credentials
+ *
+ * @param obj - Object to sanitize
+ * @param sensitiveKeys - Additional sensitive key names to redact
+ * @returns Sanitized object safe for logging
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   apiKey: "secret-key-123",
+ *   timeout: 5000,
+ *   env: { TOKEN: "bearer-xyz" }
+ * };
+ *
+ * sanitizeForLogging(config)
+ * // {
+ * //   apiKey: "[REDACTED:14]",
+ * //   timeout: 5000,
+ * //   env: { TOKEN: "[REDACTED:10]" }
+ * // }
+ * ```
+ */
+export function sanitizeForLogging(
+  obj: any,
+  additionalSensitiveKeys: string[] = []
+): any {
+  if (!obj || typeof obj !== "object") {
+    return obj;
+  }
+
+  const defaultSensitiveKeys = [
+    "anthropic_api_key",
+    "api_key",
+    "apiKey",
+    "token",
+    "password",
+    "secret",
+    "authorization",
+    "bearer",
+    "credentials",
+    "privateKey",
+    "private_key",
+  ];
+
+  const sensitiveKeys = [...defaultSensitiveKeys, ...additionalSensitiveKeys];
+
+  const sanitized = Array.isArray(obj) ? [...obj] : { ...obj };
+
+  for (const key in sanitized) {
+    const lowerKey = key.toLowerCase();
+    const isSensitive = sensitiveKeys.some((k) => lowerKey.includes(k));
+
+    if (isSensitive && typeof sanitized[key] === "string") {
+      // Redact but show length for debugging
+      sanitized[key] = `[REDACTED:${sanitized[key].length}]`;
+    } else if (key === "env" && typeof sanitized[key] === "object") {
+      // Recursively sanitize env object
+      sanitized[key] = sanitizeForLogging(
+        sanitized[key],
+        additionalSensitiveKeys
+      );
+    } else if (typeof sanitized[key] === "object") {
+      // Recursively sanitize nested objects
+      sanitized[key] = sanitizeForLogging(
+        sanitized[key],
+        additionalSensitiveKeys
+      );
+    }
+  }
+
+  return sanitized;
+}

package/src/worker/auth.ts

@@ -0,0 +1,100 @@
+import { createLogger } from "../logger";
+import { decrypt, encrypt } from "../utils/encryption";
+
+const logger = createLogger("worker-auth");
+
+/**
+ * Worker authentication using encrypted conversation ID
+ * Token format: encrypted(userId:conversationId:deploymentName:timestamp)
+ */
+
+export interface WorkerTokenData {
+  userId: string;
+  conversationId: string;
+  channelId: string;
+  teamId?: string; // Optional - not all platforms have teams
+  agentId?: string; // Space ID for multi-tenant isolation
+  connectionId?: string;
+  deploymentName: string;
+  timestamp: number;
+  platform?: string;
+  sessionKey?: string;
+  traceId?: string; // Trace ID for end-to-end observability
+}
+
+/**
+ * Generate a worker authentication token by encrypting thread metadata
+ */
+export function generateWorkerToken(
+  userId: string,
+  conversationId: string,
+  deploymentName: string,
+  options: {
+    channelId: string;
+    teamId?: string;
+    agentId?: string;
+    connectionId?: string;
+    platform?: string;
+    sessionKey?: string;
+    traceId?: string; // Trace ID for end-to-end observability
+  }
+): string {
+  // Validate required fields
+  if (!options.channelId) {
+    throw new Error("channelId is required for worker token generation");
+  }
+
+  const timestamp = Date.now();
+  const payload: WorkerTokenData = {
+    userId,
+    conversationId,
+    channelId: options.channelId,
+    teamId: options.teamId, // Can be undefined - that's ok
+    agentId: options.agentId, // Space ID for multi-tenant credential lookup
+    connectionId: options.connectionId,
+    deploymentName,
+    timestamp,
+    platform: options.platform,
+    sessionKey: options.sessionKey,
+    traceId: options.traceId, // Trace ID for observability
+  };
+
+  // Encrypt the payload
+  const encrypted = encrypt(JSON.stringify(payload));
+  return encrypted;
+}
+
+/**
+ * Verify and decrypt a worker authentication token
+ */
+export function verifyWorkerToken(token: string): WorkerTokenData | null {
+  try {
+    // Decrypt the token
+    const decrypted = decrypt(token);
+    const data = JSON.parse(decrypted) as WorkerTokenData;
+
+    if (
+      !data.conversationId ||
+      !data.userId ||
+      !data.deploymentName ||
+      !data.timestamp
+    ) {
+      logger.error("Worker token rejected: missing required fields");
+      return null;
+    }
+
+    // Check token expiration (default 24h)
+    const parsedTtl = parseInt(process.env.WORKER_TOKEN_TTL_MS ?? "", 10);
+    const ttl =
+      !Number.isNaN(parsedTtl) && parsedTtl > 0 ? parsedTtl : 86400000;
+    if (Date.now() - data.timestamp > ttl) {
+      logger.error("Worker token rejected: expired");
+      return null;
+    }
+
+    return data;
+  } catch (error) {
+    logger.error("Error verifying token:", error);
+    return null;
+  }
+}

package/src/worker/transport.ts

@@ -0,0 +1,107 @@
+/**
+ * Worker Transport Interface
+ * Defines how workers communicate with the gateway (platform-agnostic)
+ *
+ * This abstraction allows different transport implementations:
+ * - HTTP (current implementation)
+ * - WebSocket (for real-time bidirectional communication)
+ * - gRPC (for high-performance scenarios)
+ * - Message Queue (for asynchronous processing)
+ */
+
+/**
+ * Transport interface for worker-to-gateway communication
+ */
+export interface WorkerTransport {
+  /**
+   * Set the job ID for this worker session
+   * Used to correlate responses with the originating request
+   */
+  setJobId(jobId: string): void;
+
+  /**
+   * Set module-specific data to be included in responses
+   * Allows modules to attach metadata to worker responses
+   */
+  setModuleData(moduleData: Record<string, unknown>): void;
+
+  /**
+   * Send a streaming delta to the gateway
+   *
+   * @param delta - The content delta to send
+   * @param isFullReplacement - If true, replaces entire content; if false, appends
+   * @param isFinal - If true, indicates this is the final delta
+   */
+  sendStreamDelta(
+    delta: string,
+    isFullReplacement?: boolean,
+    isFinal?: boolean
+  ): Promise<void>;
+
+  /**
+   * Signal that the worker has completed processing
+   * Optionally includes a final delta
+   *
+   * @param finalDelta - Optional final content delta
+   */
+  signalDone(finalDelta?: string): Promise<void>;
+
+  /**
+   * Signal successful completion without additional content
+   */
+  signalCompletion(): Promise<void>;
+
+  /**
+   * Signal that an error occurred during processing
+   *
+   * @param error - The error that occurred
+   */
+  signalError(error: Error, errorCode?: string): Promise<void>;
+
+  /**
+   * Send a status update to the gateway
+   * Used for long-running operations to show progress
+   *
+   * @param elapsedSeconds - Time elapsed since operation started
+   * @param state - Current state description (e.g., "processing", "waiting for API")
+   */
+  sendStatusUpdate(elapsedSeconds: number, state: string): Promise<void>;
+}
+
+/**
+ * Configuration for creating a worker transport
+ */
+export interface WorkerTransportConfig {
+  /** Gateway URL for sending responses */
+  gatewayUrl: string;
+
+  /** Authentication token for worker */
+  workerToken: string;
+
+  /** User ID who initiated the request */
+  userId: string;
+
+  /** Channel/conversation ID */
+  channelId: string;
+
+  /** Conversation ID for organizing messages */
+  conversationId: string;
+
+  /** Original message timestamp/ID */
+  originalMessageTs: string;
+
+  /** Bot's response message timestamp/ID (if exists) */
+  botResponseTs?: string;
+
+  /** Team/workspace ID (required for all platforms) */
+  teamId: string;
+
+  /** Platform identifier (slack, whatsapp, api, etc.) */
+  platform?: string;
+
+  /** Platform-specific metadata needed for response routing */
+  platformMetadata?: Record<string, unknown>;
+
+  /** IDs of messages already processed (for deduplication) */
+  processedMessageIds?: string[];
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noEmit": false,
+    "moduleResolution": "node",
+    "module": "CommonJS",
+    "target": "ES2020",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "composite": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}