@carmaclouds/core 2.3.1

package/src/common/browser-polyfill.js

@@ -0,0 +1,319 @@
+/**
+ * Browser API Compatibility Layer - Chrome & Firefox Support
+ *
+ * This provides a consistent browserAPI interface across Chrome and Firefox.
+ * Firefox uses the 'browser' namespace (Promise-based), while Chrome uses 'chrome' (callback-based).
+ */
+
+console.log('🌐 Loading browser polyfill...');
+
+// Use 'self' for service workers, 'window' for content scripts/popups
+const globalScope = typeof window !== 'undefined' ? window : self;
+
+// Detect browser and use appropriate API
+let browserAPI;
+
+if (typeof browser !== 'undefined' && browser.runtime) {
+  // Firefox - uses native Promise-based API
+  console.log('🦊 Detected Firefox');
+  browserAPI = browser;
+} else if (typeof chrome !== 'undefined' && chrome.runtime) {
+  // Chrome - wrap callback-based API to be consistent with Firefox
+  console.log('🌐 Detected Chrome');
+  // Helper to check if Chrome extension context is valid
+  const isChromeContextValid = () => {
+    try {
+      return chrome && chrome.runtime && chrome.runtime.id;
+    } catch (error) {
+      return false;
+    }
+  };
+
+  browserAPI = {
+    runtime: {
+      sendMessage: (message, callback) => {
+        // If callback is provided, use callback-based API
+        if (typeof callback === 'function') {
+          try {
+            if (!isChromeContextValid()) {
+              console.error('❌ Extension context invalidated');
+              callback(null);
+              return;
+            }
+            chrome.runtime.sendMessage(message, callback);
+          } catch (error) {
+            // Handle "Extension context invalidated" error in Chrome
+            console.error('❌ Extension context error:', error.message);
+            callback(null);
+          }
+          return;
+        }
+        // Otherwise return a Promise
+        return new Promise((resolve, reject) => {
+          try {
+            if (!isChromeContextValid()) {
+              reject(new Error('Extension context invalidated'));
+              return;
+            }
+            chrome.runtime.sendMessage(message, (response) => {
+              if (chrome.runtime.lastError) {
+                reject(new Error(chrome.runtime.lastError.message));
+              } else {
+                resolve(response);
+              }
+            });
+          } catch (error) {
+            // Handle "Extension context invalidated" error in Chrome
+            console.error('❌ Extension context error:', error.message);
+            reject(error);
+          }
+        });
+      },
+      onMessage: chrome.runtime.onMessage,
+      getURL: (path) => {
+        try {
+          if (!isChromeContextValid()) return null;
+          return chrome.runtime.getURL(path);
+        } catch (error) {
+          console.error('❌ Extension context error:', error.message);
+          return null;
+        }
+      },
+      getManifest: () => {
+        try {
+          if (!isChromeContextValid()) return null;
+          return chrome.runtime.getManifest();
+        } catch (error) {
+          console.error('❌ Extension context error:', error.message);
+          return null;
+        }
+      },
+      get id() {
+        try {
+          if (!isChromeContextValid()) return null;
+          return chrome.runtime.id;
+        } catch (error) {
+          console.error('❌ Extension context error:', error.message);
+          return null;
+        }
+      },
+      get lastError() {
+        try {
+          if (!isChromeContextValid()) return null;
+          return chrome.runtime.lastError;
+        } catch (error) {
+          return null;
+        }
+      },
+      connectNative: (application) => {
+        try {
+          if (!isChromeContextValid()) {
+            console.error('❌ Extension context invalidated');
+            return null;
+          }
+          const port = chrome.runtime.connectNative(application);
+          // Check for immediate errors
+          if (chrome.runtime.lastError) {
+            console.warn('⚠️ Native messaging error:', chrome.runtime.lastError.message);
+            return null;
+          }
+          return port;
+        } catch (error) {
+          console.error('❌ Native messaging error:', error.message);
+          return null;
+        }
+      }
+    },
+    storage: {
+      local: {
+        get: (keys) => {
+          return new Promise((resolve, reject) => {
+            try {
+              if (!isChromeContextValid()) {
+                reject(new Error('Extension context invalidated'));
+                return;
+              }
+              chrome.storage.local.get(keys, (result) => {
+                if (chrome.runtime.lastError) {
+                  reject(new Error(chrome.runtime.lastError.message));
+                } else {
+                  resolve(result);
+                }
+              });
+            } catch (error) {
+              reject(new Error('Extension context invalidated'));
+            }
+          });
+        },
+        set: (items) => {
+          return new Promise((resolve, reject) => {
+            try {
+              if (!isChromeContextValid()) {
+                reject(new Error('Extension context invalidated'));
+                return;
+              }
+              chrome.storage.local.set(items, () => {
+                if (chrome.runtime.lastError) {
+                  reject(new Error(chrome.runtime.lastError.message));
+                } else {
+                  resolve();
+                }
+              });
+            } catch (error) {
+              reject(new Error('Extension context invalidated'));
+            }
+          });
+        },
+        remove: (keys) => {
+          return new Promise((resolve, reject) => {
+            try {
+              if (!isChromeContextValid()) {
+                reject(new Error('Extension context invalidated'));
+                return;
+              }
+              chrome.storage.local.remove(keys, () => {
+                if (chrome.runtime.lastError) {
+                  reject(new Error(chrome.runtime.lastError.message));
+                } else {
+                  resolve();
+                }
+              });
+            } catch (error) {
+              reject(new Error('Extension context invalidated'));
+            }
+          });
+        },
+        clear: () => {
+          return new Promise((resolve, reject) => {
+            try {
+              if (!isChromeContextValid()) {
+                reject(new Error('Extension context invalidated'));
+                return;
+              }
+              chrome.storage.local.clear(() => {
+                if (chrome.runtime.lastError) {
+                  reject(new Error(chrome.runtime.lastError.message));
+                } else {
+                  resolve();
+                }
+              });
+            } catch (error) {
+              reject(new Error('Extension context invalidated'));
+            }
+          });
+        }
+      }
+    },
+    tabs: {
+      query: (queryInfo) => {
+        return new Promise((resolve, reject) => {
+          try {
+            if (!isChromeContextValid()) {
+              reject(new Error('Extension context invalidated'));
+              return;
+            }
+            chrome.tabs.query(queryInfo, (tabs) => {
+              if (chrome.runtime.lastError) {
+                reject(new Error(chrome.runtime.lastError.message));
+              } else {
+                resolve(tabs);
+              }
+            });
+          } catch (error) {
+            reject(new Error('Extension context invalidated'));
+          }
+        });
+      },
+      sendMessage: (tabId, message, callback) => {
+        // If callback is provided, use callback-based API
+        if (typeof callback === 'function') {
+          try {
+            if (!isChromeContextValid()) {
+              console.error('❌ Extension context invalidated');
+              callback(null);
+              return;
+            }
+            chrome.tabs.sendMessage(tabId, message, callback);
+          } catch (error) {
+            // Handle "Extension context invalidated" error in Chrome
+            console.error('❌ Extension context error:', error.message);
+            callback(null);
+          }
+          return;
+        }
+        // Otherwise return a Promise
+        return new Promise((resolve, reject) => {
+          try {
+            if (!isChromeContextValid()) {
+              reject(new Error('Extension context invalidated'));
+              return;
+            }
+            chrome.tabs.sendMessage(tabId, message, (response) => {
+              if (chrome.runtime.lastError) {
+                reject(new Error(chrome.runtime.lastError.message));
+              } else {
+                resolve(response);
+              }
+            });
+          } catch (error) {
+            // Handle "Extension context invalidated" error in Chrome
+            console.error('❌ Extension context error:', error.message);
+            reject(error);
+          }
+        });
+      },
+      create: (createProperties) => {
+        return new Promise((resolve, reject) => {
+          try {
+            if (!isChromeContextValid()) {
+              reject(new Error('Extension context invalidated'));
+              return;
+            }
+            chrome.tabs.create(createProperties, (tab) => {
+              if (chrome.runtime.lastError) {
+                reject(new Error(chrome.runtime.lastError.message));
+              } else {
+                resolve(tab);
+              }
+            });
+          } catch (error) {
+            reject(new Error('Extension context invalidated'));
+          }
+        });
+      },
+      update: (tabId, updateProperties) => {
+        return new Promise((resolve, reject) => {
+          try {
+            if (!isChromeContextValid()) {
+              reject(new Error('Extension context invalidated'));
+              return;
+            }
+            chrome.tabs.update(tabId, updateProperties, (tab) => {
+              if (chrome.runtime.lastError) {
+                reject(new Error(chrome.runtime.lastError.message));
+              } else {
+                resolve(tab);
+              }
+            });
+          } catch (error) {
+            reject(new Error('Extension context invalidated'));
+          }
+        });
+      }
+    }
+  };
+} else {
+  console.error('❌ FATAL: No browser API available!');
+  throw new Error('No browser API available');
+}
+
+// Expose as browserAPI for consistent naming
+globalScope.browserAPI = browserAPI;
+
+// Verify API is available
+if (!globalScope.browserAPI || !globalScope.browserAPI.runtime) {
+  console.error('❌ FATAL: Browser API not available!');
+  throw new Error('Browser API not available');
+}
+
+console.log('✅ Browser API ready:', (typeof browser !== 'undefined' && browserAPI === browser) ? 'Firefox' : 'Chrome');

package/src/common/debug.js

@@ -0,0 +1,123 @@
+/**
+ * Debug Logging Utility
+ *
+ * Centralized logging system that can be enabled/disabled.
+ * In production, debug logs are suppressed to improve performance.
+ * Errors are always logged regardless of debug mode.
+ */
+
+// Debug mode can be controlled by:
+// 1. Build process (set DEBUG = false for production)
+// 2. Extension storage (allow users to enable debug mode)
+// 3. URL parameter (for testing)
+// NOTE: This value is replaced by the build script.
+// - Development builds: DEBUG = true
+// - Production builds: DEBUG = false
+// - Use --dev flag to force DEBUG = true in production build
+const DEBUG = true; // Hardcoded for debugging
+
+/**
+ * Debug logger instance
+ * Provides methods for different log levels
+ */
+const debug = {
+  /**
+   * General debug information
+   * Only logged when DEBUG = true
+   */
+  log: (...args) => {
+    if (DEBUG) {
+      console.log(...args);
+    }
+  },
+
+  /**
+   * Warning messages
+   * Only logged when DEBUG = true
+   */
+  warn: (...args) => {
+    if (DEBUG) {
+      console.warn(...args);
+    }
+  },
+
+  /**
+   * Error messages
+   * ALWAYS logged, regardless of DEBUG mode
+   */
+  error: (...args) => {
+    console.error(...args);
+  },
+
+  /**
+   * Info messages (less noisy than log)
+   * Only logged when DEBUG = true
+   */
+  info: (...args) => {
+    if (DEBUG) {
+      console.info(...args);
+    }
+  },
+
+  /**
+   * Group logs together for better readability
+   * Only when DEBUG = true
+   */
+  group: (label, ...args) => {
+    if (DEBUG) {
+      console.group(label, ...args);
+    }
+  },
+
+  groupEnd: () => {
+    if (DEBUG) {
+      console.groupEnd();
+    }
+  },
+
+  /**
+   * Table output for structured data
+   * Only when DEBUG = true
+   */
+  table: (data) => {
+    if (DEBUG) {
+      console.table(data);
+    }
+  },
+
+  /**
+   * Performance timing
+   * Only when DEBUG = true
+   */
+  time: (label) => {
+    if (DEBUG) {
+      console.time(label);
+    }
+  },
+
+  timeEnd: (label) => {
+    if (DEBUG) {
+      console.timeEnd(label);
+    }
+  },
+
+  /**
+   * Check if debug mode is enabled
+   */
+  isEnabled: () => DEBUG
+};
+
+// Export for use in other modules
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = debug;
+}
+
+// Make available globally for content scripts
+if (typeof window !== 'undefined') {
+  window.debug = debug;
+}
+
+// Make available for service workers
+if (typeof self !== 'undefined' && !self.window) {
+  self.debug = debug;
+}

package/src/common/html-utils.js

@@ -0,0 +1,134 @@
+/**
+ * HTML Utilities
+ * Functions for safe HTML handling and XSS prevention
+ * Configurable for different projects (owlcloud, rollcloud, etc.)
+ */
+
+/**
+ * Escape HTML special characters to prevent XSS
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for innerHTML
+ */
+function escapeHTML(str) {
+  if (!str) return '';
+  if (typeof str !== 'string') str = String(str);
+
+  const div = document.createElement('div');
+  div.textContent = str;
+  return div.innerHTML;
+}
+
+/**
+ * Validate postMessage event origin
+ * @param {MessageEvent} event - The message event
+ * @param {string[]} allowedOrigins - Array of allowed origins (can include * wildcards)
+ * @returns {boolean} True if origin is allowed
+ */
+function validateMessageOrigin(event, allowedOrigins) {
+  if (!event || !event.origin) {
+    debug.warn('❌ Invalid message event or missing origin');
+    return false;
+  }
+
+  const origin = event.origin;
+
+  for (const allowed of allowedOrigins) {
+    // Handle wildcard subdomains (e.g., "https://*.dicecloud.com")
+    if (allowed.includes('*')) {
+      // Convert wildcard to regex pattern
+      const pattern = allowed
+        .replace(/\./g, '\\.')  // Escape dots
+        .replace(/\*/g, '[^.]+'); // * matches subdomain
+      const regex = new RegExp('^' + pattern + '$');
+
+      if (regex.test(origin)) {
+        debug.log('✅ Message origin validated:', origin);
+        return true;
+      }
+    } else {
+      // Exact match
+      if (origin === allowed) {
+        debug.log('✅ Message origin validated:', origin);
+        return true;
+      }
+    }
+  }
+
+  debug.warn('❌ Rejected message from untrusted origin:', origin);
+  return false;
+}
+
+/**
+ * Create configured HTML utilities for a specific project
+ * @param {Object} config - Configuration object
+ * @param {string[]} config.allowedOrigins - Array of allowed origins for postMessage
+ * @param {string} config.defaultOrigin - Default origin for postMessage
+ * @returns {Object} Configured HTML utilities
+ */
+function createHTMLUtils(config = {}) {
+  const allowedOrigins = config.allowedOrigins || [
+    'https://dicecloud.com',
+    'https://*.dicecloud.com'
+  ];
+  const defaultOrigin = config.defaultOrigin || 'https://dicecloud.com';
+
+  return {
+    escapeHTML,
+    validateMessageOrigin,
+    allowedOrigins,
+
+    /**
+     * Safe wrapper for postMessage with explicit origin
+     * @param {Window} target - Target window
+     * @param {*} message - Message to send
+     * @param {string} origin - Target origin (defaults to configured default)
+     */
+    safePostMessage(target, message, origin = defaultOrigin) {
+      if (!target || target.closed) {
+        debug.warn('⚠️ Target window is closed or invalid');
+        return false;
+      }
+
+      try {
+        target.postMessage(message, origin);
+        debug.log('📤 Message sent to:', origin);
+        return true;
+      } catch (error) {
+        debug.error('❌ Failed to send message:', error);
+        return false;
+      }
+    },
+
+    /**
+     * Create a safe message handler with origin validation
+     * @param {Function} handler - Message handler function (receives validated event)
+     * @param {string[]} customAllowedOrigins - Optional custom allowed origins
+     * @returns {Function} Wrapped handler with validation
+     */
+    createSafeMessageHandler(handler, customAllowedOrigins = null) {
+      const origins = customAllowedOrigins || allowedOrigins;
+      return function(event) {
+        if (!validateMessageOrigin(event, origins)) {
+          return; // Reject invalid origins
+        }
+
+        // Call original handler with validated event
+        handler(event);
+      };
+    }
+  };
+}
+
+// Export for use in other modules
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    escapeHTML,
+    validateMessageOrigin,
+    createHTMLUtils
+  };
+}
+
+// Make factory available globally
+if (typeof window !== 'undefined') {
+  window.createHTMLUtils = createHTMLUtils;
+}