@wildo-ai/saas-backend-lib 1.0.1

package/src/notifications/email/services/email-template-registry.backend.service.ts

@@ -0,0 +1,166 @@
+/**
+ * Email Template Registry Backend Service
+ *
+ * In-memory registry for file-based email template definitions.
+ * Templates are injected at startup from app-custom via initialize().
+ * Resolution uses exact templateRef match with i18n locale fallback.
+ *
+ * Each template is a locale-agnostic definition (`template.tsx`) paired
+ * with co-located per-locale label files (`labels.{locale}.ts`).
+ */
+
+import { injectable, inject } from 'inversify';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { ErrorType, getAllSystemTemplateRefs, type WildoError_Backend } from '@wildo-ai/saas-models';
+import type {
+  EmailTemplateDefinition,
+  EmailTemplateDefinitionsMap,
+} from '~wildo-backend-lib/notifications/email/models/email-template-definition';
+
+/** Resolved template returned by `resolve()`: definition + locale-matched labels. */
+export interface ResolvedEmailTemplate {
+  definition: EmailTemplateDefinition<any>;
+  labels: Record<string, string>;
+  resolvedLocale: string;
+}
+
+interface RegistryLocaleEntry {
+  definition: EmailTemplateDefinition<any>;
+  labels: Record<string, string>;
+}
+
+@injectable()
+export class EmailTemplateRegistryBackendService {
+  private entries = new Map<string, Map<string, RegistryLocaleEntry>>();
+
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('EmailTemplateRegistry');
+    this.logger.setDebugTypeLogging('EmailTemplateRegistry', false);
+  }
+
+  /**
+   * Populate the registry from the app-custom template map.
+   *
+   * Keys are bare `templateRef` values. Each entry has a locale-agnostic
+   * template definition + per-locale label objects.
+   */
+  initialize(definitions: EmailTemplateDefinitionsMap): void {
+    this.entries.clear();
+
+    for (const [templateRef, entry] of Object.entries(definitions)) {
+      const localeMap = new Map<string, RegistryLocaleEntry>();
+      for (const [locale, labels] of Object.entries(entry.labels)) {
+        localeMap.set(locale, { definition: entry.template, labels });
+      }
+      this.entries.set(templateRef, localeMap);
+    }
+
+    const { templateCount, locales } = this.computeStats();
+    this.logger.info(`✅ Email template registry: ${templateCount} template(s) across ${locales.size} locale(s)`);
+    this.validateSystemTemplates(locales);
+  }
+
+  /**
+   * Resolve a template by ref with i18n locale fallback.
+   *
+   * 1. Exact locale match (e.g. fr-CA)
+   * 2. Base language fallback (e.g. fr)
+   * 3. Default locale fallback (e.g. en)
+   * 4. Throw if none found
+   */
+  resolve(templateRef: string, locale: string, defaultLocale: string): ResolvedEmailTemplate {
+    const localeMap = this.entries.get(templateRef);
+    if (!localeMap) {
+      throw this.buildNotFoundError(templateRef, [locale, defaultLocale]);
+    }
+
+    const candidates = [locale];
+    const baseLanguage = locale.includes('-') ? locale.split('-')[0] : null;
+    if (baseLanguage && baseLanguage !== locale) {
+      candidates.push(baseLanguage);
+    }
+    if (!candidates.includes(defaultLocale)) {
+      candidates.push(defaultLocale);
+    }
+
+    for (const candidateLocale of candidates) {
+      const entry = localeMap.get(candidateLocale);
+      if (entry) {
+        this.logDebug('Template resolved', { templateRef, resolvedLocale: candidateLocale });
+        return {
+          definition: entry.definition,
+          labels: entry.labels,
+          resolvedLocale: candidateLocale,
+        };
+      }
+    }
+
+    throw this.buildNotFoundError(templateRef, candidates);
+  }
+
+  /** Return all registered keys as `{templateRef}/{locale}` (diagnostics). */
+  getRegisteredKeys(): string[] {
+    const keys: string[] = [];
+    for (const [templateRef, localeMap] of this.entries) {
+      for (const locale of localeMap.keys()) {
+        keys.push(`${templateRef}/${locale}`);
+      }
+    }
+    return keys;
+  }
+
+  // ── Validation ─────────────────────────────────────────────────
+
+  private validateSystemTemplates(registeredLocales: Set<string>): void {
+    const systemRefs = getAllSystemTemplateRefs();
+    const defaultLocale = registeredLocales.has('en') ? 'en' : registeredLocales.values().next().value;
+    if (!defaultLocale) return;
+
+    const missing: string[] = [];
+    for (const ref of systemRefs) {
+      const localeMap = this.entries.get(ref);
+      if (!localeMap?.has(defaultLocale)) {
+        missing.push(ref);
+      }
+    }
+
+    if (missing.length > 0) {
+      this.logger.warn(`⚠️ Missing email templates for ${missing.length} system ref(s) in locale "${defaultLocale}": ${missing.join(', ')}`);
+    }
+  }
+
+  // ── Helpers ────────────────────────────────────────────────────
+
+  private computeStats(): { templateCount: number; locales: Set<string> } {
+    const locales = new Set<string>();
+    let templateCount = 0;
+    for (const localeMap of this.entries.values()) {
+      templateCount += localeMap.size;
+      for (const locale of localeMap.keys()) {
+        locales.add(locale);
+      }
+    }
+    return { templateCount, locales };
+  }
+
+  private buildNotFoundError(templateRef: string, triedLocales: string[]): WildoError_Backend {
+    return this.errorBuilder.buildError(
+      ErrorType.CONFIGURATION,
+      undefined,
+      {
+        context: {
+          message: `Email template "${templateRef}" not found for any locale [${triedLocales.join(', ')}]`,
+          templateRef,
+          triedLocales,
+        },
+      },
+    );
+  }
+}

package/src/notifications/email/services/email-template-sandbox.backend.service.ts

@@ -0,0 +1,255 @@
+/**
+ * Email Template Sandbox Backend Service
+ *
+ * Provides a secure execution environment for running compiled email templates.
+ * Uses Node.js VM with restricted globals and a controlled require function.
+ */
+
+import { injectable, inject } from 'inversify';
+import * as vm from 'vm';
+import { ErrorType, ErrorCustomMessageReference } from '@wildo-ai/saas-models';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SandboxExecutionResult {
+  success: boolean;
+  result?: unknown;
+  error?: string;
+  durationMs: number;
+}
+
+export interface SandboxOptions {
+  /** Timeout in milliseconds (default: 5000) */
+  timeout?: number;
+  /** Additional context to pass to the template */
+  additionalContext?: Record<string, unknown>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CONSTANTS
+// ─────────────────────────────────────────────────────────────────────────────
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+/**
+ * Allowed modules that can be required in the sandbox
+ */
+const ALLOWED_MODULES = new Set([
+  'react',
+  'react-dom',
+  '@react-email/components',
+  '@react-email/render',
+  '@wildo-ai/email-components',
+]);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SERVICE
+// ─────────────────────────────────────────────────────────────────────────────
+
+@injectable()
+export class EmailTemplateSandboxBackendService {
+  private emailComponentsModule: unknown | null = null;
+
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('EmailTemplateSandboxBackendService');
+    this.logger.setDebugTypeLogging('EmailTemplateSandboxBackendService', false);
+  }
+
+  /**
+   * Execute a compiled module in the sandbox
+   *
+   * @param compiledCode - The compiled JavaScript code
+   * @param context - The context to pass to the template
+   * @param options - Execution options
+   * @returns Execution result with the rendered output or error
+   */
+  async execute(
+    compiledCode: string,
+    context: Record<string, unknown>,
+    options: SandboxOptions = {}
+  ): Promise<SandboxExecutionResult> {
+    const startTime = Date.now();
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+
+    this.logDebug('Executing email template in sandbox', { timeout });
+
+    try {
+      // Create sandbox require function
+      const sandboxRequire = this.createSandboxRequire();
+
+      // Create sandbox globals
+      const sandbox: vm.Context = {
+        module: { exports: {} },
+        exports: {},
+        require: sandboxRequire,
+        console: this.createSafeConsole(),
+        // Pass context values
+        __context: context,
+        __brand: context.__brand || {},
+        // Provide Buffer for any serialization needs
+        Buffer: {
+          from: Buffer.from.bind(Buffer),
+          isBuffer: Buffer.isBuffer.bind(Buffer),
+        },
+      };
+
+      // Add additional context if provided
+      if (options.additionalContext) {
+        Object.assign(sandbox, options.additionalContext);
+      }
+
+      // Create VM context
+      vm.createContext(sandbox);
+
+      // Wrap the code to capture the default export
+      const wrappedCode = `
+        (function(module, exports, require, __context, __brand) {
+          ${compiledCode}
+          return module.exports.default || module.exports;
+        })(module, exports, require, __context, __brand);
+      `;
+
+      // Execute with timeout
+      const script = new vm.Script(wrappedCode, {
+        filename: 'email-template.js',
+      });
+
+      const result = script.runInContext(sandbox, {
+        timeout,
+        displayErrors: true,
+      });
+
+      const durationMs = Date.now() - startTime;
+      this.logDebug('Sandbox execution completed', { durationMs });
+
+      return {
+        success: true,
+        result,
+        durationMs,
+      };
+    } catch (err) {
+      const error = err as Error;
+      const durationMs = Date.now() - startTime;
+
+      this.logger.error('Sandbox execution failed', {
+        error: error.message,
+        durationMs,
+        isTimeout: error.message.includes('Script execution timed out'),
+      });
+
+      return {
+        success: false,
+        error: error.message,
+        durationMs,
+      };
+    }
+  }
+
+  /**
+   * Create a safe require function that only allows specific modules
+   */
+  private createSandboxRequire(): (moduleName: string) => unknown {
+    return (moduleName: string): unknown => {
+      // Handle @wildo-ai/email-components specially - load our internal module
+      if (moduleName === '@wildo-ai/email-components') {
+        return this.getEmailComponentsModule();
+      }
+
+      // Check if module is in allowlist
+      if (!ALLOWED_MODULES.has(moduleName)) {
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+          context: { moduleName, message: 'Module is not allowed in email templates' },
+        });
+      }
+
+      // For allowed modules, use the real require
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      return require(moduleName);
+    };
+  }
+
+  /**
+   * Get the email components module (lazy loaded)
+   * Uses multiple resolution strategies for robustness across different build outputs
+   */
+  private getEmailComponentsModule(): unknown {
+    if (!this.emailComponentsModule) {
+      // Load our internal email components with multiple resolution strategies
+      const resolutionStrategies = [
+        // Strategy 1: Relative path from current file
+        () => require('../components/email-components'),
+        // Strategy 2: Absolute path using __dirname
+        () => require(require('path').resolve(__dirname, '../components/email-components')),
+        // Strategy 3: Try dist/esm path
+        () => require(require('path').resolve(__dirname, '../../dist/esm/notifications/email/components/email-components')),
+        // Strategy 4: Try dist/cjs path
+        () => require(require('path').resolve(__dirname, '../../dist/cjs/notifications/email/components/email-components')),
+      ];
+
+      for (const strategy of resolutionStrategies) {
+        try {
+          this.emailComponentsModule = strategy();
+          this.logDebug('Email components module loaded successfully');
+          return this.emailComponentsModule;
+        } catch {
+          // Try next strategy
+        }
+      }
+
+      this.logger.error('Failed to load email components module with any strategy');
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+        context: { message: 'Email components module not available' },
+      });
+    }
+    return this.emailComponentsModule;
+  }
+
+  /**
+   * Create a safe console that logs through our logger
+   */
+  private createSafeConsole(): Partial<Console> {
+    return {
+      log: (...args: unknown[]) => {
+        this.logger.debug('Template console.log', { args });
+      },
+      warn: (...args: unknown[]) => {
+        this.logger.warn('Template console.warn', { args });
+      },
+      error: (...args: unknown[]) => {
+        this.logger.error('Template console.error', { args });
+      },
+      info: (...args: unknown[]) => {
+        this.logger.info('Template console.info', { args });
+      },
+      debug: (...args: unknown[]) => {
+        this.logger.debug('Template console.debug', { args });
+      },
+    };
+  }
+
+  /**
+   * Check if a module is allowed in the sandbox
+   */
+  isModuleAllowed(moduleName: string): boolean {
+    return ALLOWED_MODULES.has(moduleName);
+  }
+
+  /**
+   * Get list of allowed modules (for LLM context)
+   */
+  getAllowedModules(): string[] {
+    return Array.from(ALLOWED_MODULES);
+  }
+}

package/src/notifications/email/services/email-template-validator.backend.service.ts

@@ -0,0 +1,229 @@
+/**
+ * Email Template Validator Backend Service
+ *
+ * Validates TSX email templates for security and correctness.
+ * Checks for:
+ * - Import allowlist compliance
+ * - Forbidden patterns (Node.js APIs, dangerous code)
+ * - Syntax validation via ESBuild
+ */
+
+import { injectable, inject } from 'inversify';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface TsxValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CONSTANTS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Allowed import paths for generated email templates
+ * Templates can only import from these modules
+ */
+export const EMAIL_TEMPLATE_ALLOWED_IMPORTS: string[] = [
+  // React Email core
+  '@react-email/components',
+  '@react-email/render',
+  // Our predefined email components
+  '@wildo-ai/email-components',
+  // React (limited)
+  'react',
+];
+
+/**
+ * Forbidden patterns that indicate potentially dangerous code
+ */
+const FORBIDDEN_PATTERNS: Array<{ pattern: RegExp; message: string }> = [
+  // Node.js APIs
+  { pattern: /require\s*\(/g, message: 'Dynamic require() is not allowed' },
+  { pattern: /import\s*\(/g, message: 'Dynamic import() is not allowed' },
+  { pattern: /process\./g, message: 'Access to process is not allowed' },
+  { pattern: /global\./g, message: 'Access to global is not allowed' },
+  { pattern: /globalThis\./g, message: 'Access to globalThis is not allowed' },
+  { pattern: /__dirname/g, message: '__dirname is not allowed' },
+  { pattern: /__filename/g, message: '__filename is not allowed' },
+
+  // File system
+  { pattern: /\bfs\b/g, message: 'File system access is not allowed' },
+  { pattern: /\bpath\b\.(?!join|resolve)/g, message: 'Path module access is restricted' },
+
+  // Network
+  { pattern: /\bhttp\b/g, message: 'HTTP module is not allowed' },
+  { pattern: /\bhttps\b/g, message: 'HTTPS module is not allowed' },
+  { pattern: /\bnet\b/g, message: 'Net module is not allowed' },
+  { pattern: /\bfetch\s*\(/g, message: 'fetch() is not allowed in templates' },
+  { pattern: /\bXMLHttpRequest\b/g, message: 'XMLHttpRequest is not allowed' },
+
+  // Code execution
+  { pattern: /\beval\s*\(/g, message: 'eval() is not allowed' },
+  { pattern: /\bFunction\s*\(/g, message: 'Function() constructor is not allowed' },
+  { pattern: /\bsetTimeout\s*\(/g, message: 'setTimeout() is not allowed in templates' },
+  { pattern: /\bsetInterval\s*\(/g, message: 'setInterval() is not allowed in templates' },
+
+  // Child processes
+  { pattern: /child_process/g, message: 'child_process is not allowed' },
+  { pattern: /\bexec\s*\(/g, message: 'exec() is not allowed' },
+  { pattern: /\bspawn\s*\(/g, message: 'spawn() is not allowed' },
+];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SERVICE
+// ─────────────────────────────────────────────────────────────────────────────
+
+@injectable()
+export class EmailTemplateValidatorBackendService {
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+  ) {
+    this.logDebug = this.logger.debugByType('EmailTemplateValidatorBackendService');
+    this.logger.setDebugTypeLogging('EmailTemplateValidatorBackendService', false);
+  }
+
+  /**
+   * Validate a TSX template source
+   *
+   * @param tsxSource - The TSX template source code
+   * @returns Validation result with errors and warnings
+   */
+  async validate(tsxSource: string): Promise<TsxValidationResult> {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    this.logDebug('Validating email template TSX source');
+
+    // 1. Check for forbidden patterns
+    const forbiddenErrors = this.checkForbiddenPatterns(tsxSource);
+    errors.push(...forbiddenErrors);
+
+    // 2. Validate imports
+    const importErrors = this.validateImports(tsxSource);
+    errors.push(...importErrors);
+
+    // 3. Syntax check via ESBuild (basic parse)
+    try {
+      const syntaxResult = await this.checkSyntax(tsxSource);
+      if (!syntaxResult.valid) {
+        errors.push(...syntaxResult.errors);
+      }
+      warnings.push(...syntaxResult.warnings);
+    } catch (err) {
+      const error = err as Error;
+      errors.push(`Syntax error: ${error.message}`);
+    }
+
+    const valid = errors.length === 0;
+
+    if (!valid) {
+      this.logger.warn('Email template validation failed', { errorCount: errors.length, errors });
+    } else {
+      this.logDebug('Email template validation passed', { warningCount: warnings.length });
+    }
+
+    return { valid, errors, warnings };
+  }
+
+  /**
+   * Check for forbidden patterns in the source code
+   */
+  private checkForbiddenPatterns(tsxSource: string): string[] {
+    const errors: string[] = [];
+
+    for (const { pattern, message } of FORBIDDEN_PATTERNS) {
+      // Reset regex state
+      pattern.lastIndex = 0;
+      if (pattern.test(tsxSource)) {
+        errors.push(message);
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * Validate that all imports are in the allowlist
+   */
+  private validateImports(tsxSource: string): string[] {
+    const errors: string[] = [];
+
+    // Match import statements
+    const importRegex = /import\s+(?:[\w*{}\s,]+\s+from\s+)?['"]([^'"]+)['"]/g;
+    let match;
+
+    while ((match = importRegex.exec(tsxSource)) !== null) {
+      const importPath = match[1];
+
+      // Check if import is allowed
+      const isAllowed = EMAIL_TEMPLATE_ALLOWED_IMPORTS.some(allowed => {
+        return importPath === allowed || importPath.startsWith(allowed + '/');
+      });
+
+      if (!isAllowed) {
+        errors.push(`Import from '${importPath}' is not allowed. Allowed imports: ${EMAIL_TEMPLATE_ALLOWED_IMPORTS.join(', ')}`);
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * Check syntax using ESBuild's parser
+   */
+  private async checkSyntax(tsxSource: string): Promise<{ valid: boolean; errors: string[]; warnings: string[] }> {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    try {
+      // Lazy import esbuild
+      const esbuild = await import('esbuild');
+
+      // Transform with TSX loader - this will catch syntax errors
+      const result = await esbuild.transform(tsxSource, {
+        loader: 'tsx',
+        target: 'es2020',
+        jsx: 'automatic',
+        minify: false,
+      });
+
+      // Check for warnings from ESBuild
+      if (result.warnings && result.warnings.length > 0) {
+        for (const warning of result.warnings) {
+          warnings.push(`Line ${warning.location?.line || '?'}: ${warning.text}`);
+        }
+      }
+
+      return { valid: true, errors, warnings };
+    } catch (err) {
+      const error = err as Error & { errors?: Array<{ text: string; location?: { line: number } }> };
+
+      // ESBuild error format
+      if (error.errors && Array.isArray(error.errors)) {
+        for (const e of error.errors) {
+          errors.push(`Line ${e.location?.line || '?'}: ${e.text}`);
+        }
+      } else {
+        errors.push(error.message);
+      }
+
+      return { valid: false, errors, warnings };
+    }
+  }
+
+  /**
+   * Get the list of allowed imports (for LLM context)
+   */
+  getAllowedImports(): string[] {
+    return [...EMAIL_TEMPLATE_ALLOWED_IMPORTS];
+  }
+}