@unrdf/knowledge-engine 5.0.1

package/src/engines/rdf-engine.mjs

@@ -0,0 +1,299 @@
+/**
+ * @fileoverview Production-grade RDF engine for JavaScript.
+ * @version 2.0.0
+ * @license MIT
+ */
+
+import { Parser, Writer, UnrdfDataFactory as DataFactory } from '@unrdf/core/rdf/n3-justified-only';
+import { createStore } from '@unrdf/oxigraph'; // TODO: Replace with Oxigraph Store
+import { createStore as createOxigraphStore } from '@unrdf/oxigraph';
+import rdf from 'rdf-ext';
+import SHACLValidator from 'rdf-validate-shacl';
+import rdfCanonize from 'rdf-canonize';
+import eyereasoner from 'eyereasoner';
+import _jsonld from 'jsonld';
+
+const { namedNode, literal, quad, blankNode, defaultGraph } = DataFactory;
+
+/**
+ * A comprehensive, production-grade engine for RDF processing in JavaScript.
+ * It unifies parsing, serialization, querying, validation, and reasoning.
+ */
+export class RdfEngine {
+  /**
+   * @param {object} [options] - Configuration options for the engine.
+   * @param {string} [options.baseIRI] - The base IRI to use for parsing relative URIs.
+   */
+  constructor(options = {}) {
+    this.baseIRI = options.baseIRI || 'http://example.org/';
+    this.store = createStore();
+  }
+
+  // =================================================================
+  // == Core Setup & Store Access
+  // =================================================================
+
+  /**
+   * Returns the underlying N3.js Store instance.
+   * @returns {import('n3').Store}
+   */
+  getStore() {
+    return this.store;
+  }
+
+  /**
+   * Clears the internal store, removing all quads.
+   */
+  clearStore() {
+    this.store.removeQuads(this.store.getQuads());
+  }
+
+  // =================================================================
+  // == Term Creation
+  // =================================================================
+
+  /**
+   *
+   */
+  namedNode(value) {
+    return namedNode(value);
+  }
+  /**
+   *
+   */
+  literal(value, langOrDt) {
+    return literal(value, langOrDt);
+  }
+  /**
+   *
+   */
+  blankNode(value) {
+    return blankNode(value);
+  }
+  /**
+   *
+   */
+  quad(s, p, o, g = defaultGraph()) {
+    return quad(s, p, o, g);
+  }
+
+  // =================================================================
+  // == Parsing & Serialization
+  // =================================================================
+
+  /**
+   * Parses a Turtle string and adds the quads to the internal store.
+   * @param {string} ttl - The Turtle string to parse.
+   * @returns {import('n3').Store} The engine's store instance.
+   */
+  parseTurtle(ttl) {
+    const quads = new Parser({ baseIRI: this.baseIRI }).parse(ttl);
+    this.store.addQuads(quads);
+    return this.store;
+  }
+
+  /**
+   * Serializes a store to a Turtle string.
+   * @param {import('n3').Store} [store=this.store] - The store to serialize.
+   * @param {object} [options] - N3.js Writer options.
+   * @returns {string}
+   */
+  serializeTurtle(store = this.store, options = {}) {
+    const writer = new Writer({ ...options, format: 'Turtle' });
+    return writer.quadsToString(store.getQuads());
+  }
+
+  /**
+   * Serializes a store to a canonical N-Quads string.
+   * @param {import('n3').Store} [store=this.store] - The store to serialize.
+   * @returns {string}
+   */
+  serializeNQuads(store = this.store) {
+    const writer = new Writer({ format: 'N-Quads' });
+    return writer.quadsToString(store.getQuads());
+  }
+
+  // =================================================================
+  // == SPARQL Querying
+  // =================================================================
+
+  /**
+   * Executes a read-only SPARQL query (SELECT, ASK, CONSTRUCT) against the store.
+   * @param {string} sparql - The SPARQL query string.
+   * @returns {Promise<Array<object>|boolean|import('n3').Store>} The query result.
+   */
+  async query(sparql) {
+    // Remove PREFIX declarations to find the actual query type
+    const queryWithoutPrefixes = sparql.replace(/^PREFIX\s+[^\s]+\s+<[^>]+>\s*/gm, '').trim();
+    const queryType = queryWithoutPrefixes.toUpperCase().split(/\s+/)[0];
+
+    // Convert n3.Store to Oxigraph store and execute query synchronously
+    const oxigraphStore = createOxigraphStore(Array.from(this.store.getQuads()));
+    const result = oxigraphStore.query(sparql);
+
+    switch (queryType) {
+      case 'SELECT': {
+        // Oxigraph returns array of binding objects for SELECT
+        const rows = Array.isArray(result)
+          ? result.map(item => {
+              const entry = {};
+              if (item && typeof item === 'object') {
+                for (const [key, val] of Object.entries(item)) {
+                  entry[key] = val && val.value ? val.value : val;
+                }
+              }
+              return entry;
+            })
+          : [];
+        const variables = rows.length > 0 ? Object.keys(rows[0]) : [];
+        return { type: 'select', rows, variables };
+      }
+      case 'ASK': {
+        // Oxigraph returns boolean for ASK
+        const boolean = typeof result === 'boolean' ? result : false;
+        return { type: 'ask', boolean };
+      }
+      case 'CONSTRUCT': {
+        // Oxigraph returns array of quads for CONSTRUCT
+        const quads = Array.isArray(result) ? result : [];
+        return {
+          type: 'construct',
+          store: createStore(quads),
+        };
+      }
+      case 'DESCRIBE': {
+        // Oxigraph returns array of quads for DESCRIBE
+        const quads = Array.isArray(result) ? result : [];
+        return {
+          type: 'describe',
+          store: createStore(quads),
+        };
+      }
+      case 'INSERT':
+      case 'UPDATE':
+      case 'DELETE':
+        throw new Error(
+          `Query type "${queryType}" is not supported. Use the update() helper for writes.`
+        );
+      default:
+        throw new Error(`Query type "${queryType}" is not supported by query().`);
+    }
+  }
+
+  /**
+   * Executes a SPARQL UPDATE operation (INSERT, DELETE, etc.) against the store.
+   * @param {string} sparql - The SPARQL UPDATE query string.
+   * @returns {Promise<object>} The update result.
+   */
+  async update(sparql) {
+    // Remove PREFIX declarations to find the actual query type
+    const queryWithoutPrefixes = sparql.replace(/PREFIX\s+[^\s]+\s+<[^>]+>\s*/g, '').trim();
+
+    // If still starts with PREFIX, try a different approach
+    if (queryWithoutPrefixes.startsWith('PREFIX')) {
+      const lines = queryWithoutPrefixes.split('\n');
+      const nonPrefixLines = lines.filter(line => !line.trim().startsWith('PREFIX'));
+      const result = nonPrefixLines.join('\n').trim();
+      return this.update(result);
+    }
+    const queryType = queryWithoutPrefixes.toUpperCase().split(/\s+/)[0];
+
+    // For now, we'll implement a simple INSERT DATA operation
+    if (queryType === 'INSERT' && queryWithoutPrefixes.includes('INSERT DATA')) {
+      // Parse the INSERT DATA operation - need to handle PREFIX declarations
+      const insertMatch = sparql.match(/INSERT\s+DATA\s*\{([^}]+)\}/is);
+      if (insertMatch) {
+        const turtleData = insertMatch[1].trim();
+
+        // Extract PREFIX declarations from the original query
+        const prefixMatches = sparql.match(/PREFIX\s+[^\s]+\s+<[^>]+>/gi) || [];
+        const prefixes = prefixMatches.join('\n');
+
+        // Combine prefixes with the data for parsing
+        const dataToParse = prefixes + (prefixes ? '\n' : '') + turtleData;
+
+        // Parse the Turtle data with PREFIX declarations and add to store
+        const parser = new Parser();
+        const quads = parser.parse(dataToParse);
+        for (const quad of quads) {
+          this.store.add(quad);
+        }
+        return { type: 'update', ok: true, inserted: quads.length };
+      }
+    }
+
+    // For other UPDATE operations, throw an error for now
+    throw new Error(`UPDATE operation "${queryType}" not yet implemented`);
+  }
+
+  // =================================================================
+  // == SHACL Validation
+  // =================================================================
+
+  /**
+   * Validates a data store against a set of SHACL shapes.
+   * @param {import('n3').Store} dataStore - The store containing data to validate.
+   * @param {import('n3').Store|string} shapes - The store or Turtle string containing SHACL shapes.
+   * @returns {{conforms: boolean, results: Array<object>}} A validation report.
+   */
+  validateShacl(dataStore, shapes) {
+    const shapesStore =
+      typeof shapes === 'string' ? createStore(new Parser().parse(shapes)) : shapes;
+
+    const validator = new SHACLValidator(rdf.dataset([...shapesStore]));
+    const report = validator.validate(rdf.dataset([...dataStore]));
+
+    return {
+      conforms: report.conforms,
+      results: (report.results || []).map(r => ({
+        message: r.message?.[0]?.value || null,
+        path: r.path?.value || null,
+        focusNode: r.focusNode?.value || null,
+      })),
+    };
+  }
+
+  // =================================================================
+  // == Reasoning
+  // =================================================================
+
+  /**
+   * Infers new knowledge by applying N3 Rules to a data store.
+   * @param {import('n3').Store} dataStore - The store containing data.
+   * @param {import('n3').Store|string} rules - The store or Turtle string containing N3 Rules.
+   * @returns {Promise<import('n3').Store>} A new store containing both original and inferred quads.
+   */
+  async reason(dataStore, rules) {
+    const rulesN3 = typeof rules === 'string' ? rules : this.serializeTurtle(rules);
+    const dataN3 = this.serializeTurtle(dataStore);
+    const { executeBasicEyeQuery } = await import('eyereasoner');
+    const inferredN3 = await executeBasicEyeQuery(eyereasoner.SWIPL, dataN3, rulesN3);
+    return createStore(new Parser().parse(inferredN3));
+  }
+
+  // =================================================================
+  // == Canonicalization & Isomorphism
+  // =================================================================
+
+  /**
+   * Produces a canonical representation of a store's quads using URDNA2015.
+   * @param {import('n3').Store} store - The store to canonicalize.
+   * @returns {string} The canonical N-Quads string.
+   */
+  canonicalize(store) {
+    return rdfCanonize.canonizeSync(store.getQuads(), {
+      algorithm: 'URDNA2015',
+    });
+  }
+
+  /**
+   * Checks if two stores are logically equivalent (isomorphic).
+   * @param {import('n3').Store} storeA
+   * @param {import('n3').Store} storeB
+   * @returns {boolean}
+   */
+  isIsomorphic(storeA, storeB) {
+    if (storeA.size !== storeB.size) return false;
+    return this.canonicalize(storeA) === this.canonicalize(storeB);
+  }
+}

package/src/file-resolver.mjs

@@ -0,0 +1,387 @@
+/**
+ * @file File URI resolver with content-addressed verification.
+ * @module file-resolver
+ *
+ * @description
+ * Production-ready file resolver that loads SPARQL/SHACL files from URIs
+ * with SHA-256 hash verification for content integrity and provenance.
+ */
+
+import { readFile } from 'fs/promises';
+import { createHash } from 'crypto';
+import { _fileURLToPath } from 'url';
+import { _dirname, _join, _resolve } from 'path';
+import { createPathValidator } from './security/path-validator.mjs';
+
+/**
+ * Resolve a file URI to an absolute path.
+ * @param {string} uri - The file URI (e.g., "file://hooks/compliance/largeTx.ask.rq")
+ * @param {string} [basePath] - Base path for relative resolution
+ * @returns {string} Absolute file path
+ *
+ * @throws {Error} If URI is invalid or file doesn't exist
+ */
+export function resolveFileUri(uri, basePath = process.cwd()) {
+  if (!uri || typeof uri !== 'string') {
+    throw new TypeError('resolveFileUri: uri must be a non-empty string');
+  }
+
+  if (!uri.startsWith('file://')) {
+    throw new Error(`resolveFileUri: URI must start with 'file://', got: ${uri}`);
+  }
+
+  // Validate path for security vulnerabilities
+  const pathValidator = createPathValidator({ basePath });
+  const validation = pathValidator.validateFileUri(uri);
+
+  if (!validation.valid) {
+    throw new Error(`Security validation failed: ${validation.violations.join(', ')}`);
+  }
+
+  // Use sanitized path from validator
+  return validation.sanitizedPath;
+}
+
+/**
+ * Calculate SHA-256 hash of file content.
+ * @param {string} filePath - Path to the file
+ * @returns {Promise<string>} Hexadecimal SHA-256 hash
+ *
+ * @throws {Error} If file cannot be read
+ */
+export async function calculateFileHash(filePath) {
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    const hash = createHash('sha256');
+    hash.update(content, 'utf-8');
+    return hash.digest('hex');
+  } catch (error) {
+    throw new Error(`Failed to calculate hash for ${filePath}: ${error.message}`);
+  }
+}
+
+/**
+ * Load file content with hash verification.
+ * @param {string} uri - The file URI
+ * @param {string} expectedHash - Expected SHA-256 hash
+ * @param {string} [basePath] - Base path for resolution
+ * @returns {Promise<{content: string, hash: string, path: string}>} File content and metadata
+ *
+ * @throws {Error} If file cannot be loaded or hash doesn't match
+ */
+export async function loadFileWithHash(uri, expectedHash, basePath = process.cwd()) {
+  if (!expectedHash || typeof expectedHash !== 'string') {
+    throw new TypeError('loadFileWithHash: expectedHash must be a non-empty string');
+  }
+
+  const filePath = resolveFileUri(uri, basePath);
+
+  try {
+    // Load file content
+    const content = await readFile(filePath, 'utf-8');
+
+    // Calculate actual hash
+    const actualHash = await calculateFileHash(filePath);
+
+    // Verify hash matches
+    if (actualHash !== expectedHash) {
+      throw new Error(
+        `Hash verification failed for ${uri}\n` +
+          `Expected: ${expectedHash}\n` +
+          `Actual:   ${actualHash}\n` +
+          `File:     ${filePath}`
+      );
+    }
+
+    return {
+      content,
+      hash: actualHash,
+      path: filePath,
+      uri,
+    };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`File not found: ${uri} (resolved to: ${filePath})`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Load and parse a SPARQL query file.
+ * @param {string} uri - The file URI
+ * @param {string} expectedHash - Expected SHA-256 hash
+ * @param {string} [basePath] - Base path for resolution
+ * @returns {Promise<{sparql: string, hash: string, path: string}>} Parsed SPARQL query
+ *
+ * @throws {Error} If file cannot be loaded or is not valid SPARQL
+ */
+export async function loadSparqlFile(uri, expectedHash, basePath = process.cwd()) {
+  const fileData = await loadFileWithHash(uri, expectedHash, basePath);
+
+  // Basic SPARQL syntax validation
+  const sparql = fileData.content.trim();
+  if (!sparql) {
+    throw new Error(`Empty SPARQL file: ${uri}`);
+  }
+
+  // Check for common SPARQL keywords
+  const sparqlKeywords = ['SELECT', 'ASK', 'CONSTRUCT', 'DESCRIBE', 'INSERT', 'DELETE', 'PREFIX'];
+  const hasKeyword = sparqlKeywords.some(keyword => sparql.toUpperCase().includes(keyword));
+
+  if (!hasKeyword) {
+    throw new Error(`Invalid SPARQL syntax in ${uri}: No recognized SPARQL keywords found`);
+  }
+
+  return {
+    sparql,
+    hash: fileData.hash,
+    path: fileData.path,
+    uri: fileData.uri,
+  };
+}
+
+/**
+ * Load and parse a SHACL shapes file.
+ * @param {string} uri - The file URI
+ * @param {string} expectedHash - Expected SHA-256 hash
+ * @param {string} [basePath] - Base path for resolution
+ * @returns {Promise<{turtle: string, hash: string, path: string}>} Parsed SHACL shapes
+ *
+ * @throws {Error} If file cannot be loaded or is not valid Turtle
+ */
+export async function loadShaclFile(uri, expectedHash, basePath = process.cwd()) {
+  const fileData = await loadFileWithHash(uri, expectedHash, basePath);
+
+  // Basic Turtle syntax validation
+  const turtle = fileData.content.trim();
+  if (!turtle) {
+    throw new Error(`Empty SHACL file: ${uri}`);
+  }
+
+  // Check for SHACL namespace
+  if (!turtle.includes('http://www.w3.org/ns/shacl#')) {
+    throw new Error(`Invalid SHACL file ${uri}: Missing SHACL namespace`);
+  }
+
+  // Check for common SHACL terms
+  const shaclTerms = ['sh:NodeShape', 'sh:PropertyShape', 'sh:targetClass', 'sh:path'];
+  const hasShaclTerm = shaclTerms.some(term => turtle.includes(term));
+
+  if (!hasShaclTerm) {
+    throw new Error(`Invalid SHACL file ${uri}: No recognized SHACL terms found`);
+  }
+
+  return {
+    turtle,
+    hash: fileData.hash,
+    path: fileData.path,
+    uri: fileData.uri,
+  };
+}
+
+/**
+ * Create a file resolver with caching.
+ * @param {Object} [options] - Resolver options
+ * @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
+ * @returns {Object} File resolver instance
+ */
+export function createFileResolver(options = {}) {
+  const {
+    basePath = process.cwd(),
+    enableCache = true,
+    cacheMaxAge = 300000, // 5 minutes
+  } = options;
+
+  const cache = new Map();
+
+  return {
+    /**
+     * Load a file with hash verification.
+     * @param {string} uri - The file URI
+     * @param {string} expectedHash - Expected SHA-256 hash
+     * @returns {Promise<Object>} File content and metadata
+     */
+    async loadFile(uri, expectedHash) {
+      const cacheKey = `${uri}:${expectedHash}`;
+
+      if (enableCache && cache.has(cacheKey)) {
+        const cached = cache.get(cacheKey);
+        if (Date.now() - cached.timestamp < cacheMaxAge) {
+          return cached.data;
+        }
+        cache.delete(cacheKey);
+      }
+
+      const data = await loadFileWithHash(uri, expectedHash, basePath);
+
+      if (enableCache) {
+        cache.set(cacheKey, {
+          data,
+          timestamp: Date.now(),
+        });
+      }
+
+      return data;
+    },
+
+    /**
+     * Load a SPARQL file.
+     * @param {string} uri - The file URI
+     * @param {string} expectedHash - Expected SHA-256 hash
+     * @returns {Promise<Object>} Parsed SPARQL query
+     */
+    async loadSparql(uri, expectedHash) {
+      const cacheKey = `sparql:${uri}:${expectedHash}`;
+
+      if (enableCache && cache.has(cacheKey)) {
+        const cached = cache.get(cacheKey);
+        if (Date.now() - cached.timestamp < cacheMaxAge) {
+          return cached.data;
+        }
+        cache.delete(cacheKey);
+      }
+
+      const data = await loadSparqlFile(uri, expectedHash, basePath);
+
+      if (enableCache) {
+        cache.set(cacheKey, {
+          data,
+          timestamp: Date.now(),
+        });
+      }
+
+      return data;
+    },
+
+    /**
+     * Load a SHACL file.
+     * @param {string} uri - The file URI
+     * @param {string} expectedHash - Expected SHA-256 hash
+     * @returns {Promise<Object>} Parsed SHACL shapes
+     */
+    async loadShacl(uri, expectedHash) {
+      const cacheKey = `shacl:${uri}:${expectedHash}`;
+
+      if (enableCache && cache.has(cacheKey)) {
+        const cached = cache.get(cacheKey);
+        if (Date.now() - cached.timestamp < cacheMaxAge) {
+          return cached.data;
+        }
+        cache.delete(cacheKey);
+      }
+
+      const data = await loadShaclFile(uri, expectedHash, basePath);
+
+      if (enableCache) {
+        cache.set(cacheKey, {
+          data,
+          timestamp: Date.now(),
+        });
+      }
+
+      return data;
+    },
+
+    /**
+     * Clear the cache.
+     */
+    clearCache() {
+      cache.clear();
+    },
+
+    /**
+     * Pre-load a file at startup (compute hash once, avoid I/O in hot path)
+     * @param {string} uri - The file URI
+     * @returns {Promise<Object>} File content, computed hash, and metadata
+     *
+     * This method loads a file and computes its SHA-256 hash once at startup,
+     * then caches the result. Useful for "warming" the cache before transaction execution.
+     */
+    async preload(uri) {
+      try {
+        const filePath = resolveFileUri(uri, basePath);
+        const content = await readFile(filePath, 'utf-8');
+        const hash = await calculateFileHash(filePath);
+
+        const data = {
+          content,
+          hash,
+          path: filePath,
+          uri,
+        };
+
+        // Cache with preloaded marker (very long TTL)
+        const cacheKey = `preloaded:${uri}`;
+        if (enableCache) {
+          cache.set(cacheKey, {
+            data,
+            timestamp: Date.now(),
+          });
+        }
+
+        return data;
+      } catch (error) {
+        throw new Error(`Failed to preload ${uri}: ${error.message}`);
+      }
+    },
+
+    /**
+     * Collect all file URIs referenced in hook conditions
+     * @param {Array<Object>} hooks - Array of hook definitions
+     * @returns {Set<string>} Set of unique file URIs
+     *
+     * This method analyzes hook conditions to find all file references
+     * that should be preloaded at startup to eliminate File I/O from hot path.
+     */
+    collectFileUris(hooks) {
+      const uris = new Set();
+
+      if (!Array.isArray(hooks)) {
+        return uris;
+      }
+
+      for (const hook of hooks) {
+        if (hook.condition && hook.condition.file) {
+          uris.add(hook.condition.file);
+        }
+        if (hook.conditions && Array.isArray(hook.conditions)) {
+          for (const cond of hook.conditions) {
+            if (cond.file) {
+              uris.add(cond.file);
+            }
+          }
+        }
+      }
+
+      return uris;
+    },
+
+    /**
+     * Get cache statistics.
+     * @returns {Object} Cache statistics
+     */
+    getCacheStats() {
+      const now = Date.now();
+      let validEntries = 0;
+      let expiredEntries = 0;
+
+      for (const [_key, value] of cache.entries()) {
+        if (now - value.timestamp < cacheMaxAge) {
+          validEntries++;
+        } else {
+          expiredEntries++;
+        }
+      }
+
+      return {
+        totalEntries: cache.size,
+        validEntries,
+        expiredEntries,
+        cacheMaxAge,
+      };
+    },
+  };
+}