pulse-js-framework 1.10.4 → 1.11.1

package/runtime/router/psc-integration.js

@@ -0,0 +1,301 @@
+/**
+ * PSC Integration for Router - Pulse Framework
+ *
+ * Handles Server Component navigation, caching, and prefetching.
+ * Provides client-side navigation with Server Component updates via PSC Wire Format.
+ *
+ * @module runtime/router/psc-integration
+ */
+
+import { reconstructPSCTree } from '../server-components/index.js';
+
+// ============================================================
+// PSC Cache (LRU)
+// ============================================================
+
+/**
+ * LRU Cache for PSC payloads
+ * @class PSCCache
+ */
+class PSCCache {
+  /**
+   * @param {number} maxSize - Maximum cache size
+   */
+  constructor(maxSize = 50) {
+    this.cache = new Map();
+    this.maxSize = maxSize;
+  }
+
+  /**
+   * Get cached entry (moves to most recent)
+   * @param {string} key - Cache key
+   * @returns {any|null} Cached value or null
+   */
+  get(key) {
+    if (!this.cache.has(key)) return null;
+
+    const entry = this.cache.get(key);
+    // Move to end (most recent)
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry;
+  }
+
+  /**
+   * Set cache entry (evicts oldest if at capacity)
+   * @param {string} key - Cache key
+   * @param {any} value - Value to cache
+   */
+  set(key, value) {
+    // Delete if exists (will re-add at end)
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+
+    // Evict oldest if at capacity
+    if (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+
+    this.cache.set(key, value);
+  }
+
+  /**
+   * Check if key exists in cache
+   * @param {string} key - Cache key
+   * @returns {boolean} True if key exists
+   */
+  has(key) {
+    return this.cache.has(key);
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear() {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache size
+   * @returns {number} Number of cached entries
+   */
+  get size() {
+    return this.cache.size;
+  }
+}
+
+// ============================================================
+// Cache Instance & Prefetch Queue
+// ============================================================
+
+/**
+ * Global PSC cache instance
+ * @type {PSCCache}
+ */
+export const pscCache = new PSCCache();
+
+/**
+ * Prefetch queue (tracks in-flight prefetches)
+ * @type {Set<string>}
+ */
+const prefetchQueue = new Set();
+
+// ============================================================
+// PSC Fetch
+// ============================================================
+
+/**
+ * Fetch PSC payload from server
+ * @param {string} url - URL to fetch
+ * @param {Object} options - Fetch options
+ * @param {Object} [options.query={}] - Query parameters
+ * @param {AbortSignal} [options.signal] - Abort signal
+ * @returns {Promise<Object>} PSC payload
+ *
+ * @example
+ * const payload = await fetchPSCPayload('/products/123', {
+ *   query: { tab: 'reviews' }
+ * });
+ */
+export async function fetchPSCPayload(url, options = {}) {
+  const { query = {}, signal } = options;
+
+  // Build query string
+  const queryString = new URLSearchParams(query).toString();
+  const fullUrl = `${url}${queryString ? '?' + queryString : ''}`;
+
+  // Fetch from server with PSC headers
+  const response = await fetch(fullUrl, {
+    headers: {
+      'Accept': 'application/x-pulse-psc',
+      'X-Pulse-Request': 'navigation'
+    },
+    signal
+  });
+
+  if (!response.ok) {
+    throw new Error(`PSC fetch failed: ${response.status} ${response.statusText}`);
+  }
+
+  return response.json();
+}
+
+// ============================================================
+// PSC Navigation
+// ============================================================
+
+/**
+ * Navigate to Server Component route
+ * @param {string} url - URL to navigate to
+ * @param {Object} options - Navigation options
+ * @param {Object} [options.query={}] - Query parameters
+ * @param {string} [options.cacheKey] - Cache key (auto-generated if not provided)
+ * @param {number} [options.staleTime=60000] - Cache staleness threshold (ms)
+ * @param {AbortSignal} [options.signal] - Abort signal
+ * @returns {Promise<Object>} PSC payload
+ *
+ * @example
+ * const payload = await navigatePSC('/products/123', {
+ *   query: { tab: 'reviews' },
+ *   staleTime: 30000
+ * });
+ */
+export async function navigatePSC(url, options = {}) {
+  const { query = {}, cacheKey, signal } = options;
+  const staleTime = options.staleTime ?? 60000;
+
+  // Generate cache key if not provided
+  const key = cacheKey || (url + JSON.stringify(query));
+
+  // Check cache
+  if (pscCache.has(key)) {
+    const cached = pscCache.get(key);
+    const age = Date.now() - cached.timestamp;
+
+    if (age < staleTime) {
+      return cached.payload; // Fresh cache hit
+    }
+  }
+
+  // Fetch fresh payload
+  const payload = await fetchPSCPayload(url, { query, signal });
+
+  // Cache it
+  pscCache.set(key, {
+    payload,
+    timestamp: Date.now()
+  });
+
+  return payload;
+}
+
+// ============================================================
+// PSC Prefetching
+// ============================================================
+
+/**
+ * Prefetch PSC payload in background
+ * @param {string} url - URL to prefetch
+ * @param {Object} options - Prefetch options
+ * @param {Object} [options.query={}] - Query parameters
+ * @param {number} [options.staleTime=60000] - Cache staleness threshold (ms)
+ * @returns {Promise<void>} Resolves when prefetch completes
+ *
+ * @example
+ * // Prefetch on link hover
+ * linkElement.addEventListener('mouseenter', () => {
+ *   prefetchPSC('/products/123');
+ * });
+ */
+export function prefetchPSC(url, options = {}) {
+  const { query = {} } = options;
+  const cacheKey = url + JSON.stringify(query);
+
+  // Skip if already prefetching or cached
+  if (prefetchQueue.has(cacheKey) || pscCache.has(cacheKey)) {
+    return Promise.resolve();
+  }
+
+  // Add to queue
+  prefetchQueue.add(cacheKey);
+
+  // Navigate (which fetches and caches)
+  return navigatePSC(url, { ...options, cacheKey })
+    .then(() => {
+      prefetchQueue.delete(cacheKey);
+    })
+    .catch((err) => {
+      console.warn('PSC prefetch failed:', err);
+      prefetchQueue.delete(cacheKey);
+    });
+}
+
+// ============================================================
+// Cache Management
+// ============================================================
+
+/**
+ * Clear PSC cache
+ *
+ * @example
+ * clearPSCCache(); // Clear all cached PSC payloads
+ */
+export function clearPSCCache() {
+  pscCache.clear();
+}
+
+/**
+ * Get cache statistics
+ * @returns {Object} Cache stats
+ *
+ * @example
+ * const stats = getPSCCacheStats();
+ * console.log(`Cache: ${stats.size}/${stats.maxSize} entries`);
+ */
+export function getPSCCacheStats() {
+  return {
+    size: pscCache.size,
+    maxSize: pscCache.maxSize,
+    prefetching: prefetchQueue.size
+  };
+}
+
+/**
+ * Configure PSC cache
+ * @param {Object} options - Configuration options
+ * @param {number} [options.maxSize] - Maximum cache size
+ *
+ * @example
+ * configurePSCCache({ maxSize: 100 }); // Increase cache size
+ */
+export function configurePSCCache(options = {}) {
+  if (options.maxSize !== undefined) {
+    // Create new cache with new max size
+    const newCache = new PSCCache(options.maxSize);
+
+    // Copy existing entries (up to new max size)
+    const entries = Array.from(pscCache.cache.entries()).slice(0, options.maxSize);
+    entries.forEach(([key, value]) => newCache.set(key, value));
+
+    // Replace global cache
+    pscCache.cache = newCache.cache;
+    pscCache.maxSize = newCache.maxSize;
+  }
+}
+
+// ============================================================
+// Exports
+// ============================================================
+
+export default {
+  PSCCache,
+  pscCache,
+  fetchPSCPayload,
+  navigatePSC,
+  prefetchPSC,
+  clearPSCCache,
+  getPSCCacheStats,
+  configurePSCCache
+};

package/runtime/security.js

@@ -166,10 +166,11 @@ export function sanitizeObjectKeys(obj, options = {}) {
 // =============================================================================
 
 /**
- * HTML entity escape map
- * @private
+ * HTML entity escape map.
+ * Single source of truth — imported by utils.js and error-sanitizer.js.
+ * @type {Object<string, string>}
  */
-const HTML_ESCAPES = {
+export const HTML_ESCAPES = {
   '&': '&amp;',
   '<': '&lt;',
   '>': '&gt;',
@@ -177,10 +178,17 @@ const HTML_ESCAPES = {
   "'": '&#39;'
 };
 
+/**
+ * Pre-compiled regex for HTML special characters (generated from HTML_ESCAPES keys).
+ * @private
+ */
+const HTML_ESCAPE_REGEX = new RegExp(`[${Object.keys(HTML_ESCAPES).join('')}]`, 'g');
+
 /**
  * Escape HTML special characters to prevent XSS.
+ * Single source of truth — re-exported by utils.js.
  *
- * @param {string} str - String to escape
+ * @param {*} str - Value to escape (will be converted to string)
  * @returns {string} Escaped string safe for HTML insertion
  *
  * @example
@@ -189,7 +197,7 @@ const HTML_ESCAPES = {
  */
 export function escapeHtml(str) {
   if (str == null) return '';
-  return String(str).replace(/[&<>"']/g, char => HTML_ESCAPES[char]);
+  return String(str).replace(HTML_ESCAPE_REGEX, char => HTML_ESCAPES[char]);
 }
 
 /**
@@ -398,38 +406,36 @@ export function sanitizeUrl(url, options = {}) {
 
   const trimmed = String(url).trim();
 
-  // Decode URL to catch encoded attacks
+  // Decode URL to catch encoded attacks like &#x6a;avascript:
+  // Also handles %6A%61%76%61%73%63%72%69%70%74 encoding
   let decoded = trimmed;
   try {
-    // Decode HTML entities first
+    // Decode HTML entities first (&#x6a; -> j)
     decoded = decoded.replace(/&#x([0-9a-f]+);?/gi, (_, hex) =>
       String.fromCharCode(parseInt(hex, 16))
     );
     decoded = decoded.replace(/&#(\d+);?/g, (_, dec) =>
       String.fromCharCode(parseInt(dec, 10))
     );
-    // Then decode URI encoding
+    // Then decode URI encoding (%6A -> j)
     decoded = decodeURIComponent(decoded);
   } catch {
-    // Malformed URL - use original
+    // If decoding fails, use original (malformed URLs will be blocked anyway)
   }
 
-  // Normalize and check protocol
+  // Normalize: lowercase and remove whitespace for protocol check
   const normalized = decoded.toLowerCase().replace(/[\s\x00-\x1f]/g, '');
 
-  // Block javascript: protocol
-  if (normalized.startsWith('javascript:')) {
-    log.warn('Blocked javascript: URL');
-    return null;
-  }
-
-  // Block vbscript: protocol
-  if (normalized.startsWith('vbscript:')) {
-    log.warn('Blocked vbscript: URL');
-    return null;
+  // Block dangerous protocols
+  const dangerousProtocols = ['javascript:', 'vbscript:', 'file:'];
+  for (const protocol of dangerousProtocols) {
+    if (normalized.startsWith(protocol)) {
+      log.warn(`Blocked ${protocol} URL`);
+      return null;
+    }
   }
 
-  // Check data: URLs
+  // Check for data: protocol
   if (normalized.startsWith('data:')) {
     if (!allowData) {
       log.warn('Blocked data: URL (not allowed)');
@@ -440,20 +446,42 @@ export function sanitizeUrl(url, options = {}) {
       log.warn('Blocked dangerous data: URL');
       return null;
     }
+    return trimmed;
   }
 
-  // Check blob: URLs
-  if (normalized.startsWith('blob:') && !allowBlob) {
-    log.warn('Blocked blob: URL (not allowed)');
-    return null;
+  // Check for blob: protocol
+  if (normalized.startsWith('blob:')) {
+    if (!allowBlob) {
+      log.warn('Blocked blob: URL (not allowed)');
+      return null;
+    }
+    return trimmed;
+  }
+
+  // Allow relative URLs (must start with / or . to prevent //evil.com attacks)
+  if (allowRelative) {
+    if (trimmed.startsWith('/') && !trimmed.startsWith('//')) {
+      return trimmed;
+    }
+    if (trimmed.startsWith('./') || trimmed.startsWith('../')) {
+      return trimmed;
+    }
+    // URLs without protocol that don't start with // are relative
+    if (!trimmed.includes(':') && !trimmed.startsWith('//')) {
+      return trimmed;
+    }
   }
 
-  // Check for relative URLs
-  if (!trimmed.includes(':')) {
-    return allowRelative ? trimmed : null;
+  // Allow safe protocols (http, https, mailto, tel, sms, ftp, sftp)
+  const colonIndex = trimmed.indexOf(':');
+  if (colonIndex > 0) {
+    const protocol = trimmed.slice(0, colonIndex + 1).toLowerCase();
+    if (SAFE_PROTOCOLS.has(protocol)) {
+      return trimmed;
+    }
   }
 
-  return trimmed;
+  return null;
 }
 
 // =============================================================================
@@ -468,6 +496,7 @@ export default {
   SAFE_PROTOCOLS,
   DEFAULT_ALLOWED_TAGS,
   DEFAULT_ALLOWED_ATTRS,
+  HTML_ESCAPES,
 
   // Validation
   isDangerousKey,