insforge 0.3.2 → 1.2.10

package/backend/src/infra/database/migrations/015_create-auth-config-and-email-otp-tables.sql

@@ -0,0 +1,60 @@
+-- Migration: 015 - Create email OTP verification table and email auth configs
+-- This migration creates:
+-- 1. _email_otps: Stores one-time tokens for email verification purposes
+--    - Supports both short numeric codes (6 digits) for manual entry
+--    - Supports long cryptographic tokens (64 chars) for magic links
+--    - Uses dual hashing strategy:
+--      * NUMERIC_CODE (6 digits): Bcrypt hash (slow, defense against brute force)
+--      * LINK_TOKEN (64 hex chars): SHA-256 hash (fast, enables direct O(1) lookup)
+-- 2. _auth_configs: Stores email authentication configuration (single-row table)
+
+-- 1. Create email OTP verification table
+CREATE TABLE IF NOT EXISTS _email_otps (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  email TEXT NOT NULL,
+  purpose TEXT NOT NULL,
+  otp_hash TEXT NOT NULL, -- Hash of OTP: bcrypt for NUMERIC_CODE, SHA-256 for LINK_TOKEN
+  expires_at TIMESTAMPTZ NOT NULL,
+  consumed_at TIMESTAMPTZ,
+  attempts_count INTEGER DEFAULT 0 NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW(),
+  UNIQUE (email, purpose) -- Only one active token per email/purpose combination
+);
+
+-- Create indexes for better query performance
+CREATE INDEX IF NOT EXISTS idx_email_otps_email_purpose ON _email_otps(email, purpose);
+CREATE INDEX IF NOT EXISTS idx_email_otps_expires_at ON _email_otps(expires_at);
+CREATE INDEX IF NOT EXISTS idx_email_otps_otp_hash ON _email_otps(otp_hash); -- For direct LINK_TOKEN lookup
+
+-- Add trigger for updated_at
+DROP TRIGGER IF EXISTS update__email_otps_updated_at ON _email_otps;
+CREATE TRIGGER update__email_otps_updated_at
+BEFORE UPDATE ON _email_otps
+FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+-- 2. Create email authentication configuration table (single-row design)
+-- This table stores global email authentication settings for the project
+CREATE TABLE IF NOT EXISTS _auth_configs (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  require_email_verification BOOLEAN DEFAULT FALSE NOT NULL,
+  password_min_length INTEGER DEFAULT 6 NOT NULL CHECK (password_min_length >= 4 AND password_min_length <= 128),
+  require_number BOOLEAN DEFAULT FALSE NOT NULL,
+  require_lowercase BOOLEAN DEFAULT FALSE NOT NULL,
+  require_uppercase BOOLEAN DEFAULT FALSE NOT NULL,
+  require_special_char BOOLEAN DEFAULT FALSE NOT NULL,
+  verify_email_redirect_to TEXT, -- Custom URL to redirect after successful email verification (defaults to no redirect if NULL)
+  reset_password_redirect_to TEXT, -- Custom URL to redirect after successful password reset (defaults to no redirect if NULL)
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Ensure only one row exists (singleton pattern)
+-- This constraint prevents multiple configuration rows
+CREATE UNIQUE INDEX IF NOT EXISTS idx_auth_configs_singleton ON _auth_configs ((1));
+
+-- Add trigger for updated_at
+DROP TRIGGER IF EXISTS update__auth_configs_updated_at ON _auth_configs;
+CREATE TRIGGER update__auth_configs_updated_at
+BEFORE UPDATE ON _auth_configs
+FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

package/backend/src/infra/database/migrations/016_update-auth-config-and-email-otp.sql

@@ -0,0 +1,24 @@
+-- Migration 016: Update _email_otps and _auth_configs tables
+--
+-- Changes:
+-- 1. _email_otps table:
+--    - Remove attempts_count column (brute force protection moved to API rate limiter)
+-- 2. _auth_configs table:
+--    - Remove verify_email_redirect_to and reset_password_redirect_to columns
+--    - Add verify_email_method and reset_password_method columns (code or link)
+--    - Add sign_in_redirect_to column
+
+-- Update _email_otps: Remove attempts_count column
+ALTER TABLE _email_otps DROP COLUMN IF EXISTS attempts_count;
+
+-- Update _auth_configs: Remove old redirect columns
+ALTER TABLE _auth_configs
+  DROP COLUMN IF EXISTS verify_email_redirect_to,
+  DROP COLUMN IF EXISTS reset_password_redirect_to;
+
+-- Add new columns to _auth_configs
+-- Note: DEFAULT 'code' NOT NULL ensures existing rows automatically get 'code' value
+ALTER TABLE _auth_configs
+  ADD COLUMN IF NOT EXISTS verify_email_method TEXT DEFAULT 'code' NOT NULL CHECK (verify_email_method IN ('code', 'link')),
+  ADD COLUMN IF NOT EXISTS reset_password_method TEXT DEFAULT 'code' NOT NULL CHECK (reset_password_method IN ('code', 'link')),
+  ADD COLUMN IF NOT EXISTS sign_in_redirect_to TEXT;

package/backend/src/{core/secrets/encryption.ts → infra/security/encryption.manager.ts}

@@ -1,9 +1,10 @@
 import crypto from 'crypto';
 
 /**
- * Encryption utilities for secrets management
+ * EncryptionManager - Handles encryption/decryption operations
+ * Infrastructure layer for secrets encryption
  */
-export class EncryptionUtils {
+export class EncryptionManager {
   private static encryptionKey: Buffer | null = null;
 
   private static getEncryptionKey(): Buffer {

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

@@ -0,0 +1,125 @@
+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
+      );
+    }
+  }
+}

package/backend/src/{core/socket/socket.ts → infra/socket/socket.manager.ts}

@@ -1,7 +1,7 @@
 import { Server as HttpServer } from 'http';
 import { Server as SocketIOServer, Socket } from 'socket.io';
 import logger from '@/utils/logger.js';
-import { AuthService } from '../auth/auth.js';
+import { TokenManager } from '@/infra/security/token.manager.js';
 import {
   ServerEvents,
   ClientEvents,
@@ -10,31 +10,31 @@ import {
   NotificationPayload,
   SubscribePayload,
   UnsubscribePayload,
-} from './types.js';
-import { AppError } from '@/api/middleware/error.js';
+} from '@/types/socket.js';
+import { AppError } from '@/api/middlewares/error.js';
 import { ERROR_CODES, NEXT_ACTION } from '@/types/error-constants.js';
 
-const authService = AuthService.getInstance();
+const tokenManager = TokenManager.getInstance();
 
 /**
- * SocketService - Industrial-grade Socket.IO implementation
- * Follows best practices for real-time communication
+ * SocketManager - Industrial-grade Socket.IO implementation
+ * Infrastructure layer for real-time WebSocket communication
  */
-export class SocketService {
-  private static instance: SocketService;
+export class SocketManager {
+  private static instance: SocketManager;
   private io: SocketIOServer | null = null;
   private socketMetadata: Map<string, SocketMetadata> = new Map();
 
   private constructor() {}
 
   /**
-   * Singleton pattern for global socket service access
+   * Singleton pattern for global socket manager access
    */
-  static getInstance(): SocketService {
-    if (!SocketService.instance) {
-      SocketService.instance = new SocketService();
+  static getInstance(): SocketManager {
+    if (!SocketManager.instance) {
+      SocketManager.instance = new SocketManager();
     }
-    return SocketService.instance;
+    return SocketManager.instance;
   }
 
   /**
@@ -66,7 +66,7 @@ export class SocketService {
     this.io.use((socket, next) => {
       try {
         const token = socket.handshake.auth.token;
-        const payload = authService.verifyToken(token);
+        const payload = tokenManager.verifyToken(token);
         if (!payload.role) {
           throw new AppError(
             'Invalid token: missing role',
@@ -385,4 +385,4 @@ export class SocketService {
 }
 
 // Export singleton instance for convenience
-export const socketService = SocketService.getInstance();
+export const socketService = SocketManager.getInstance();

package/backend/src/providers/ai/openrouter.provider.ts

@@ -0,0 +1,377 @@
+import OpenAI from 'openai';
+import jwt from 'jsonwebtoken';
+import { isCloudEnvironment } from '@/utils/environment.js';
+import { AppError } from '@/api/middlewares/error.js';
+import { ERROR_CODES } from '@/types/error-constants.js';
+import logger from '@/utils/logger.js';
+
+interface CloudCredentialsResponse {
+  openrouter?: {
+    api_key: string;
+    limit?: number;
+    expired_at?: string | null;
+    usage?: number;
+    limit_remaining?: number;
+  };
+}
+
+interface CloudCredentials {
+  apiKey: string;
+  limitRemaining?: number;
+}
+
+interface OpenRouterKeyInfo {
+  data: {
+    label: string;
+    usage: number;
+    limit: number | null;
+    is_free_tier: boolean;
+  };
+}
+
+interface OpenRouterLimitation {
+  label: string;
+  credit_limit: number | null;
+  credit_used: number;
+  credit_remaining: number | null;
+  rate_limit?: {
+    requests?: number;
+    interval?: string;
+    note?: string;
+  };
+}
+
+export class AIClientService {
+  private static instance: AIClientService;
+  private cloudCredentials: CloudCredentials | undefined;
+  private openRouterClient: OpenAI | null = null;
+  private currentApiKey: string | undefined;
+  private renewalPromise: Promise<string> | null = null;
+  private fetchPromise: Promise<string> | null = null;
+
+  private constructor() {}
+
+  static getInstance(): AIClientService {
+    if (!AIClientService.instance) {
+      AIClientService.instance = new AIClientService();
+    }
+    return AIClientService.instance;
+  }
+
+  /**
+   * Create or recreate the OpenAI client with the given API key
+   */
+  private createClient(apiKey: string): OpenAI {
+    this.currentApiKey = apiKey;
+    return new OpenAI({
+      baseURL: 'https://openrouter.ai/api/v1',
+      apiKey,
+      defaultHeaders: {
+        'HTTP-Referer': 'https://insforge.dev',
+        'X-Title': 'InsForge',
+      },
+    });
+  }
+
+  /**
+   * Get OpenRouter API key based on environment
+   * In cloud environment: fetches from cloud API with JWT authentication
+   * In local environment: returns from environment variable
+   */
+  async getApiKey(): Promise<string> {
+    if (isCloudEnvironment()) {
+      if (this.cloudCredentials) {
+        return this.cloudCredentials.apiKey;
+      } else {
+        return await this.fetchCloudApiKey();
+      }
+    }
+
+    const apiKey = process.env.OPENROUTER_API_KEY;
+    if (!apiKey) {
+      throw new AppError(
+        'OPENROUTER_API_KEY not found in environment variables',
+        500,
+        ERROR_CODES.AI_INVALID_API_KEY
+      );
+    }
+    return apiKey;
+  }
+
+  /**
+   * Get the OpenAI client, creating or updating it as needed
+   * This is the main method services should use
+   */
+  async getClient(): Promise<OpenAI> {
+    if (!this.openRouterClient) {
+      this.openRouterClient = this.createClient(await this.getApiKey());
+      return this.openRouterClient;
+    }
+    if (isCloudEnvironment()) {
+      const apiKey = await this.getApiKey();
+      if (this.currentApiKey !== apiKey) {
+        this.openRouterClient = this.createClient(apiKey);
+      }
+    }
+    return this.openRouterClient;
+  }
+
+  /**
+   * Check if AI services are properly configured
+   */
+  isConfigured(): boolean {
+    if (isCloudEnvironment()) {
+      return true;
+    }
+    return !!process.env.OPENROUTER_API_KEY;
+  }
+
+  /**
+   * Get remaining credits for the current API key from OpenRouter
+   */
+  async getRemainingCredits(): Promise<{
+    usage: number;
+    limit: number | null;
+    remaining: number | null;
+  }> {
+    try {
+      const apiKey = await this.getApiKey();
+
+      if (isCloudEnvironment()) {
+        // Use InsForge API for cloud environment
+        const response = await fetch(
+          `https://api.insforge.dev/ai/v1/limitations?credential=${encodeURIComponent(apiKey)}`,
+          {
+            method: 'GET',
+          }
+        );
+
+        if (!response.ok) {
+          throw new Error(`Failed to fetch key info: ${response.statusText}`);
+        }
+
+        const result = (await response.json()) as { data: OpenRouterLimitation };
+        const keyInfo = result.data;
+
+        return {
+          usage: keyInfo.credit_used,
+          limit: keyInfo.credit_limit,
+          remaining: keyInfo.credit_remaining,
+        };
+      } else {
+        // Use OpenRouter API for local environment
+        const response = await fetch('https://openrouter.ai/api/v1/key', {
+          method: 'GET',
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+          },
+        });
+
+        if (!response.ok) {
+          throw new AppError(
+            `Invalid OpenRouter API Key`,
+            500,
+            ERROR_CODES.AI_INVALID_API_KEY,
+            'Check your OpenRouter key and try again.'
+          );
+        }
+
+        const keyInfo = (await response.json()) as OpenRouterKeyInfo;
+
+        return {
+          usage: keyInfo.data.usage,
+          limit: keyInfo.data.limit,
+          remaining: keyInfo.data.limit !== null ? keyInfo.data.limit - keyInfo.data.usage : null,
+        };
+      }
+    } catch (error) {
+      console.error('Failed to fetch remaining credits:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Fetch API key from cloud service
+   * Uses promise memoization to prevent duplicate fetch requests
+   */
+  private async fetchCloudApiKey(): Promise<string> {
+    // If fetch is already in progress, wait for it
+    if (this.fetchPromise) {
+      logger.info('Fetch already in progress, waiting for completion...');
+      return this.fetchPromise;
+    }
+
+    // Start new fetch and store the promise
+    this.fetchPromise = (async () => {
+      try {
+        const projectId = process.env.PROJECT_ID;
+        if (!projectId) {
+          throw new Error('PROJECT_ID not found in environment variables');
+        }
+
+        const jwtSecret = process.env.JWT_SECRET;
+        if (!jwtSecret) {
+          throw new Error('JWT_SECRET not found in environment variables');
+        }
+
+        // Sign a token for authentication
+        const token = jwt.sign({ projectId }, jwtSecret, { expiresIn: '1h' });
+
+        // Fetch API key from cloud service with sign token as query parameter
+        const response = await fetch(
+          `${process.env.CLOUD_API_HOST || 'https://api.insforge.dev'}/ai/v1/credentials/${projectId}?sign=${token}`
+        );
+
+        if (!response.ok) {
+          throw new Error(`Failed to fetch cloud API key: ${response.statusText}`);
+        }
+
+        const data = (await response.json()) as CloudCredentialsResponse;
+
+        // Extract API key from the openrouter object in response
+        if (!data.openrouter?.api_key) {
+          throw new Error('Invalid response: missing openrouter API Key');
+        }
+
+        // Store credentials with metadata
+        this.cloudCredentials = {
+          apiKey: data.openrouter.api_key,
+          limitRemaining: data.openrouter.limit_remaining,
+        };
+
+        logger.info('Successfully fetched cloud API key');
+
+        return data.openrouter.api_key;
+      } catch (error) {
+        console.error('Failed to fetch cloud API key:', error);
+        throw error;
+      } finally {
+        // Clear the promise after completion (success or failure)
+        this.fetchPromise = null;
+      }
+    })();
+
+    return this.fetchPromise;
+  }
+
+  /**
+   * Renew API key from cloud service when credits are exhausted
+   * Uses promise memoization to prevent duplicate renewal requests
+   */
+  async renewCloudApiKey(): Promise<string> {
+    // If renewal is already in progress, wait for it
+    if (this.renewalPromise) {
+      logger.info('Renewal already in progress, waiting for completion...');
+      return this.renewalPromise;
+    }
+
+    // Start new renewal and store the promise
+    this.renewalPromise = (async () => {
+      try {
+        const projectId = process.env.PROJECT_ID;
+        if (!projectId) {
+          throw new Error('PROJECT_ID not found in environment variables');
+        }
+
+        const jwtSecret = process.env.JWT_SECRET;
+        if (!jwtSecret) {
+          throw new Error('JWT_SECRET not found in environment variables');
+        }
+
+        // Sign a token for authentication
+        const token = jwt.sign({ projectId }, jwtSecret, { expiresIn: '1h' });
+
+        // Renew API key from cloud service with sign token in request body
+        const response = await fetch(
+          `${process.env.CLOUD_API_HOST || 'https://api.insforge.dev'}/ai/v1/credentials/${projectId}/renew`,
+          {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ sign: token }),
+          }
+        );
+
+        if (!response.ok) {
+          throw new Error(`Failed to renew cloud API key: ${response.statusText}`);
+        }
+
+        const data = (await response.json()) as CloudCredentialsResponse;
+
+        // Extract API key from the openrouter object in response
+        if (!data.openrouter?.api_key) {
+          throw new Error('Invalid response: missing openrouter API Key');
+        }
+
+        // Store credentials with metadata
+        this.cloudCredentials = {
+          apiKey: data.openrouter.api_key,
+          limitRemaining: data.openrouter.limit_remaining,
+        };
+
+        logger.info('Successfully renewed cloud API key');
+
+        // Wait for OpenRouter to propagate the updated credits
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+
+        return data.openrouter.api_key;
+      } catch (error) {
+        console.error('Failed to renew cloud API key:', error);
+        throw error;
+      } finally {
+        // Clear the promise after completion (success or failure)
+        this.renewalPromise = null;
+      }
+    })();
+
+    return this.renewalPromise;
+  }
+
+  /**
+   * Send a request to OpenRouter with automatic renewal and retry logic
+   * Handles 403 insufficient credits errors by renewing the API key and retrying
+   * @param request - Function that takes an OpenAI client and returns a Promise
+   * @returns The result of the request
+   */
+  async sendRequest<T>(request: (client: OpenAI) => Promise<T>): Promise<T> {
+    const client = await this.getClient();
+
+    try {
+      return await request(client);
+    } catch (error) {
+      // Check if error is a 402/403 insufficient credits error in cloud environment
+      if (
+        isCloudEnvironment() &&
+        error instanceof OpenAI.APIError &&
+        (error.status === 402 || error.status === 403)
+      ) {
+        logger.info(`Received ${error.status} insufficient credits, renewing API key...`);
+        await this.renewCloudApiKey();
+
+        // Retry with exponential backoff (3 attempts)
+        const maxRetries = 3;
+
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+          try {
+            const backoffMs = Math.pow(2, attempt - 1) * 1000; // 1s, 2s, 4s
+            logger.info(
+              `Retrying request after renewal (attempt ${attempt}/${maxRetries}), waiting ${backoffMs}ms...`
+            );
+            await new Promise((resolve) => setTimeout(resolve, backoffMs));
+
+            const result = await request(client);
+            logger.info('Request succeeded after API key renewal');
+            return result;
+          } catch (retryError) {
+            if (attempt === maxRetries) {
+              logger.error(`All ${maxRetries} retry attempts failed after API key renewal`);
+              throw retryError;
+            }
+          }
+        }
+      }
+      throw error;
+    }
+  }
+}