@unrdf/hooks 26.4.2 → 26.4.4

package/src/hooks/effect-sandbox.mjs

@@ -39,13 +39,17 @@ const SandboxConfigSchema = z.object({
 /**
  * Schema for sandbox execution context
  */
-const SandboxContextSchema = z.object({
-  event: z.any(),
-  store: z.any(),
-  delta: z.any(),
-  metadata: z.record(z.any()).optional(),
-  allowedFunctions: z.array(z.string()).default(['emitEvent', 'log', 'assert']),
-});
+const SandboxContextSchema = z
+  .object({
+    event: z.any(),
+    store: z.any(),
+    delta: z.any(),
+    metadata: z.record(z.any()).optional(),
+    allowedFunctions: z.array(z.string()).default(['emitEvent', 'log', 'assert']),
+  })
+  .refine(obj => 'event' in obj && 'store' in obj && 'delta' in obj, {
+    message: 'event, store, and delta fields are required',
+  });
 
 /**
  * Schema for sandbox execution result
@@ -175,7 +179,7 @@ export class EffectSandbox {
         ...result,
         executionId,
         duration,
-        success: true,
+        success: result?.success !== false,
       };
     } catch (error) {
       const duration = Date.now() - startTime;
@@ -478,7 +482,13 @@ export class EffectSandbox {
 
     const terminationPromises = Array.from(this.workers.values()).map(worker => {
       return new Promise(resolve => {
-        worker.terminate();
+        if (worker?.terminate && typeof worker.terminate === 'function') {
+          try {
+            worker.terminate();
+          } catch (_e) {
+            // Ignore termination errors
+          }
+        }
         resolve();
       });
     });

package/src/hooks/file-resolver.mjs

@@ -186,6 +186,10 @@ export async function loadShaclFile(uri, expectedHash, basePath = process.cwd())
  * @param {string} [options.basePath] - Base path for file resolution
  * @param {boolean} [options.enableCache] - Enable file content caching
  * @param {number} [options.cacheMaxAge] - Cache max age in milliseconds
+ * @param {number} [options.cacheSize] - Maximum cache size
+ * @param {boolean} [options.allowAbsolutePaths] - Allow absolute paths (default: true)
+ * @param {boolean} [options.enablePathValidation] - Enforce strict path validation
+ * @param {Array<string>} [options.allowedExtensions] - Whitelist of allowed extensions
  * @returns {Object} File resolver instance
  */
 export function createFileResolver(options = {}) {
@@ -193,11 +197,152 @@ export function createFileResolver(options = {}) {
     basePath = process.cwd(),
     enableCache = true,
     cacheMaxAge = 300000, // 5 minutes
+    cacheSize = 1000,
+    allowAbsolutePaths = true,
+    enablePathValidation = false,
+    allowedExtensions = null,
   } = options;
 
   const cache = new Map();
+  const pathResolveCache = new Map(); // Cache for resolve() results
+  let cacheHits = 0;
+  let cacheMisses = 0;
+
+  /**
+   * Ensure cache doesn't exceed size limit by removing oldest entries
+   */
+  function enforceMaxCacheSize() {
+    if (cache.size > cacheSize) {
+      const keysToDelete = Array.from(cache.keys()).slice(0, cache.size - cacheSize);
+      keysToDelete.forEach(key => cache.delete(key));
+    }
+    if (pathResolveCache.size > cacheSize) {
+      const keysToDelete = Array.from(pathResolveCache.keys()).slice(
+        0,
+        pathResolveCache.size - cacheSize
+      );
+      keysToDelete.forEach(key => pathResolveCache.delete(key));
+    }
+  }
 
   return {
+    /**
+     * Sanitize a file path to remove dangerous patterns.
+     * @param {string} filePath - The file path to sanitize
+     * @returns {string} Sanitized file path
+     */
+    sanitizePath(filePath) {
+      if (!filePath || typeof filePath !== 'string') {
+        return '';
+      }
+      // Remove parent directory traversal attempts
+      return filePath
+        .split(/[/\\]+/)
+        .filter(part => part && part !== '..')
+        .join('/');
+    },
+
+    /**
+     * Validate hash format.
+     * @param {string} hash - The hash string to validate
+     * @param {string} algorithm - Hash algorithm ('sha256', 'sha512', etc.)
+     * @returns {boolean} True if hash is valid
+     */
+    isValidHash(hash, algorithm = 'sha256') {
+      if (!hash || typeof hash !== 'string') {
+        return false;
+      }
+
+      const expectedLength = algorithm === 'sha512' ? 128 : algorithm === 'sha256' ? 64 : 0;
+      if (expectedLength === 0 || hash.length !== expectedLength) {
+        return false;
+      }
+
+      // Check if all characters are valid hex (0-9, a-f, A-F)
+      return /^[0-9a-fA-F]+$/.test(hash);
+    },
+
+    /**
+     * Resolve a file path relative to basePath.
+     * @param {string} filePath - The file path to resolve
+     * @returns {string} Absolute file path
+     * @throws {Error} If path is invalid or not allowed
+     */
+    resolve(filePath) {
+      if (!filePath || typeof filePath !== 'string') {
+        throw new TypeError('resolve: path must be a non-empty string');
+      }
+
+      // Check cache first
+      if (enableCache && pathResolveCache.has(filePath)) {
+        cacheHits++;
+        return pathResolveCache.get(filePath);
+      }
+      cacheMisses++;
+
+      // Pass through HTTP/HTTPS URIs unchanged
+      if (filePath.startsWith('http://') || filePath.startsWith('https://')) {
+        if (enableCache) {
+          pathResolveCache.set(filePath, filePath);
+          enforceMaxCacheSize();
+        }
+        return filePath;
+      }
+
+      // Pass through file:// URIs with special handling
+      if (filePath.startsWith('file://')) {
+        if (enableCache) {
+          pathResolveCache.set(filePath, filePath);
+          enforceMaxCacheSize();
+        }
+        return filePath;
+      }
+
+      // Reject unknown URI schemes
+      if (filePath.includes('://')) {
+        throw new Error(`resolve: unsupported URI scheme in ${filePath}`);
+      }
+
+      // Path traversal validation if enabled
+      if (enablePathValidation && filePath.includes('..')) {
+        throw new Error(`resolve: path traversal detected: ${filePath}`);
+      }
+
+      // Check for absolute paths - only reject if explicitly disabled
+      const isAbsolute = filePath.startsWith('/') || /^[a-zA-Z]:/.test(filePath);
+      if (!allowAbsolutePaths && isAbsolute) {
+        throw new Error(`resolve: absolute paths are not allowed: ${filePath}`);
+      }
+
+      // If absolute path and allowed, return as-is
+      if (isAbsolute) {
+        const resolved = _resolve(filePath);
+        if (enableCache) {
+          pathResolveCache.set(filePath, resolved);
+          enforceMaxCacheSize();
+        }
+        return resolved;
+      }
+
+      // Check file extensions if whitelist provided
+      if (allowedExtensions && Array.isArray(allowedExtensions)) {
+        const ext = filePath.slice(filePath.lastIndexOf('.'));
+        if (ext && !allowedExtensions.includes(ext)) {
+          throw new Error(
+            `resolve: file extension '${ext}' is not allowed. Allowed: ${allowedExtensions.join(', ')}`
+          );
+        }
+      }
+
+      // Resolve relative paths against basePath
+      const resolved = _resolve(_join(basePath, filePath));
+      if (enableCache) {
+        pathResolveCache.set(filePath, resolved);
+        enforceMaxCacheSize();
+      }
+      return resolved;
+    },
+
     /**
      * Load a file with hash verification.
      * @param {string} uri - The file URI
@@ -222,6 +367,7 @@ export function createFileResolver(options = {}) {
           data,
           timestamp: Date.now(),
         });
+        enforceMaxCacheSize();
       }
 
       return data;
@@ -251,6 +397,7 @@ export function createFileResolver(options = {}) {
           data,
           timestamp: Date.now(),
         });
+        enforceMaxCacheSize();
       }
 
       return data;
@@ -280,6 +427,7 @@ export function createFileResolver(options = {}) {
           data,
           timestamp: Date.now(),
         });
+        enforceMaxCacheSize();
       }
 
       return data;
@@ -290,6 +438,7 @@ export function createFileResolver(options = {}) {
      */
     clearCache() {
       cache.clear();
+      pathResolveCache.clear();
     },
 
     /**
@@ -377,10 +526,15 @@ export function createFileResolver(options = {}) {
       }
 
       return {
-        totalEntries: cache.size,
+        size: pathResolveCache.size,
+        hits: cacheHits,
+        misses: cacheMisses,
+        totalEntries: cache.size + pathResolveCache.size,
         validEntries,
         expiredEntries,
         cacheMaxAge,
+        cacheSize,
+        pathCacheSize: pathResolveCache.size,
       };
     },
   };

package/src/hooks/hook-chain-compiler.mjs

@@ -100,10 +100,17 @@ export function compileHookChain(hooks) {
 
   // Generate inline transformation steps
   const transformSteps = hooks
-    .map((h, i) => (hasTransformation(h) ? `quad = hooks[${i}].transform(quad);` : ''))
+    .map((h, i) => {
+      if (hasTransformation(h)) {
+        return `quad = hooks[${i}].transform(quad);
+    if (quad === null || quad === undefined) return { valid: false, quad };`;
+      }
+      return '';
+    })
     .filter(Boolean)
     .join('\n    ');
 
+
   // Compile the chain function
   const fnBody = `
     ${validationSteps}
@@ -147,6 +154,9 @@ function createInterpretedChain(hooks) {
 
       if (hasTransformation(hook)) {
         currentQuad = hook.transform(currentQuad);
+        if (currentQuad === null || currentQuad === undefined) {
+          return { valid: false, quad: currentQuad, failedHook: hook.name };
+        }
       }
     }
 

package/src/hooks/hook-executor.mjs

@@ -65,6 +65,18 @@ export const ChainResultSchema = z.object({
  * }
  */
 export function executeHook(hook, quad, options = {}) {
+  // Validate input quad
+  if (!quad || typeof quad !== 'object') {
+    throw new TypeError(
+      `Invalid quad provided to executeHook: expected object, got ${typeof quad}`
+    );
+  }
+
+  // Validate quad has required properties
+  if (!quad.subject || !quad.predicate || !quad.object) {
+    throw new TypeError('Quad must have subject, predicate, and object properties');
+  }
+
   // Fast path: skip Zod if hook was created via defineHook (_validated flag)
   const validatedHook = hook._validated ? hook : HookSchema.parse(hook);
 
@@ -75,71 +87,61 @@ export function executeHook(hook, quad, options = {}) {
     hookName: validatedHook.name,
   };
 
-  try {
-    // Execute validation if present
-    if (hasValidation(validatedHook)) {
-      const validationResult = validatedHook.validate(quad);
-
-      // POKA-YOKE: Non-boolean validation return guard (RPN 280 → 28)
-      if (typeof validationResult !== 'boolean') {
-        console.warn(
-          `[POKA-YOKE] Hook "${validatedHook.name}": validate() returned ${typeof validationResult}, expected boolean. Coercing to boolean.`
-        );
-        result.warning = `Non-boolean validation return (${typeof validationResult}) coerced to boolean`;
-      }
+  // Execute validation if present - let errors propagate
+  if (hasValidation(validatedHook)) {
+    const validationResult = validatedHook.validate(quad);
 
-      if (!validationResult) {
-        result.valid = false;
-        result.error = `Validation failed for hook: ${validatedHook.name}`;
-        return result;
-      }
+    // POKA-YOKE: Non-boolean validation return guard (RPN 280 → 28)
+    if (typeof validationResult !== 'boolean') {
+      console.warn(
+        `[POKA-YOKE] Hook "${validatedHook.name}": validate() returned ${typeof validationResult}, expected boolean. Coercing to boolean.`
+      );
+      result.warning = `Non-boolean validation return (${typeof validationResult}) coerced to boolean`;
     }
 
-    // Execute transformation if present
-    if (hasTransformation(validatedHook)) {
-      const transformed = validatedHook.transform(quad);
+    if (!validationResult) {
+      result.valid = false;
+      result.error = `Validation failed for hook: ${validatedHook.name}`;
+      return result;
+    }
+  }
 
-      // POKA-YOKE: Transform return type validation (RPN 280 → 28)
-      if (!transformed || typeof transformed !== 'object') {
-        throw new TypeError(
-          `Hook "${validatedHook.name}": transform() must return a Quad object, got ${typeof transformed}`
-        );
-      }
+  // Execute transformation if present - let errors propagate
+  if (hasTransformation(validatedHook)) {
+    const transformed = validatedHook.transform(quad);
 
-      // POKA-YOKE: Check for required Quad properties
-      if (!transformed.subject || !transformed.predicate || !transformed.object) {
-        throw new TypeError(
-          `Hook "${validatedHook.name}": transform() returned object missing subject/predicate/object`
-        );
-      }
+    // POKA-YOKE: Transform return type validation (RPN 280 → 28)
+    if (transformed === null || transformed === undefined) {
+      result.valid = false;
+      result.quad = transformed;
+      return result;
+    }
 
-      // POKA-YOKE: Pooled quad leak detection (warn if returning pooled quad)
-      if (transformed._pooled && options.warnPooledQuads !== false) {
-        console.warn(
-          `[POKA-YOKE] Hook "${validatedHook.name}": returned pooled quad. Clone before storing to prevent memory issues.`
-        );
-        result.warning = 'Pooled quad returned - consider cloning';
-      }
+    if (typeof transformed !== 'object') {
+      throw new TypeError(
+        `Hook "${validatedHook.name}": transform() must return a Quad object, got ${typeof transformed}`
+      );
+    }
 
-      result.quad = transformed;
+    // POKA-YOKE: Check for required Quad properties
+    if (!transformed.subject || !transformed.predicate || !transformed.object) {
+      throw new TypeError(
+        `Hook "${validatedHook.name}": transform() returned object missing subject/predicate/object`
+      );
+    }
+
+    // POKA-YOKE: Pooled quad leak detection (warn if returning pooled quad)
+    if (transformed._pooled && options.warnPooledQuads !== false) {
+      console.warn(
+        `[POKA-YOKE] Hook "${validatedHook.name}": returned pooled quad. Clone before storing to prevent memory issues.`
+      );
+      result.warning = 'Pooled quad returned - consider cloning';
     }
 
-    return result;
-  } catch (error) {
-    result.valid = false;
-    result.error = error instanceof Error ? error.message : String(error);
-
-    // POKA-YOKE: Stack trace preservation (RPN 504 → 50)
-    result.errorDetails = {
-      hookName: validatedHook.name,
-      hookTrigger: validatedHook.trigger,
-      stack: error instanceof Error ? error.stack : undefined,
-      originalError: error instanceof Error ? error : undefined,
-      rawError: !(error instanceof Error) ? error : undefined,
-    };
-
-    return result;
+    result.quad = transformed;
   }
+
+  return result;
 }
 
 /**
@@ -158,7 +160,17 @@ export function executeHook(hook, quad, options = {}) {
  * }
  */
 export function executeHookChain(hooks, quad) {
-  // Fast path: trust pre-validated hooks (skip Zod array parse)
+  // Validate input
+  if (!Array.isArray(hooks)) {
+    throw new TypeError('hooks must be an array');
+  }
+
+  // Check for null/undefined hooks
+  for (let i = 0; i < hooks.length; i++) {
+    if (hooks[i] === null || hooks[i] === undefined) {
+      throw new Error(`Hook at index ${i} is ${hooks[i]}`);
+    }
+  }
 
   /** @type {HookResult[]} */
   const results = [];
@@ -176,7 +188,7 @@ export function executeHookChain(hooks, quad) {
       break;
     }
 
-    if (result.quad) {
+    if (result.quad !== undefined) {
       currentQuad = result.quad;
     }
   }
@@ -187,24 +199,44 @@ export function executeHookChain(hooks, quad) {
     quad: currentQuad,
     results,
     error: chainError,
+    failedHook: !chainValid ? results[results.length - 1]?.hookName : undefined,
   };
 }
 
 /**
  * Execute hooks for a specific trigger type.
+ * Accepts either a registry or an array of hooks.
  *
- * @param {Hook[]} hooks - All registered hooks
+ * @param {HookRegistry|Hook[]} hooksOrRegistry - Hooks array or registry
  * @param {import('./define-hook.mjs').HookTrigger} trigger - Trigger type to execute
  * @param {Quad} quad - Quad to process
- * @returns {ChainResult} - Execution result
+ * @returns {HookResult[]} - Array of hook execution results
  *
  * @example
- * const result = executeHooksByTrigger(allHooks, 'before-add', quad);
+ * const results = executeHooksByTrigger(registry, 'before-add', quad);
  */
-export function executeHooksByTrigger(hooks, trigger, quad) {
-  // Fast path: trust pre-validated hooks (skip Zod array parse)
-  const matchingHooks = hooks.filter(h => h.trigger === trigger);
-  return executeHookChain(matchingHooks, quad);
+export function executeHooksByTrigger(hooksOrRegistry, trigger, quad) {
+  let hooks;
+
+  // Handle registry object
+  if (hooksOrRegistry && typeof hooksOrRegistry === 'object' && hooksOrRegistry.hooks instanceof Map) {
+    // Extract hooks for the specific trigger from registry
+    const triggerSet = hooksOrRegistry.triggerIndex.get(trigger);
+    if (!triggerSet) {
+      hooks = [];
+    } else {
+      hooks = Array.from(triggerSet).map(name => hooksOrRegistry.hooks.get(name));
+    }
+  } else if (Array.isArray(hooksOrRegistry)) {
+    // Direct hooks array
+    hooks = hooksOrRegistry.filter(h => h.trigger === trigger);
+  } else {
+    // Invalid input
+    hooks = [];
+  }
+
+  // Execute and return the full chain result
+  return executeHookChain(hooks, quad);
 }
 
 /**
@@ -267,15 +299,13 @@ export function validateOnly(hooks, quad) {
  * @param {Quad[]} quads - Array of quads to process
  * @param {Object} [options] - Batch options
  * @param {boolean} [options.stopOnError=false] - Stop on first error
- * @returns {{ results: ChainResult[], validCount: number, invalidCount: number }}
+ * @returns {ChainResult[]} Array of execution results
  */
 export function executeBatch(hooks, quads, options = {}) {
   const { stopOnError = false } = options;
 
   /** @type {ChainResult[]} */
   const results = [];
-  let validCount = 0;
-  let invalidCount = 0;
 
   // Zod-free hot path - hooks already validated by defineHook
   for (let i = 0; i < quads.length; i++) {
@@ -314,12 +344,7 @@ export function executeBatch(hooks, quads, options = {}) {
 
     results.push({ valid: isValid, quad: currentQuad, error, results: [] });
 
-    if (isValid) {
-      validCount++;
-    } else {
-      invalidCount++;
-      if (stopOnError) break;
-    }
+    if (!isValid && stopOnError) break;
   }
 
   return results;