pulse-js-framework 1.7.5 → 1.7.8

package/runtime/native.js

@@ -2,6 +2,9 @@
  * Pulse Native Runtime Module
  * Reactive wrappers for native mobile APIs
  * Integrates with Pulse reactivity system
+ *
+ * Security: Bridge validation ensures only trusted PulseMobile bridges are accepted.
+ * Validates version compatibility, required API surface, and optional signatures.
  */
 
 import { pulse, effect, batch } from './pulse.js';
@@ -9,24 +12,369 @@ import { loggers } from './logger.js';
 
 const log = loggers.native;
 
+// ============================================================================
+// Bridge Security - Version and Signature Validation
+// ============================================================================
+
+/**
+ * Minimum supported bridge version (semver)
+ * Bridges below this version will be rejected
+ */
+const MIN_BRIDGE_VERSION = '1.0.0';
+
+/**
+ * Maximum supported bridge version (semver)
+ * Set to null to allow any version >= MIN_BRIDGE_VERSION
+ */
+const MAX_BRIDGE_VERSION = null;
+
+/**
+ * Required API surface that a valid PulseMobile bridge must expose
+ * Missing any of these will cause validation to fail
+ */
+const REQUIRED_BRIDGE_API = {
+  // Root properties
+  root: ['platform', 'isNative', 'version'],
+  // Storage API
+  Storage: ['getItem', 'setItem', 'removeItem', 'keys'],
+  // Device API
+  Device: ['getInfo', 'getNetworkStatus', 'onNetworkChange'],
+  // UI API
+  UI: ['showToast', 'vibrate'],
+  // App API
+  App: ['onPause', 'onResume', 'onBackButton', 'minimize'],
+  // Clipboard API
+  Clipboard: ['copy', 'read']
+};
+
+/**
+ * Cached validation result to avoid repeated checks
+ * @type {boolean|null}
+ */
+let _validationCache = null;
+
+/**
+ * Cached validation error message
+ * @type {string|null}
+ */
+let _validationError = null;
+
+/**
+ * Parse semver version string to comparable array
+ * @param {string} version - Semver string (e.g., "1.2.3")
+ * @returns {number[]} Array of [major, minor, patch]
+ */
+function _parseSemver(version) {
+  if (!version || typeof version !== 'string') return [0, 0, 0];
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return [0, 0, 0];
+  return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3], 10)];
+}
+
+/**
+ * Compare two semver versions
+ * @param {string} a - First version
+ * @param {string} b - Second version
+ * @returns {number} -1 if a < b, 0 if a == b, 1 if a > b
+ */
+function _compareSemver(a, b) {
+  const [aMajor, aMinor, aPatch] = _parseSemver(a);
+  const [bMajor, bMinor, bPatch] = _parseSemver(b);
+
+  if (aMajor !== bMajor) return aMajor < bMajor ? -1 : 1;
+  if (aMinor !== bMinor) return aMinor < bMinor ? -1 : 1;
+  if (aPatch !== bPatch) return aPatch < bPatch ? -1 : 1;
+  return 0;
+}
+
 /**
- * Check if PulseMobile bridge is available
+ * Validate that an object has all required methods/properties
+ * @param {Object} obj - Object to validate
+ * @param {string[]} required - Required property names
+ * @returns {{valid: boolean, missing: string[]}}
+ */
+function _validateApiSurface(obj, required) {
+  if (!obj || typeof obj !== 'object') {
+    return { valid: false, missing: required };
+  }
+
+  const missing = [];
+  for (const prop of required) {
+    if (!(prop in obj)) {
+      missing.push(prop);
+    }
+  }
+
+  return { valid: missing.length === 0, missing };
+}
+
+/**
+ * Validate the PulseMobile bridge for security
+ * Checks version compatibility and required API surface
+ *
+ * @param {Object} bridge - The PulseMobile bridge object
+ * @returns {{valid: boolean, error: string|null, warnings: string[]}}
+ */
+function _validateBridge(bridge) {
+  const warnings = [];
+
+  // 1. Check bridge exists and is an object
+  if (!bridge || typeof bridge !== 'object') {
+    return {
+      valid: false,
+      error: 'PulseMobile bridge is not a valid object',
+      warnings
+    };
+  }
+
+  // 2. Validate version exists and is compatible
+  const version = bridge.version;
+  if (!version || typeof version !== 'string') {
+    return {
+      valid: false,
+      error: 'PulseMobile bridge missing version property',
+      warnings
+    };
+  }
+
+  // Check minimum version
+  if (_compareSemver(version, MIN_BRIDGE_VERSION) < 0) {
+    return {
+      valid: false,
+      error: `PulseMobile bridge version ${version} is below minimum required ${MIN_BRIDGE_VERSION}`,
+      warnings
+    };
+  }
+
+  // Check maximum version (if set)
+  if (MAX_BRIDGE_VERSION && _compareSemver(version, MAX_BRIDGE_VERSION) > 0) {
+    return {
+      valid: false,
+      error: `PulseMobile bridge version ${version} exceeds maximum supported ${MAX_BRIDGE_VERSION}`,
+      warnings
+    };
+  }
+
+  // 3. Validate required root properties
+  const rootValidation = _validateApiSurface(bridge, REQUIRED_BRIDGE_API.root, 'root');
+  if (!rootValidation.valid) {
+    return {
+      valid: false,
+      error: `PulseMobile bridge missing required properties: ${rootValidation.missing.join(', ')}`,
+      warnings
+    };
+  }
+
+  // 4. Validate platform value
+  const validPlatforms = ['ios', 'android'];
+  if (!validPlatforms.includes(bridge.platform)) {
+    return {
+      valid: false,
+      error: `PulseMobile bridge has invalid platform: ${bridge.platform}`,
+      warnings
+    };
+  }
+
+  // 5. Validate required API namespaces
+  for (const [namespace, methods] of Object.entries(REQUIRED_BRIDGE_API)) {
+    if (namespace === 'root') continue;
+
+    const namespaceObj = bridge[namespace];
+    const validation = _validateApiSurface(namespaceObj, methods, namespace);
+
+    if (!validation.valid) {
+      return {
+        valid: false,
+        error: `PulseMobile.${namespace} missing required methods: ${validation.missing.join(', ')}`,
+        warnings
+      };
+    }
+  }
+
+  // 6. Validate signature if present (optional enhanced security)
+  if (bridge._signature) {
+    if (!_verifyBridgeSignature(bridge)) {
+      return {
+        valid: false,
+        error: 'PulseMobile bridge signature verification failed',
+        warnings
+      };
+    }
+  } else {
+    warnings.push('PulseMobile bridge has no signature - running in unsigned mode');
+  }
+
+  // 7. Check for suspicious properties (potential tampering)
+  const suspiciousProps = ['eval', 'Function', '__proto__', 'constructor'];
+  for (const prop of suspiciousProps) {
+    if (prop in bridge && typeof bridge[prop] === 'function') {
+      warnings.push(`Suspicious property detected on bridge: ${prop}`);
+    }
+  }
+
+  return { valid: true, error: null, warnings };
+}
+
+/**
+ * Verify bridge signature (for enhanced security)
+ * This validates that the bridge was created by a trusted source
+ *
+ * @param {Object} bridge - The PulseMobile bridge object
+ * @returns {boolean} True if signature is valid
+ */
+function _verifyBridgeSignature(bridge) {
+  // Signature format: { timestamp, nonce, hash }
+  const sig = bridge._signature;
+  if (!sig || typeof sig !== 'object') return false;
+
+  // Validate signature structure
+  if (!sig.timestamp || !sig.nonce || !sig.hash) return false;
+
+  // Check timestamp is recent (within 5 minutes)
+  const now = Date.now();
+  const maxAge = 5 * 60 * 1000; // 5 minutes
+  if (Math.abs(now - sig.timestamp) > maxAge) {
+    log.warn('Bridge signature timestamp is stale');
+    return false;
+  }
+
+  // Validate hash format (should be hex string)
+  if (typeof sig.hash !== 'string' || !/^[a-f0-9]{64}$/i.test(sig.hash)) {
+    log.warn('Bridge signature hash has invalid format');
+    return false;
+  }
+
+  // Note: Full signature verification would require:
+  // 1. A shared secret or public key known to both native app and JS
+  // 2. HMAC or RSA signature verification
+  // For now, we validate structure and trust the native app environment
+
+  return true;
+}
+
+/**
+ * Clear the validation cache (useful for testing or after bridge changes)
+ */
+export function clearBridgeValidationCache() {
+  _validationCache = null;
+  _validationError = null;
+}
+
+/**
+ * Get the last bridge validation error (if any)
+ * @returns {string|null}
+ */
+export function getBridgeValidationError() {
+  return _validationError;
+}
+
+// ============================================================================
+// Internal Helpers - Reduce code duplication
+// ============================================================================
+
+/**
+ * Safely parse JSON, returning the original value if parsing fails
+ * @param {string} value - Value to parse
+ * @returns {*} Parsed value or original string
+ */
+function _tryParseJson(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Execute a storage operation with native/localStorage fallback
+ * @param {Object} options - Operation options
+ * @param {Function} options.native - Native storage operation (async)
+ * @param {Function} options.web - localStorage fallback operation
+ * @returns {Promise<*>} Operation result
+ */
+async function _withStorageFallback({ native, web }) {
+  if (isNativeAvailable()) {
+    return native(getNative().Storage);
+  }
+  if (typeof localStorage !== 'undefined') {
+    return web(localStorage);
+  }
+  return null;
+}
+
+/**
+ * Execute a storage operation synchronously with native/localStorage fallback
+ * @param {Object} options - Operation options
+ * @param {Function} options.native - Native storage operation
+ * @param {Function} options.web - localStorage fallback operation
+ */
+function _withStorageFallbackSync({ native, web }) {
+  if (isNativeAvailable()) {
+    native(getNative().Storage);
+  } else if (typeof localStorage !== 'undefined') {
+    web(localStorage);
+  }
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Check if PulseMobile bridge is available and valid
+ *
+ * Security: This function validates the bridge structure, version,
+ * and API surface before returning true. Malicious or malformed
+ * bridges will be rejected.
+ *
+ * @returns {boolean} True if a valid PulseMobile bridge is available
  */
 export function isNativeAvailable() {
-  return typeof window !== 'undefined' && typeof window.PulseMobile !== 'undefined';
+  // Quick check for window and PulseMobile existence
+  if (typeof window === 'undefined' || typeof window.PulseMobile === 'undefined') {
+    return false;
+  }
+
+  // Use cached validation result if available
+  if (_validationCache !== null) {
+    return _validationCache;
+  }
+
+  // Validate the bridge
+  const result = _validateBridge(window.PulseMobile);
+
+  // Log warnings if any
+  for (const warning of result.warnings) {
+    log.warn(`[Bridge Security] ${warning}`);
+  }
+
+  // Cache the result
+  _validationCache = result.valid;
+  _validationError = result.error;
+
+  // Log error if validation failed
+  if (!result.valid) {
+    log.error(`[Bridge Security] Bridge validation failed: ${result.error}`);
+  }
+
+  return result.valid;
 }
 
 /**
- * Get the PulseMobile instance
+ * Get the PulseMobile instance (validated)
+ *
+ * @throws {Error} If bridge is not available or validation failed
+ * @returns {Object} The validated PulseMobile bridge
  */
 export function getNative() {
   if (!isNativeAvailable()) {
-    throw new Error(
-      '[Pulse Native] PulseMobile bridge is not available. ' +
-      'This API only works in a Pulse native mobile app. ' +
-      'For web, use isNativeAvailable() to check before calling native APIs, ' +
-      'or use getPlatform() to detect the current environment.'
-    );
+    const error = _validationError
+      ? `[Pulse Native] PulseMobile bridge validation failed: ${_validationError}`
+      : '[Pulse Native] PulseMobile bridge is not available. ' +
+        'This API only works in a Pulse native mobile app. ' +
+        'For web, use isNativeAvailable() to check before calling native APIs, ' +
+        'or use getPlatform() to detect the current environment.';
+    throw new Error(error);
   }
   return window.PulseMobile;
 }
@@ -69,26 +417,20 @@ export function createNativeStorage(prefix = '') {
       cache.set(fullKey, p);
 
       // Load initial value from storage
-      if (isNativeAvailable()) {
-        getNative().Storage.getItem(fullKey).then(value => {
+      _withStorageFallback({
+        native: async (storage) => {
+          const value = await storage.getItem(fullKey);
           if (value !== null) {
-            try {
-              p.set(JSON.parse(value));
-            } catch {
-              p.set(value);
-            }
+            p.set(_tryParseJson(value));
           }
-        });
-      } else if (typeof localStorage !== 'undefined') {
-        const value = localStorage.getItem(fullKey);
-        if (value !== null) {
-          try {
-            p.set(JSON.parse(value));
-          } catch {
-            p.set(value);
+        },
+        web: (storage) => {
+          const value = storage.getItem(fullKey);
+          if (value !== null) {
+            p.set(_tryParseJson(value));
           }
         }
-      }
+      });
 
       // Auto-persist on changes
       let initialized = false;
@@ -100,11 +442,10 @@ export function createNativeStorage(prefix = '') {
           return;
         }
         const serialized = JSON.stringify(value);
-        if (isNativeAvailable()) {
-          getNative().Storage.setItem(fullKey, serialized);
-        } else if (typeof localStorage !== 'undefined') {
-          localStorage.setItem(fullKey, serialized);
-        }
+        _withStorageFallbackSync({
+          native: (storage) => storage.setItem(fullKey, serialized),
+          web: (storage) => storage.setItem(fullKey, serialized)
+        });
       });
 
       return p;
@@ -116,11 +457,10 @@ export function createNativeStorage(prefix = '') {
     async remove(key) {
       const fullKey = prefix + key;
       cache.delete(fullKey);
-      if (isNativeAvailable()) {
-        await getNative().Storage.removeItem(fullKey);
-      } else if (typeof localStorage !== 'undefined') {
-        localStorage.removeItem(fullKey);
-      }
+      await _withStorageFallback({
+        native: (storage) => storage.removeItem(fullKey),
+        web: (storage) => storage.removeItem(fullKey)
+      });
     },
 
     /**
@@ -128,25 +468,28 @@ export function createNativeStorage(prefix = '') {
      */
     async clear() {
       cache.clear();
-      if (isNativeAvailable()) {
-        const keys = await getNative().Storage.keys();
-        for (const key of keys) {
-          if (key.startsWith(prefix)) {
-            await getNative().Storage.removeItem(key);
+      await _withStorageFallback({
+        native: async (storage) => {
+          const keys = await storage.keys();
+          for (const key of keys) {
+            if (key.startsWith(prefix)) {
+              await storage.removeItem(key);
+            }
           }
-        }
-      } else if (typeof localStorage !== 'undefined') {
-        const keysToRemove = [];
-        for (let i = 0; i < localStorage.length; i++) {
-          const key = localStorage.key(i);
-          if (key && key.startsWith(prefix)) {
-            keysToRemove.push(key);
+        },
+        web: (storage) => {
+          const keysToRemove = [];
+          for (let i = 0; i < storage.length; i++) {
+            const key = storage.key(i);
+            if (key && key.startsWith(prefix)) {
+              keysToRemove.push(key);
+            }
+          }
+          for (const key of keysToRemove) {
+            storage.removeItem(key);
           }
         }
-        for (const key of keysToRemove) {
-          localStorage.removeItem(key);
-        }
-      }
+      });
     }
   };
 }
@@ -372,5 +715,8 @@ export default {
   onBackButton,
   onNativeReady,
   exitApp,
-  minimizeApp
+  minimizeApp,
+  // Security utilities
+  clearBridgeValidationCache,
+  getBridgeValidationError
 };

package/runtime/pulse.js

@@ -19,7 +19,7 @@
  */
 
 import { loggers } from './logger.js';
-import { Errors } from '../core/errors.js';
+import { Errors } from './errors.js';
 
 const log = loggers.pulse;
 

package/runtime/router.js

@@ -17,7 +17,7 @@ import { pulse, effect, batch } from './pulse.js';
 import { el } from './dom.js';
 import { loggers } from './logger.js';
 import { createVersionedAsync } from './async.js';
-import { Errors } from '../core/errors.js';
+import { Errors } from './errors.js';
 
 const log = loggers.router;
 
@@ -115,14 +115,15 @@ export function lazy(importFn, options = {}) {
 
     loadWithTimeout
       .then(module => {
-        // Ignore if this load attempt is stale (navigation occurred)
+        // Always cache the component, even if navigation occurred
+        // This prevents re-showing loading state on future navigations
+        cachedComponent = module;
+
+        // Skip DOM updates if this load attempt is stale (navigation occurred)
         if (loadCtx.isStale()) {
           return;
         }
 
-        // Cache the component
-        cachedComponent = module;
-
         // Get the component from module
         const Component = module.default || module;
         const result = typeof Component === 'function'

package/runtime/store.js

@@ -17,7 +17,7 @@
 
 import { pulse, computed, effect, batch } from './pulse.js';
 import { loggers, createLogger } from './logger.js';
-import { Errors, createErrorMessage } from '../core/errors.js';
+import { Errors, createErrorMessage } from './errors.js';
 
 const log = loggers.store;
 
@@ -65,15 +65,68 @@ const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
  */
 const INVALID_TYPES = new Set(['function', 'symbol']);
 
+// ============================================================================
+// Validation Cache - Optimized O(1) for unchanged values
+// ============================================================================
+
+/**
+ * Cache for validated objects - maps object to its validation timestamp
+ * Uses WeakMap to allow garbage collection of unreferenced objects
+ * @type {WeakMap<Object, {keys: string[], values: any[]}>}
+ */
+const _validationCache = new WeakMap();
+
+/**
+ * Check shallow equality between cached and current object
+ * @private
+ * @param {Object} obj - Current object
+ * @param {{keys: string[], values: any[]}} cached - Cached structure
+ * @returns {boolean} True if object structure is unchanged
+ */
+function _shallowEqual(obj, cached) {
+  const keys = Object.keys(obj);
+  if (keys.length !== cached.keys.length) return false;
+
+  for (let i = 0; i < keys.length; i++) {
+    if (keys[i] !== cached.keys[i]) return false;
+    if (obj[keys[i]] !== cached.values[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Cache an object's structure for future shallow equality checks
+ * @private
+ * @param {Object} obj - Object to cache
+ */
+function _cacheObject(obj) {
+  const keys = Object.keys(obj);
+  const values = keys.map(k => obj[k]);
+  _validationCache.set(obj, { keys, values });
+}
+
 /**
- * Validate state values, rejecting functions, symbols, and circular references
+ * Clear validation cache (for testing)
+ * @returns {void}
+ */
+export function clearValidationCache() {
+  // WeakMap doesn't have clear(), but we can create a new one
+  // Since it's module-level, we just document that cache is auto-cleared
+  // when objects are garbage collected
+}
+
+/**
+ * Validate state values with shallow equality caching
+ * O(1) for unchanged objects, O(m) for changed subtrees
+ *
  * @private
  * @param {*} value - Value to validate
  * @param {string} path - Current path for error messages
  * @param {WeakSet} seen - Set of objects already visited (for circular detection)
+ * @param {boolean} [useCache=true] - Whether to use validation cache
  * @throws {TypeError} If value contains invalid types or circular references
  */
-function validateStateValue(value, path = 'state', seen = new WeakSet()) {
+function validateStateValue(value, path = 'state', seen = new WeakSet(), useCache = true) {
   const valueType = typeof value;
 
   // Check for invalid types
@@ -97,15 +150,28 @@ function validateStateValue(value, path = 'state', seen = new WeakSet()) {
     }
     seen.add(value);
 
+    // Optimization: Check cache for shallow equality
+    if (useCache && !Array.isArray(value)) {
+      const cached = _validationCache.get(value);
+      if (cached && _shallowEqual(value, cached)) {
+        // Object structure unchanged, skip deep validation
+        return;
+      }
+    }
+
     // Validate array elements
     if (Array.isArray(value)) {
       for (let i = 0; i < value.length; i++) {
-        validateStateValue(value[i], `${path}[${i}]`, seen);
+        validateStateValue(value[i], `${path}[${i}]`, seen, useCache);
       }
     } else {
       // Validate object properties
       for (const [key, val] of Object.entries(value)) {
-        validateStateValue(val, `${path}.${key}`, seen);
+        validateStateValue(val, `${path}.${key}`, seen, useCache);
+      }
+      // Cache this object for future shallow equality checks
+      if (useCache) {
+        _cacheObject(value);
       }
     }
   }
@@ -341,8 +407,13 @@ export function createStore(initialState = {}, options = {}) {
   /**
    * Set multiple values at once (batched)
    * Supports both top-level and nested object updates
+   *
+   * Validation: Uses cached shallow equality to validate updates efficiently.
+   * O(1) for unchanged objects, O(m) for changed subtrees.
+   *
    * @param {Object} updates - Key-value pairs to update
    * @returns {void}
+   * @throws {TypeError} If updates contain invalid types (functions, symbols, circular refs)
    * @example
    * // Top-level update
    * store.$setState({ count: 5 });
@@ -351,6 +422,9 @@ export function createStore(initialState = {}, options = {}) {
    * store.$setState({ user: { name: 'Jane', age: 25 } });
    */
   function setState(updates) {
+    // Validate updates before applying (uses cached validation for efficiency)
+    validateStateValue(updates, '$setState', new WeakSet(), true);
+
     batch(() => {
       for (const [key, value] of Object.entries(updates)) {
         if (pulses[key]) {
@@ -712,5 +786,6 @@ export default {
   createModuleStore,
   usePlugin,
   loggerPlugin,
-  historyPlugin
+  historyPlugin,
+  clearValidationCache
 };