insforge 1.2.10 → 1.3.0

package/backend/src/infra/realtime/realtime.manager.ts

@@ -0,0 +1,246 @@
+import type { Client } from 'pg';
+import { SocketManager } from '@/infra/socket/socket.manager.js';
+import { WebhookSender } from './webhook-sender.js';
+import { DatabaseManager } from '@/infra/database/database.manager.js';
+import { RealtimeChannelService } from '@/services/realtime/realtime-channel.service.js';
+import { RealtimeMessageService } from '@/services/realtime/realtime-message.service.js';
+import logger from '@/utils/logger.js';
+import type { RealtimeMessage, RealtimeChannel, WebhookMessage } from '@insforge/shared-schemas';
+import type { DeliveryResult } from '@/types/realtime.js';
+
+/**
+ * RealtimeManager - Listens to pg_notify and publishes messages to WebSocket/webhooks
+ *
+ * This is a singleton that:
+ * 1. Maintains a dedicated PostgreSQL connection for LISTEN
+ * 2. Receives notifications from realtime.publish() function
+ * 3. Publishes messages to WebSocket clients (via Socket.IO rooms)
+ * 4. Publishes messages to webhook URLs (via HTTP POST)
+ * 5. Updates message records with delivery statistics
+ */
+export class RealtimeManager {
+  private static instance: RealtimeManager;
+  private listenerClient: Client | null = null;
+  private isConnected = false;
+  private reconnectTimeout: NodeJS.Timeout | null = null;
+  private reconnectAttempts = 0;
+  private readonly maxReconnectAttempts = 10;
+  private readonly baseReconnectDelay = 5000;
+  private webhookSender: WebhookSender;
+
+  private constructor() {
+    this.webhookSender = new WebhookSender();
+  }
+
+  static getInstance(): RealtimeManager {
+    if (!RealtimeManager.instance) {
+      RealtimeManager.instance = new RealtimeManager();
+    }
+    return RealtimeManager.instance;
+  }
+
+  /**
+   * Initialize the realtime manager and start listening for pg_notify
+   */
+  async initialize(): Promise<void> {
+    if (this.isConnected) {
+      return;
+    }
+
+    // Create a dedicated client for LISTEN (cannot use pooled connections)
+    this.listenerClient = DatabaseManager.getInstance().createClient();
+
+    try {
+      await this.listenerClient.connect();
+      await this.listenerClient.query('LISTEN realtime_message');
+      this.isConnected = true;
+      this.reconnectAttempts = 0;
+
+      this.listenerClient.on('notification', (msg) => {
+        if (msg.channel === 'realtime_message' && msg.payload) {
+          void this.handlePGNotification(msg.payload);
+        }
+      });
+
+      this.listenerClient.on('error', (error) => {
+        logger.error('RealtimeManager connection error', { error: error.message });
+        this.handleDisconnect();
+      });
+
+      this.listenerClient.on('end', () => {
+        logger.warn('RealtimeManager connection ended');
+        this.handleDisconnect();
+      });
+
+      logger.info('RealtimeManager initialized and listening');
+    } catch (error) {
+      logger.error('Failed to initialize RealtimeManager', { error });
+      this.handleDisconnect();
+    }
+  }
+
+  /**
+   * Handle incoming pg_notify notification
+   * Payload is just the message_id (UUID string) to bypass 8KB limit
+   */
+  private async handlePGNotification(messageId: string): Promise<void> {
+    try {
+      // 1. Fetch message and channel in parallel
+      // channelId is guaranteed non-null for fresh messages (publish/insertMessage validate channel)
+      const message = await RealtimeMessageService.getInstance().getById(messageId);
+
+      if (!message || !message.channelId) {
+        logger.warn('Message not found or invalid for realtime notification', { messageId });
+        return;
+      }
+
+      // 2. Look up channel configuration (for enabled check and webhook URLs)
+      const channel = await RealtimeChannelService.getInstance().getById(message.channelId);
+
+      if (!channel?.enabled) {
+        logger.debug('Channel not found or disabled, skipping', { channelId: message.channelId });
+        return;
+      }
+
+      // 3. Publish to WebSocket and/or Webhooks
+      const result = await this.publishMessage(message, channel);
+
+      // 4. Update message record with delivery stats
+      await RealtimeMessageService.getInstance().updateDeliveryStats(messageId, result);
+
+      logger.debug('Realtime message published', {
+        messageId,
+        channelName: message.channelName,
+        eventName: message.eventName,
+        ...result,
+      });
+    } catch (error) {
+      logger.error('Failed to publish realtime message', { error, messageId });
+    }
+  }
+
+  /**
+   * Publish message to WebSocket clients and webhook URLs
+   */
+  private async publishMessage(
+    message: RealtimeMessage,
+    channel: RealtimeChannel
+  ): Promise<DeliveryResult> {
+    const result: DeliveryResult = {
+      wsAudienceCount: 0,
+      whAudienceCount: 0,
+      whDeliveredCount: 0,
+    };
+
+    // Publish to WebSocket clients
+    result.wsAudienceCount = this.publishToWebSocket(message);
+
+    // Publish to Webhook URLs if configured
+    if (channel.webhookUrls && channel.webhookUrls.length > 0) {
+      const webhookPayload: WebhookMessage = {
+        messageId: message.id,
+        channel: message.channelName,
+        eventName: message.eventName,
+        payload: message.payload,
+      };
+      const whResult = await this.publishToWebhooks(channel.webhookUrls, webhookPayload);
+      result.whAudienceCount = whResult.audienceCount;
+      result.whDeliveredCount = whResult.deliveredCount;
+    }
+
+    return result;
+  }
+
+  /**
+   * Publish message to WebSocket clients subscribed to the channel
+   * Returns the number of clients in the room (audience count)
+   */
+  private publishToWebSocket(message: RealtimeMessage): number {
+    const socketManager = SocketManager.getInstance();
+    const roomName = `realtime:${message.channelName}`;
+
+    const audienceCount = socketManager.getRoomSize(roomName);
+
+    if (audienceCount > 0) {
+      socketManager.broadcastToRoom(
+        roomName,
+        message.eventName,
+        message.payload,
+        message.senderType,
+        message.senderId ?? undefined,
+        message.id
+      );
+    }
+
+    return audienceCount;
+  }
+
+  /**
+   * Publish message to all configured webhook URLs
+   */
+  private async publishToWebhooks(
+    urls: string[],
+    message: WebhookMessage
+  ): Promise<{ audienceCount: number; deliveredCount: number }> {
+    const audienceCount = urls.length;
+    const results = await this.webhookSender.sendToAll(urls, message);
+    const deliveredCount = results.filter((r) => r.success).length;
+
+    return { audienceCount, deliveredCount };
+  }
+
+  /**
+   * Handle disconnection and attempt reconnection
+   */
+  private handleDisconnect(): void {
+    this.isConnected = false;
+
+    if (this.listenerClient) {
+      this.listenerClient.removeAllListeners();
+      this.listenerClient = null;
+    }
+
+    // Reconnect with exponential backoff
+    if (this.reconnectAttempts < this.maxReconnectAttempts) {
+      const delay = this.baseReconnectDelay * Math.pow(2, this.reconnectAttempts);
+      this.reconnectAttempts++;
+
+      if (!this.reconnectTimeout) {
+        this.reconnectTimeout = setTimeout(() => {
+          this.reconnectTimeout = null;
+          logger.info(
+            `Attempting to reconnect RealtimeManager (attempt ${this.reconnectAttempts})...`
+          );
+          void this.initialize();
+        }, delay);
+      }
+    } else {
+      logger.error('RealtimeManager max reconnect attempts reached');
+    }
+  }
+
+  /**
+   * Close the realtime manager connection
+   */
+  async close(): Promise<void> {
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+
+    if (this.listenerClient) {
+      this.listenerClient.removeAllListeners();
+      await this.listenerClient.end();
+      this.listenerClient = null;
+      this.isConnected = false;
+      logger.info('RealtimeManager closed');
+    }
+  }
+
+  /**
+   * Check if the manager is connected and healthy
+   */
+  isHealthy(): boolean {
+    return this.isConnected;
+  }
+}

package/backend/src/infra/realtime/webhook-sender.ts

@@ -0,0 +1,82 @@
+import axios, { AxiosError } from 'axios';
+import logger from '@/utils/logger.js';
+import type { WebhookMessage } from '@insforge/shared-schemas';
+
+export interface WebhookResult {
+  url: string;
+  success: boolean;
+  statusCode?: number;
+  error?: string;
+}
+
+/**
+ * WebhookSender - Handles HTTP delivery of realtime messages to webhook endpoints
+ */
+export class WebhookSender {
+  private readonly timeout = 10000; // 10 seconds
+  private readonly maxRetries = 2;
+
+  /**
+   * Send message to all webhook URLs in parallel
+   */
+  async sendToAll(urls: string[], message: WebhookMessage): Promise<WebhookResult[]> {
+    const promises = urls.map((url) => this.send(url, message));
+    return Promise.all(promises);
+  }
+
+  /**
+   * Send message to a single webhook URL with retry logic
+   */
+  private async send(url: string, message: WebhookMessage): Promise<WebhookResult> {
+    let lastError: string | undefined;
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const response = await axios.post(url, message.payload, {
+          timeout: this.timeout,
+          headers: {
+            'Content-Type': 'application/json',
+            'X-InsForge-Event': message.eventName,
+            'X-InsForge-Channel': message.channel,
+            'X-InsForge-Message-Id': message.messageId,
+          },
+        });
+
+        return {
+          url,
+          success: response.status >= 200 && response.status < 300,
+          statusCode: response.status,
+        };
+      } catch (error) {
+        const axiosError = error as AxiosError;
+        lastError = axiosError.message;
+
+        if (axiosError.response) {
+          // Server responded with error status - don't retry
+          return {
+            url,
+            success: false,
+            statusCode: axiosError.response.status,
+            error: `HTTP ${axiosError.response.status}`,
+          };
+        }
+
+        // Network error - retry with backoff
+        if (attempt < this.maxRetries) {
+          await this.delay(1000 * (attempt + 1)); // 1s, 2s
+        }
+      }
+    }
+    logger.warn('Webhook delivery failed after retries', { url, error: lastError });
+
+    return {
+      url,
+      success: false,
+      error: lastError,
+    };
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/backend/src/infra/security/token.manager.ts

@@ -1,125 +1,219 @@
-import jwt from 'jsonwebtoken';
-import { createRemoteJWKSet, JWTPayload, jwtVerify } from 'jose';
-import { AppError } from '@/api/middlewares/error.js';
-import { ERROR_CODES, NEXT_ACTION } from '@/types/error-constants.js';
-import type { TokenPayloadSchema } from '@insforge/shared-schemas';
-
-const JWT_SECRET = process.env.JWT_SECRET ?? '';
-const JWT_EXPIRES_IN = '7d';
-
-/**
- * Create JWKS instance with caching and timeout configuration
- * The instance will automatically cache keys and handle refetching
- */
-const cloudApiHost = process.env.CLOUD_API_HOST || 'https://api.insforge.dev';
-const JWKS = createRemoteJWKSet(new URL(`${cloudApiHost}/.well-known/jwks.json`), {
-  timeoutDuration: 10000, // 10 second timeout for HTTP requests
-  cooldownDuration: 30000, // 30 seconds cooldown after successful fetch
-  cacheMaxAge: 600000, // Maximum 10 minutes between refetches
-});
-
-/**
- * TokenManager - Handles JWT token operations
- * Infrastructure layer for token generation and verification
- */
-export class TokenManager {
-  private static instance: TokenManager;
-
-  private constructor() {
-    if (!process.env.JWT_SECRET) {
-      throw new Error('JWT_SECRET environment variable is required');
-    }
-  }
-
-  public static getInstance(): TokenManager {
-    if (!TokenManager.instance) {
-      TokenManager.instance = new TokenManager();
-    }
-    return TokenManager.instance;
-  }
-
-  /**
-   * Generate JWT token for users and admins
-   */
-  generateToken(payload: TokenPayloadSchema): string {
-    return jwt.sign(payload, JWT_SECRET, {
-      algorithm: 'HS256',
-      expiresIn: JWT_EXPIRES_IN,
-    });
-  }
-
-  /**
-   * Generate anonymous JWT token (never expires)
-   */
-  generateAnonToken(): string {
-    const payload = {
-      sub: '12345678-1234-5678-90ab-cdef12345678',
-      email: 'anon@insforge.com',
-      role: 'anon',
-    };
-    return jwt.sign(payload, JWT_SECRET, {
-      algorithm: 'HS256',
-      // No expiresIn means token never expires
-    });
-  }
-
-  /**
-   * Verify JWT token
-   */
-  verifyToken(token: string): TokenPayloadSchema {
-    try {
-      const decoded = jwt.verify(token, JWT_SECRET) as TokenPayloadSchema;
-      return {
-        sub: decoded.sub,
-        email: decoded.email,
-        role: decoded.role || 'authenticated',
-      };
-    } catch {
-      throw new AppError('Invalid token', 401, ERROR_CODES.AUTH_UNAUTHORIZED);
-    }
-  }
-
-  /**
-   * Verify cloud backend JWT token
-   * Validates JWT tokens from api.insforge.dev using JWKS
-   */
-  async verifyCloudToken(token: string): Promise<{ projectId: string; payload: JWTPayload }> {
-    try {
-      // JWKS handles caching internally, no need to manage it manually
-      const { payload } = await jwtVerify(token, JWKS, {
-        algorithms: ['RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512'],
-      });
-
-      // Verify project_id matches if configured
-      const tokenProjectId = payload['projectId'] as string;
-      const expectedProjectId = process.env.PROJECT_ID;
-
-      if (expectedProjectId && tokenProjectId !== expectedProjectId) {
-        throw new AppError(
-          'Project ID mismatch',
-          403,
-          ERROR_CODES.AUTH_UNAUTHORIZED,
-          NEXT_ACTION.CHECK_TOKEN
-        );
-      }
-
-      return {
-        projectId: tokenProjectId || expectedProjectId || 'local',
-        payload,
-      };
-    } catch (error) {
-      // Re-throw AppError as-is
-      if (error instanceof AppError) {
-        throw error;
-      }
-
-      // Wrap other JWT errors
-      throw new AppError(
-        `Invalid cloud authorization code: ${error instanceof Error ? error.message : 'Unknown error'}`,
-        401,
-        ERROR_CODES.AUTH_INVALID_CREDENTIALS,
-        NEXT_ACTION.CHECK_TOKEN
-      );
-    }
-  }
-}
+import jwt from 'jsonwebtoken';
+import crypto from 'crypto';
+import { createRemoteJWKSet, JWTPayload, jwtVerify } from 'jose';
+import { AppError } from '@/api/middlewares/error.js';
+import { ERROR_CODES, NEXT_ACTION } from '@/types/error-constants.js';
+import type { TokenPayloadSchema } from '@insforge/shared-schemas';
+
+const JWT_SECRET = process.env.JWT_SECRET ?? '';
+// TODO: Change access token expiration time to 15 min
+const JWT_EXPIRES_IN = '7d';
+const REFRESH_TOKEN_EXPIRES_IN = '7d';
+
+/**
+ * Refresh token payload interface
+ */
+export interface RefreshTokenPayload {
+  sub: string;
+  type: 'refresh';
+  iss: string;
+}
+
+/**
+ * Create JWKS instance with caching and timeout configuration
+ * The instance will automatically cache keys and handle refetching
+ */
+const cloudApiHost = process.env.CLOUD_API_HOST || 'https://api.insforge.dev';
+const JWKS = createRemoteJWKSet(new URL(`${cloudApiHost}/.well-known/jwks.json`), {
+  timeoutDuration: 10000, // 10 second timeout for HTTP requests
+  cooldownDuration: 30000, // 30 seconds cooldown after successful fetch
+  cacheMaxAge: 600000, // Maximum 10 minutes between refetches
+});
+
+/**
+ * TokenManager - Handles JWT token operations
+ * Infrastructure layer for token generation and verification
+ */
+export class TokenManager {
+  private static instance: TokenManager;
+
+  private constructor() {
+    if (!process.env.JWT_SECRET) {
+      throw new Error('JWT_SECRET environment variable is required');
+    }
+  }
+
+  public static getInstance(): TokenManager {
+    if (!TokenManager.instance) {
+      TokenManager.instance = new TokenManager();
+    }
+    return TokenManager.instance;
+  }
+
+  /**
+   * Generate JWT access token for users and admins
+   */
+  generateToken(payload: TokenPayloadSchema): string {
+    return jwt.sign(payload, JWT_SECRET, {
+      algorithm: 'HS256',
+      expiresIn: JWT_EXPIRES_IN,
+    });
+  }
+
+  /**
+   * Generate admin JWT token (never expires)
+   * Used for internal API key authenticated requests to PostgREST
+   */
+  generateAdminToken(): string {
+    const payload = {
+      sub: 'project-admin-with-api-key',
+      email: 'project-admin@email.com',
+      role: 'project_admin',
+    };
+    return jwt.sign(payload, JWT_SECRET, {
+      algorithm: 'HS256',
+      // No expiresIn means token never expires
+    });
+  }
+
+  /**
+   * Generate refresh token for secure session management
+   */
+  generateRefreshToken(userId: string): string {
+    const refreshPayload: RefreshTokenPayload = {
+      sub: userId,
+      type: 'refresh',
+      iss: 'insforge',
+    };
+    return jwt.sign(refreshPayload, JWT_SECRET, {
+      algorithm: 'HS256',
+      expiresIn: REFRESH_TOKEN_EXPIRES_IN,
+    });
+  }
+
+  /**
+   * Verify refresh token and return payload
+   * Ensures the token is a valid refresh token (not an access token)
+   */
+  verifyRefreshToken(token: string): RefreshTokenPayload {
+    try {
+      const decoded = jwt.verify(token, JWT_SECRET, {
+        algorithms: ['HS256'],
+        issuer: 'insforge',
+      }) as RefreshTokenPayload;
+
+      // Ensure this is a refresh token, not an access token
+      if (decoded.type !== 'refresh' || !decoded.sub) {
+        throw new AppError('Invalid refresh token type', 401, ERROR_CODES.AUTH_UNAUTHORIZED);
+      }
+
+      return decoded;
+    } catch (error) {
+      if (error instanceof AppError) {
+        throw error;
+      }
+      throw new AppError('Invalid or expired refresh token', 401, ERROR_CODES.AUTH_UNAUTHORIZED);
+    }
+  }
+
+  /**
+   * Generate anonymous JWT token (never expires)
+   */
+  generateAnonToken(): string {
+    const payload = {
+      sub: '12345678-1234-5678-90ab-cdef12345678',
+      email: 'anon@insforge.com',
+      role: 'anon',
+    };
+    return jwt.sign(payload, JWT_SECRET, {
+      algorithm: 'HS256',
+      // No expiresIn means token never expires
+    });
+  }
+
+  /**
+   * Verify JWT token
+   */
+  verifyToken(token: string): TokenPayloadSchema {
+    try {
+      const decoded = jwt.verify(token, JWT_SECRET) as TokenPayloadSchema;
+      return {
+        sub: decoded.sub,
+        email: decoded.email,
+        role: decoded.role || 'authenticated',
+      };
+    } catch {
+      throw new AppError('Invalid token', 401, ERROR_CODES.AUTH_UNAUTHORIZED);
+    }
+  }
+
+  /**
+   * Verify cloud backend JWT token
+   * Validates JWT tokens from api.insforge.dev using JWKS
+   */
+  async verifyCloudToken(token: string): Promise<{ projectId: string; payload: JWTPayload }> {
+    try {
+      // JWKS handles caching internally, no need to manage it manually
+      const { payload } = await jwtVerify(token, JWKS, {
+        algorithms: ['RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512'],
+      });
+
+      // Verify project_id matches if configured
+      const tokenProjectId = payload['projectId'] as string;
+      const expectedProjectId = process.env.PROJECT_ID;
+
+      if (expectedProjectId && tokenProjectId !== expectedProjectId) {
+        throw new AppError(
+          'Project ID mismatch',
+          403,
+          ERROR_CODES.AUTH_UNAUTHORIZED,
+          NEXT_ACTION.CHECK_TOKEN
+        );
+      }
+
+      return {
+        projectId: tokenProjectId || expectedProjectId || 'local',
+        payload,
+      };
+    } catch (error) {
+      // Re-throw AppError as-is
+      if (error instanceof AppError) {
+        throw error;
+      }
+
+      // Wrap other JWT errors
+      throw new AppError(
+        `Invalid cloud authorization code: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        401,
+        ERROR_CODES.AUTH_INVALID_CREDENTIALS,
+        NEXT_ACTION.CHECK_TOKEN
+      );
+    }
+  }
+
+  /**
+   * Generate CSRF token derived from refresh token using HMAC
+   */
+  generateCsrfToken(refreshToken: string): string {
+    return crypto
+      .createHmac('sha256', JWT_SECRET)
+      .update(refreshToken)
+      .digest('hex');
+  }
+
+  /**
+   * Verify CSRF token by re-computing from refresh token
+   * Uses timing-safe comparison to prevent timing attacks
+   */
+  verifyCsrfToken(csrfHeader: string | undefined, refreshToken: string): boolean {
+    if (!csrfHeader || !refreshToken) {
+      return false;
+    }
+    const expectedCsrf = this.generateCsrfToken(refreshToken);
+    try {
+      return crypto.timingSafeEqual(Buffer.from(csrfHeader), Buffer.from(expectedCsrf));
+    } catch {
+      return false;
+    }
+  }
+}