pulse-js-framework 1.10.4 → 1.11.1

package/runtime/server-components/types.js

@@ -0,0 +1,383 @@
+/**
+ * Pulse Server Components (PSC) - Type Definitions
+ *
+ * Type definitions for the PSC Wire Format, which is used to serialize
+ * Server Component trees with Client Component boundaries for transmission
+ * from server to client.
+ *
+ * @module pulse-js-framework/runtime/server-components/types
+ */
+
+import { RuntimeError } from '../errors.js';
+
+// ============================================================================
+// PSC Wire Format Types
+// ============================================================================
+
+/**
+ * Complete PSC payload sent from server to client.
+ * Contains the component tree, client component manifest, and optional state.
+ *
+ * @typedef {Object} PSCPayload
+ * @property {string} version - PSC format version (e.g., "1.0")
+ * @property {PSCNode} root - Root node of the component tree
+ * @property {Record<string, ClientManifestEntry>} clientManifest - Mapping of component IDs to chunk URLs
+ * @property {Record<string, any>} [state] - Optional serialized server state
+ *
+ * @example
+ * {
+ *   version: "1.0",
+ *   root: {
+ *     type: 'element',
+ *     tag: 'div',
+ *     props: { class: 'app' },
+ *     children: [
+ *       { type: 'text', value: 'Hello' },
+ *       { type: 'client', id: 'Button', props: { text: 'Click' } }
+ *     ]
+ *   },
+ *   clientManifest: {
+ *     Button: { id: 'Button', chunk: '/assets/Button.js', exports: ['default'] }
+ *   },
+ *   state: { user: { id: 1, name: 'Alice' } }
+ * }
+ */
+
+/**
+ * PSC Node - union type representing any node in the component tree.
+ *
+ * @typedef {PSCElement | PSCText | PSCClientBoundary | PSCFragment | PSCComment} PSCNode
+ */
+
+/**
+ * PSC Element Node - represents a DOM element (e.g., <div>, <span>).
+ *
+ * @typedef {Object} PSCElement
+ * @property {'element'} type - Node type discriminator
+ * @property {string} tag - HTML tag name (e.g., 'div', 'span', 'button')
+ * @property {Record<string, any>} props - Element attributes and properties
+ * @property {PSCNode[]} children - Child nodes
+ *
+ * @example
+ * {
+ *   type: 'element',
+ *   tag: 'div',
+ *   props: { class: 'container', 'data-id': '123' },
+ *   children: [
+ *     { type: 'text', value: 'Content' }
+ *   ]
+ * }
+ */
+
+/**
+ * PSC Text Node - represents a text node.
+ *
+ * @typedef {Object} PSCText
+ * @property {'text'} type - Node type discriminator
+ * @property {string} value - Text content
+ *
+ * @example
+ * { type: 'text', value: 'Hello, world!' }
+ */
+
+/**
+ * PSC Client Boundary - represents a Client Component boundary.
+ * This is a placeholder for a Client Component that will be lazy-loaded
+ * and hydrated on the client side.
+ *
+ * @typedef {Object} PSCClientBoundary
+ * @property {'client'} type - Node type discriminator
+ * @property {string} id - Component ID matching clientManifest key
+ * @property {Record<string, any>} props - Serialized props for the Client Component
+ * @property {PSCNode} [fallback] - Optional fallback UI while loading
+ *
+ * @example
+ * {
+ *   type: 'client',
+ *   id: 'AddToCartButton',
+ *   props: { productId: 123, productName: 'Widget' },
+ *   fallback: {
+ *     type: 'element',
+ *     tag: 'div',
+ *     props: { class: 'skeleton-button' },
+ *     children: []
+ *   }
+ * }
+ */
+
+/**
+ * PSC Fragment - represents a fragment (multiple nodes without a wrapper).
+ *
+ * @typedef {Object} PSCFragment
+ * @property {'fragment'} type - Node type discriminator
+ * @property {PSCNode[]} children - Child nodes
+ *
+ * @example
+ * {
+ *   type: 'fragment',
+ *   children: [
+ *     { type: 'text', value: 'First' },
+ *     { type: 'text', value: 'Second' }
+ *   ]
+ * }
+ */
+
+/**
+ * PSC Comment Node - represents an HTML comment.
+ *
+ * @typedef {Object} PSCComment
+ * @property {'comment'} type - Node type discriminator
+ * @property {string} value - Comment text
+ *
+ * @example
+ * { type: 'comment', value: 'client-only' }
+ */
+
+// ============================================================================
+// Client Manifest Types
+// ============================================================================
+
+/**
+ * Client Manifest Entry - metadata for a Client Component chunk.
+ *
+ * @typedef {Object} ClientManifestEntry
+ * @property {string} id - Component ID (unique identifier)
+ * @property {string} chunk - URL path to the JS chunk (e.g., '/assets/Button.a1b2c3.js')
+ * @property {string[]} exports - Exported names from the chunk (e.g., ['default', 'Button'])
+ *
+ * @example
+ * {
+ *   id: 'ClientButton',
+ *   chunk: '/assets/ClientButton.a1b2c3.js',
+ *   exports: ['default']
+ * }
+ */
+
+// ============================================================================
+// Node Type Constants
+// ============================================================================
+
+/**
+ * Node type constants for PSC Wire Format.
+ * Use these instead of string literals for type safety.
+ */
+export const PSCNodeType = {
+  ELEMENT: 'element',
+  TEXT: 'text',
+  CLIENT: 'client',
+  FRAGMENT: 'fragment',
+  COMMENT: 'comment'
+};
+
+/**
+ * PSC format version.
+ */
+export const PSC_VERSION = '1.0';
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Check if a PSC node is an element node.
+ *
+ * @param {PSCNode} node - Node to check
+ * @returns {node is PSCElement}
+ *
+ * @example
+ * if (isPSCElement(node)) {
+ *   console.log('Tag:', node.tag);
+ * }
+ */
+export function isPSCElement(node) {
+  return node && node.type === PSCNodeType.ELEMENT;
+}
+
+/**
+ * Check if a PSC node is a text node.
+ *
+ * @param {PSCNode} node - Node to check
+ * @returns {node is PSCText}
+ */
+export function isPSCText(node) {
+  return node && node.type === PSCNodeType.TEXT;
+}
+
+/**
+ * Check if a PSC node is a client boundary.
+ *
+ * @param {PSCNode} node - Node to check
+ * @returns {node is PSCClientBoundary}
+ */
+export function isPSCClientBoundary(node) {
+  return node && node.type === PSCNodeType.CLIENT;
+}
+
+/**
+ * Check if a PSC node is a fragment.
+ *
+ * @param {PSCNode} node - Node to check
+ * @returns {node is PSCFragment}
+ */
+export function isPSCFragment(node) {
+  return node && node.type === PSCNodeType.FRAGMENT;
+}
+
+/**
+ * Check if a PSC node is a comment.
+ *
+ * @param {PSCNode} node - Node to check
+ * @returns {node is PSCComment}
+ */
+export function isPSCComment(node) {
+  return node && node.type === PSCNodeType.COMMENT;
+}
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Validate a PSC payload structure.
+ *
+ * @param {any} payload - Payload to validate
+ * @returns {boolean} True if valid PSC payload
+ * @throws {RuntimeError} If validation fails with detailed error message
+ *
+ * @example
+ * try {
+ *   validatePSCPayload(payload);
+ *   // Payload is valid
+ * } catch (err) {
+ *   console.error('Invalid PSC payload:', err.message);
+ * }
+ */
+export function validatePSCPayload(payload) {
+  if (!payload || typeof payload !== 'object') {
+    throw new RuntimeError('PSC payload must be an object', { code: 'PSC_VALIDATION_ERROR' });
+  }
+
+  if (!payload.version || typeof payload.version !== 'string') {
+    throw new RuntimeError('PSC payload must have a version string', { code: 'PSC_VALIDATION_ERROR' });
+  }
+
+  if (!payload.root) {
+    throw new RuntimeError('PSC payload must have a root node', { code: 'PSC_VALIDATION_ERROR' });
+  }
+
+  if (!payload.clientManifest || typeof payload.clientManifest !== 'object') {
+    throw new RuntimeError('PSC payload must have a clientManifest object', { code: 'PSC_VALIDATION_ERROR' });
+  }
+
+  // Validate root node structure
+  validatePSCNode(payload.root);
+
+  // Validate client manifest entries
+  for (const [key, entry] of Object.entries(payload.clientManifest)) {
+    if (!entry.id || typeof entry.id !== 'string') {
+      throw new RuntimeError(`Client manifest entry '${key}' missing id`, { code: 'PSC_VALIDATION_ERROR' });
+    }
+    if (!entry.chunk || typeof entry.chunk !== 'string') {
+      throw new RuntimeError(`Client manifest entry '${key}' missing chunk URL`, { code: 'PSC_VALIDATION_ERROR' });
+    }
+    if (!Array.isArray(entry.exports)) {
+      throw new RuntimeError(`Client manifest entry '${key}' missing exports array`, { code: 'PSC_VALIDATION_ERROR' });
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Validate a PSC node structure (recursive).
+ *
+ * @param {PSCNode} node - Node to validate
+ * @param {number} [depth=0] - Current recursion depth (for cycle detection)
+ * @returns {boolean} True if valid
+ * @throws {RuntimeError} If validation fails
+ */
+export function validatePSCNode(node, depth = 0) {
+  if (depth > 100) {
+    throw new RuntimeError('PSC node tree too deep (max 100 levels)', { code: 'PSC_VALIDATION_ERROR' });
+  }
+
+  if (!node || typeof node !== 'object') {
+    throw new RuntimeError('PSC node must be an object', { code: 'PSC_VALIDATION_ERROR' });
+  }
+
+  if (!node.type) {
+    throw new RuntimeError('PSC node missing type property', { code: 'PSC_VALIDATION_ERROR' });
+  }
+
+  switch (node.type) {
+    case PSCNodeType.ELEMENT:
+      if (!node.tag || typeof node.tag !== 'string') {
+        throw new RuntimeError('PSC element missing tag', { code: 'PSC_VALIDATION_ERROR' });
+      }
+      if (node.props && typeof node.props !== 'object') {
+        throw new RuntimeError('PSC element props must be an object', { code: 'PSC_VALIDATION_ERROR' });
+      }
+      if (!Array.isArray(node.children)) {
+        throw new RuntimeError('PSC element children must be an array', { code: 'PSC_VALIDATION_ERROR' });
+      }
+      // Validate children recursively
+      for (const child of node.children) {
+        validatePSCNode(child, depth + 1);
+      }
+      break;
+
+    case PSCNodeType.TEXT:
+      if (typeof node.value !== 'string') {
+        throw new RuntimeError('PSC text node must have a string value', { code: 'PSC_VALIDATION_ERROR' });
+      }
+      break;
+
+    case PSCNodeType.CLIENT:
+      if (!node.id || typeof node.id !== 'string') {
+        throw new RuntimeError('PSC client boundary missing id', { code: 'PSC_VALIDATION_ERROR' });
+      }
+      if (node.props && typeof node.props !== 'object') {
+        throw new RuntimeError('PSC client boundary props must be an object', { code: 'PSC_VALIDATION_ERROR' });
+      }
+      if (node.fallback) {
+        validatePSCNode(node.fallback, depth + 1);
+      }
+      break;
+
+    case PSCNodeType.FRAGMENT:
+      if (!Array.isArray(node.children)) {
+        throw new RuntimeError('PSC fragment children must be an array', { code: 'PSC_VALIDATION_ERROR' });
+      }
+      for (const child of node.children) {
+        validatePSCNode(child, depth + 1);
+      }
+      break;
+
+    case PSCNodeType.COMMENT:
+      if (typeof node.value !== 'string') {
+        throw new RuntimeError('PSC comment must have a string value', { code: 'PSC_VALIDATION_ERROR' });
+      }
+      break;
+
+    default:
+      throw new RuntimeError(`Unknown PSC node type: ${node.type}`, { code: 'PSC_VALIDATION_ERROR' });
+  }
+
+  return true;
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default {
+  PSCNodeType,
+  PSC_VERSION,
+  isPSCElement,
+  isPSCText,
+  isPSCClientBoundary,
+  isPSCFragment,
+  isPSCComment,
+  validatePSCPayload,
+  validatePSCNode
+};

package/runtime/server-components/utils/mutex.js

@@ -0,0 +1,60 @@
+/**
+ * Simple Mutex (Mutual Exclusion) Lock
+ *
+ * Provides exclusive access to critical sections to prevent race conditions.
+ * Uses a queue-based approach with promises for async/await compatibility.
+ *
+ * @module pulse-js-framework/runtime/server-components/utils/mutex
+ */
+
+/**
+ * Create a mutex lock for protecting critical sections
+ *
+ * @returns {Object} Mutex instance with lock() method
+ *
+ * @example
+ * const mutex = createMutex();
+ *
+ * await mutex.lock(async () => {
+ *   // Critical section - only one caller at a time
+ *   await someAsyncOperation();
+ * });
+ */
+export function createMutex() {
+  // Promise-chain pattern: the ONLY correct way to implement mutex in JavaScript
+  // Each lock() captures the current chain, updates it to their own promise,
+  // then waits for the previous chain before executing
+  let chain = Promise.resolve();
+
+  return {
+    /**
+     * Execute function with exclusive lock
+     *
+     * @param {Function} fn - Function to execute (can be async)
+     * @returns {Promise<any>} Result of the function
+     */
+    lock(fn) {
+      // Create completion promise
+      let unlock;
+      const ready = new Promise(resolve => {
+        unlock = resolve;
+      });
+
+      // CRITICAL: These two lines MUST be synchronous (no await between them)
+      // to prevent race conditions
+      const prevChain = chain;  // Capture current chain
+      chain = ready;             // Update chain to our promise
+
+      // Return a promise that waits for previous, executes, then unlocks
+      return prevChain.then(async () => {
+        try {
+          return await fn();
+        } finally {
+          unlock();  // Release next waiter
+        }
+      });
+    }
+  };
+}
+
+export default { createMutex };

package/runtime/server-components/utils/path-sanitizer.js

@@ -0,0 +1,109 @@
+/**
+ * Path Sanitization Utilities
+ *
+ * Prevents path traversal attacks by validating and normalizing file paths.
+ * Ensures paths stay within the project directory.
+ *
+ * @module pulse-js-framework/runtime/server-components/utils/path-sanitizer
+ */
+
+import { resolve, normalize, relative, isAbsolute } from 'path';
+
+/**
+ * Sanitize and validate an import path to prevent traversal attacks
+ *
+ * Security checks:
+ * 1. Normalizes path to remove ../ sequences
+ * 2. Resolves to absolute path
+ * 3. Ensures result is within basePath (no escaping project directory)
+ * 4. Blocks absolute paths that bypass basePath
+ *
+ * @param {string} importPath - Path to sanitize (possibly malicious)
+ * @param {string} basePath - Base directory that paths must stay within
+ * @returns {string} Sanitized absolute path
+ * @throws {Error} If path attempts to escape basePath
+ *
+ * @example
+ * // Safe path
+ * sanitizeImportPath('./components/Button.js', '/project')
+ * // → '/project/components/Button.js'
+ *
+ * // Path traversal attempt - THROWS
+ * sanitizeImportPath('../../../etc/passwd', '/project')
+ * // → Error: Invalid import path
+ */
+export function sanitizeImportPath(importPath, basePath) {
+  if (!importPath || typeof importPath !== 'string') {
+    throw new Error('Invalid import path: path must be a non-empty string');
+  }
+
+  if (!basePath || typeof basePath !== 'string') {
+    throw new Error('Invalid base path: basePath must be a non-empty string');
+  }
+
+  // SECURITY: Block Windows absolute paths on Unix systems (e.g., C:\...)
+  // These could bypass path checks on cross-platform builds
+  if (/^[A-Za-z]:\\/.test(importPath)) {
+    throw new Error(
+      `Invalid import path: "${importPath}" attempts to use absolute Windows path`
+    );
+  }
+
+  // Normalize to remove ../ and ./ sequences
+  const normalized = normalize(importPath);
+
+  // Resolve to absolute path relative to basePath
+  const resolved = resolve(basePath, normalized);
+
+  // Get relative path from basePath to resolved path
+  const rel = relative(basePath, resolved);
+
+  // Check if path escapes basePath
+  // - If rel starts with '..', it's outside basePath
+  // - If rel is absolute, it bypassed basePath
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(
+      `Invalid import path: "${importPath}" attempts to escape project directory`
+    );
+  }
+
+  return resolved;
+}
+
+/**
+ * Sanitize multiple import paths
+ *
+ * @param {string[]} paths - Array of paths to sanitize
+ * @param {string} basePath - Base directory
+ * @returns {string[]} Array of sanitized paths
+ * @throws {Error} If any path is invalid
+ */
+export function sanitizeImportPaths(paths, basePath) {
+  if (!Array.isArray(paths)) {
+    throw new Error('Invalid paths: must be an array');
+  }
+
+  return paths.map(path => sanitizeImportPath(path, basePath));
+}
+
+/**
+ * Check if a path is safe (within basePath) without throwing
+ *
+ * @param {string} importPath - Path to check
+ * @param {string} basePath - Base directory
+ * @returns {boolean} True if path is safe
+ */
+export function isPathSafe(importPath, basePath) {
+  try {
+    sanitizeImportPath(importPath, basePath);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+export default {
+  sanitizeImportPath,
+  sanitizeImportPaths,
+  isPathSafe
+};

package/runtime/ssr.js

@@ -50,6 +50,7 @@ import {
   getHydrationContext
 } from './ssr-hydrator.js';
 import { loggers } from './logger.js';
+import { DOMError } from './errors.js';
 
 const log = loggers.dom;
 
@@ -277,7 +278,7 @@ export function hydrate(target, componentFactory, options = {}) {
     : target;
 
   if (!container) {
-    throw new Error(`[Pulse SSR] Hydration target not found: ${target}`);
+    throw new DOMError(`Hydration target not found: ${target}`, { code: 'MOUNT_ERROR', suggestion: `Ensure an element matching '${target}' exists in the DOM` });
   }
 
   // Restore state if provided

package/runtime/store.js

@@ -18,6 +18,7 @@
 import { pulse, computed, effect, batch } from './pulse.js';
 import { loggers, createLogger } from './logger.js';
 import { Errors, createErrorMessage } from './errors.js';
+import { DANGEROUS_KEYS } from './security.js';
 
 const log = loggers.store;
 
@@ -53,11 +54,7 @@ const MAX_NESTING_DEPTH = 10;
  * @typedef {function(Store): Store} StorePlugin
  */
 
-/**
- * Dangerous property names that could cause prototype pollution
- * @type {Set<string>}
- */
-const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+// DANGEROUS_KEYS imported from security.js (single source of truth — 16 entries)
 
 /**
  * Invalid value types that cannot be stored in state
@@ -74,7 +71,7 @@ const INVALID_TYPES = new Set(['function', 'symbol']);
  * Uses WeakMap to allow garbage collection of unreferenced objects
  * @type {WeakMap<Object, {keys: string[], values: any[]}>}
  */
-const _validationCache = new WeakMap();
+let _validationCache = new WeakMap();
 
 /**
  * Check shallow equality between cached and current object
@@ -110,9 +107,7 @@ function _cacheObject(obj) {
  * @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
+  _validationCache = new WeakMap();
 }
 
 /**
@@ -452,6 +447,20 @@ export function createStore(initialState = {}, options = {}) {
     });
   }
 
+  /**
+   * Get a tracked snapshot of the current state (registers reactive dependencies).
+   * Unlike getState() which uses peek(), this uses get() so effects re-run on changes.
+   * @private
+   * @returns {Object} Plain object with current values
+   */
+  function getTrackedState() {
+    const snapshot = {};
+    for (const [key, p] of Object.entries(pulses)) {
+      snapshot[key] = p.get();
+    }
+    return snapshot;
+  }
+
   /**
    * Subscribe to all state changes
    * @param {function(Object): void} callback - Called with current state on each change
@@ -459,7 +468,7 @@ export function createStore(initialState = {}, options = {}) {
    */
   function subscribe(callback) {
     return effect(() => {
-      const state = getState();
+      const state = getTrackedState();
       callback(state);
     });
   }