@lobu/core 3.0.5 → 3.0.7

package/src/utils/encryption.ts

@@ -0,0 +1,78 @@
+import * as crypto from "node:crypto";
+import { createLogger } from "../logger";
+
+const IV_LENGTH = 12; // 96-bit nonce for AES-GCM
+const logger = createLogger("encryption");
+
+/**
+ * Get encryption key from environment with validation
+ *
+ * IMPORTANT: The ENCRYPTION_KEY must be exactly 32 bytes (256 bits) for AES-256.
+ * Generate a secure key using: `openssl rand -base64 32` or `openssl rand -hex 32`
+ */
+function getEncryptionKey(): Buffer {
+  const key = process.env.ENCRYPTION_KEY || "";
+  if (!key) {
+    throw new Error(
+      "ENCRYPTION_KEY environment variable is required for secure operation"
+    );
+  }
+
+  // Try to decode as base64 first (most common format)
+  let keyBuffer: Buffer;
+  try {
+    keyBuffer = Buffer.from(key, "base64");
+    if (keyBuffer.length === 32) {
+      return keyBuffer;
+    }
+  } catch (err) {
+    logger.debug("ENCRYPTION_KEY is not valid base64, trying hex format", err);
+  }
+
+  // Try as hex (must be exactly 64 hex characters for 32 bytes)
+  if (/^[0-9a-fA-F]{64}$/.test(key)) {
+    keyBuffer = Buffer.from(key, "hex");
+    if (keyBuffer.length === 32) {
+      return keyBuffer;
+    }
+  }
+
+  throw new Error(
+    "ENCRYPTION_KEY must be a base64 or hex encoded 32-byte key. " +
+      "Generate a valid key with: openssl rand -base64 32"
+  );
+}
+
+/**
+ * Encrypt a string using AES-256-GCM
+ */
+export function encrypt(text: string): string {
+  const encryptionKey = getEncryptionKey();
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const cipher = crypto.createCipheriv("aes-256-gcm", encryptionKey, iv);
+  const encrypted = Buffer.concat([
+    cipher.update(text, "utf8"),
+    cipher.final(),
+  ]);
+  const tag = cipher.getAuthTag();
+  return `${iv.toString("hex")}:${tag.toString("hex")}:${encrypted.toString("hex")}`;
+}
+
+/**
+ * Decrypt a string encrypted with AES-256-GCM
+ */
+export function decrypt(text: string): string {
+  const encryptionKey = getEncryptionKey();
+  const parts = text.split(":");
+  if (parts.length !== 3) throw new Error("Invalid encrypted format");
+  const iv = Buffer.from(parts[0]!, "hex");
+  const tag = Buffer.from(parts[1]!, "hex");
+  const encryptedText = Buffer.from(parts[2]!, "hex");
+  const decipher = crypto.createDecipheriv("aes-256-gcm", encryptionKey, iv);
+  decipher.setAuthTag(tag);
+  const decrypted = Buffer.concat([
+    decipher.update(encryptedText),
+    decipher.final(),
+  ]);
+  return decrypted.toString("utf8");
+}

package/src/utils/env.ts

@@ -0,0 +1,50 @@
+import { ConfigError } from "../errors";
+
+/**
+ * Get required environment variable
+ * Throws ConfigError if not set
+ */
+export function getRequiredEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new ConfigError(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+/**
+ * Get optional environment variable with default
+ */
+export function getOptionalEnv(name: string, defaultValue: string): string {
+  return process.env[name] || defaultValue;
+}
+
+/**
+ * Get optional number environment variable with default
+ * Throws ConfigError if value is not a valid number
+ */
+export function getOptionalNumber(name: string, defaultValue: number): number {
+  const value = process.env[name];
+  if (!value) return defaultValue;
+  const parsed = parseInt(value, 10);
+  if (Number.isNaN(parsed)) {
+    throw new ConfigError(
+      `Invalid number for ${name}: ${value} (expected integer)`
+    );
+  }
+  return parsed;
+}
+
+/**
+ * Get optional boolean environment variable with default
+ * Accepts "true", "1", "yes" as truthy values
+ */
+export function getOptionalBoolean(
+  name: string,
+  defaultValue: boolean
+): boolean {
+  const value = process.env[name];
+  if (!value) return defaultValue;
+  const lower = value.toLowerCase();
+  return lower === "true" || lower === "1" || lower === "yes";
+}

package/src/utils/json.ts

@@ -0,0 +1,37 @@
+import { createLogger } from "../logger";
+
+const logger = createLogger("json-utils");
+
+/**
+ * Safely parse JSON string
+ * Returns null on parse failure instead of throwing
+ */
+export function safeJsonParse<T = unknown>(
+  data: string,
+  fallback: T | null = null
+): T | null {
+  try {
+    return JSON.parse(data) as T;
+  } catch (error) {
+    logger.debug("JSON parse failed", {
+      error: error instanceof Error ? error.message : String(error),
+      dataPreview: data.substring(0, 100),
+    });
+    return fallback;
+  }
+}
+
+/**
+ * Safely stringify value to JSON
+ * Returns null on stringify failure instead of throwing
+ */
+export function safeJsonStringify(value: unknown): string | null {
+  try {
+    return JSON.stringify(value);
+  } catch (error) {
+    logger.error("JSON stringify failed", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}

package/src/utils/lock.ts

@@ -0,0 +1,75 @@
+/**
+ * Async lock for serializing concurrent operations
+ * Prevents race conditions in async code by ensuring only one operation runs at a time
+ *
+ * @example
+ * ```typescript
+ * class StreamSession {
+ *   private streamLock = new AsyncLock();
+ *
+ *   async appendDelta(delta: string) {
+ *     return this.streamLock.acquire(() => this.appendDeltaUnsafe(delta));
+ *   }
+ *
+ *   private async appendDeltaUnsafe(delta: string) {
+ *     // Critical section - only one execution at a time
+ *   }
+ * }
+ * ```
+ */
+export class AsyncLock {
+  private lock: Promise<void> = Promise.resolve();
+  private lockContext: string;
+
+  constructor(context: string = "unknown") {
+    this.lockContext = context;
+  }
+
+  /**
+   * Acquire lock and execute function exclusively
+   *
+   * @param fn - The async function to execute with exclusive access
+   * @param timeoutMs - Maximum time to wait for lock acquisition (default: 30s)
+   * @returns The result of the function
+   * @throws Error if lock acquisition times out
+   */
+  async acquire<T>(
+    fn: () => Promise<T>,
+    timeoutMs: number = 30000
+  ): Promise<T> {
+    const currentLock = this.lock;
+    let releaseLock: (() => void) | undefined;
+
+    // Create new lock that will be released when fn completes
+    this.lock = new Promise<void>((resolve) => {
+      releaseLock = resolve;
+    });
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+    try {
+      // Wait for previous operation with timeout to prevent deadlock
+      const lockTimeout = new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(() => {
+          reject(
+            new Error(
+              `Lock acquisition timeout after ${timeoutMs}ms - possible deadlock in ${this.lockContext}`
+            )
+          );
+        }, timeoutMs);
+      });
+
+      await Promise.race([currentLock, lockTimeout]);
+
+      // Execute function with exclusive access
+      return await fn();
+    } finally {
+      // Clear the timeout to prevent leak
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+      // Always release lock, even on error
+      releaseLock?.();
+    }
+  }
+}

package/src/utils/mcp-tool-instructions.ts

@@ -0,0 +1,5 @@
+export interface McpToolDef {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+}

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"]
+}