@unrdf/hooks 5.0.1 → 26.4.2

package/examples/policy-hooks/README.md

@@ -0,0 +1,193 @@
+# Policy Hooks Example
+
+This example demonstrates how to use **@unrdf/hooks** for implementing RDF data policies including access control, data validation, privacy, and provenance tracking.
+
+## Features
+
+- **ACL Policy**: Access control lists for trusted namespaces
+- **Data Type Policy**: Strict type validation for RDF literals
+- **Privacy Policy**: Automatic data redaction and transformation
+- **Provenance Policy**: Require metadata for audit trails
+
+## Installation
+
+```bash
+pnpm install
+```
+
+## Usage
+
+Run the example:
+
+```bash
+pnpm start
+```
+
+Run tests:
+
+```bash
+pnpm test
+```
+
+## Example Output
+
+```
+🔒 Policy Hooks Example
+
+============================================================
+
+✅ Test 1: Trusted namespace
+   Passed: 4/4
+   Failed: 0/4
+
+❌ Test 2: Untrusted namespace
+   Passed: 2/4
+   Failed: 2/4
+   ❌ acl-policy: validation failed
+   ❌ provenance-policy: validation failed
+
+✅ Test 3: Valid age constraint
+   Passed: 4/4
+   Failed: 0/4
+
+❌ Test 4: Invalid age constraint
+   Passed: 3/4
+   Failed: 1/4
+   ❌ data-type-policy: validation failed
+
+🔐 Test 5: Privacy policy transformation
+   Status: PASSED
+   Original: alice@example.org
+   Transformed: [REDACTED]
+
+❌ Test 6: Missing provenance
+   Passed: 3/4
+   Failed: 1/4
+   ❌ provenance-policy: validation failed
+
+============================================================
+✨ Policy Hooks Example Complete
+```
+
+## Policy Hooks
+
+### 1. ACL Policy
+
+Validates that RDF quads come from trusted namespaces:
+
+```javascript
+const aclPolicy = defineHook({
+  name: 'acl-policy',
+  trigger: 'before-add',
+  validate: quad => {
+    const trustedNamespaces = [
+      'http://example.org/',
+      'http://xmlns.com/foaf/0.1/',
+    ];
+    // Check subject and predicate IRIs
+    return trustedNamespaces.some(ns =>
+      quad.subject.value.startsWith(ns) ||
+      quad.predicate.value.startsWith(ns)
+    );
+  },
+});
+```
+
+### 2. Data Type Policy
+
+Enforces type constraints on specific predicates:
+
+```javascript
+const dataTypePolicy = defineHook({
+  name: 'data-type-policy',
+  trigger: 'before-add',
+  validate: quad => {
+    if (quad.predicate.value === 'http://xmlns.com/foaf/0.1/age') {
+      const value = parseInt(quad.object.value, 10);
+      return !isNaN(value) && value >= 0 && value <= 150;
+    }
+    return true;
+  },
+});
+```
+
+### 3. Privacy Policy
+
+Transforms sensitive data automatically:
+
+```javascript
+const privacyPolicy = defineHook({
+  name: 'privacy-policy',
+  trigger: 'before-add',
+  transform: quad => {
+    if (quad.predicate.value === 'http://xmlns.com/foaf/0.1/mbox') {
+      return DataFactory.quad(
+        quad.subject,
+        quad.predicate,
+        DataFactory.literal('[REDACTED]'),
+        quad.graph
+      );
+    }
+    return quad;
+  },
+});
+```
+
+### 4. Provenance Policy
+
+Requires named graphs for audit trails:
+
+```javascript
+const provenancePolicy = defineHook({
+  name: 'provenance-policy',
+  trigger: 'before-add',
+  validate: quad => {
+    return quad.graph && quad.graph.termType === 'NamedNode';
+  },
+});
+```
+
+## Registry Usage
+
+Create and configure a policy registry:
+
+```javascript
+import { createHookRegistry, registerHook } from '@unrdf/hooks';
+
+const registry = createHookRegistry();
+
+registerHook(registry, aclPolicy);
+registerHook(registry, dataTypePolicy);
+registerHook(registry, privacyPolicy);
+registerHook(registry, provenancePolicy);
+
+// Execute all policies
+const results = executeHooksByTrigger(registry, store, 'before-add', quad);
+console.log(`Passed: ${results.passed.length}/${results.total}`);
+```
+
+## Testing
+
+The example includes comprehensive tests:
+
+- ACL policy validation
+- Data type constraints
+- Privacy transformations
+- Provenance requirements
+- Registry execution
+
+Run tests with:
+
+```bash
+pnpm test
+```
+
+## Learn More
+
+- [@unrdf/hooks Documentation](../../README.md)
+- [Hook Chains Example](../hook-chains/)
+- [UNRDF Core](../../../core/)
+
+## License
+
+MIT

package/examples/policy-hooks/node_modules/.bin/validate-hooks

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/sac/unrdf/packages/hooks/examples/node_modules:/Users/sac/unrdf/packages/hooks/node_modules:/Users/sac/unrdf/packages/node_modules:/Users/sac/unrdf/node_modules:/Users/sac/node_modules:/Users/node_modules:/node_modules:/Users/sac/unrdf/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/sac/unrdf/packages/hooks/examples/node_modules:/Users/sac/unrdf/packages/hooks/node_modules:/Users/sac/unrdf/packages/node_modules:/Users/sac/unrdf/node_modules:/Users/sac/node_modules:/Users/node_modules:/node_modules:/Users/sac/unrdf/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../@unrdf/hooks/examples/validate-hooks.mjs" "$@"
+else
+  exec node  "$basedir/../@unrdf/hooks/examples/validate-hooks.mjs" "$@"
+fi

package/examples/policy-hooks/node_modules/.bin/vitest

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/sac/unrdf/node_modules/.pnpm/vitest@4.0.15_@opentelemetry+api@1.9.0_@types+node@24.10.1_@vitest+ui@4.0.15_happy-dom@_4020ef6a5cc83a28d6954792bad1f77a/node_modules/vitest/node_modules:/Users/sac/unrdf/node_modules/.pnpm/vitest@4.0.15_@opentelemetry+api@1.9.0_@types+node@24.10.1_@vitest+ui@4.0.15_happy-dom@_4020ef6a5cc83a28d6954792bad1f77a/node_modules:/Users/sac/unrdf/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/sac/unrdf/node_modules/.pnpm/vitest@4.0.15_@opentelemetry+api@1.9.0_@types+node@24.10.1_@vitest+ui@4.0.15_happy-dom@_4020ef6a5cc83a28d6954792bad1f77a/node_modules/vitest/node_modules:/Users/sac/unrdf/node_modules/.pnpm/vitest@4.0.15_@opentelemetry+api@1.9.0_@types+node@24.10.1_@vitest+ui@4.0.15_happy-dom@_4020ef6a5cc83a28d6954792bad1f77a/node_modules:/Users/sac/unrdf/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../vitest/vitest.mjs" "$@"
+else
+  exec node  "$basedir/../vitest/vitest.mjs" "$@"
+fi

package/examples/policy-hooks/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -0,0 +1 @@
+{"version":"4.0.15","results":[[":test/example.test.mjs",{"duration":6.318749999999994,"failed":false}]]}

package/examples/policy-hooks/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@unrdf/hooks-example-policy",
+  "version": "5.0.0",
+  "type": "module",
+  "description": "Policy Hooks Example - RDF data validation and access control",
+  "private": true,
+  "scripts": {
+    "start": "node src/index.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@unrdf/core": "workspace:*",
+    "@unrdf/hooks": "workspace:*",
+    "n3": "^1.26.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.15"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/examples/policy-hooks/src/index.mjs

@@ -0,0 +1,275 @@
+/**
+ * @file Policy Hooks Example
+ *
+ * Demonstrates:
+ * - Defining custom policy hooks
+ * - RDF access control policies
+ * - Data validation constraints
+ * - Hook execution and results
+ *
+ * @module hooks-example-policy
+ */
+
+import { namedNode, literal, quad, createStore, addQuad } from '@unrdf/core';
+import { createStore, dataFactory } from '@unrdf/oxigraph';
+import {
+  defineHook,
+  createHookRegistry,
+  registerHook,
+  executeHook,
+  executeHooksByTrigger,
+} from '@unrdf/hooks';
+/* ========================================================================= */
+/* Policy Hook Definitions                                                   */
+/* ========================================================================= */
+
+/**
+ * Access Control List (ACL) Policy Hook
+ *
+ * Only allows quads from trusted namespaces.
+ */
+const aclPolicy = defineHook({
+  name: 'acl-policy',
+  trigger: 'before-add',
+  validate: quad => {
+    const trustedNamespaces = [
+      'http://example.org/',
+      'http://xmlns.com/foaf/0.1/',
+      'http://www.w3.org/1999/02/22-rdf-syntax-ns#',
+    ];
+
+    const subjectIRI = quad.subject.termType === 'NamedNode' ? quad.subject.value : '';
+    const predicateIRI = quad.predicate.value;
+
+    return trustedNamespaces.some(ns => subjectIRI.startsWith(ns) || predicateIRI.startsWith(ns));
+  },
+  metadata: {
+    description: 'ACL policy - only allow quads from trusted namespaces',
+    policy: 'security',
+  },
+});
+
+/**
+ * Data Type Policy Hook
+ *
+ * Enforces strict typing on foaf:age - must be integer.
+ */
+const dataTypePolicy = defineHook({
+  name: 'data-type-policy',
+  trigger: 'before-add',
+  validate: quad => {
+    if (quad.predicate.value === 'http://xmlns.com/foaf/0.1/age') {
+      if (quad.object.termType !== 'Literal') {
+        return false;
+      }
+      const value = parseInt(quad.object.value, 10);
+      return !isNaN(value) && value >= 0 && value <= 150;
+    }
+    return true;
+  },
+  metadata: {
+    description: 'Data type policy - foaf:age must be valid integer 0-150',
+    policy: 'validation',
+  },
+});
+
+/**
+ * Privacy Policy Hook
+ *
+ * Redacts email addresses unless explicitly allowed.
+ */
+const privacyPolicy = defineHook({
+  name: 'privacy-policy',
+  trigger: 'before-add',
+  transform: quad => {
+    if (quad.predicate.value === 'http://xmlns.com/foaf/0.1/mbox') {
+      if (quad.object.termType === 'Literal') {
+        // Redact email - replace with placeholder
+        return dataFactory.quad(
+          quad.subject,
+          quad.predicate,
+          dataFactory.literal('[REDACTED]'),
+          quad.graph
+        );
+      }
+    }
+    return quad;
+  },
+  metadata: {
+    description: 'Privacy policy - redact email addresses',
+    policy: 'privacy',
+  },
+});
+
+/**
+ * Provenance Policy Hook
+ *
+ * Requires all quads to have provenance metadata.
+ */
+const provenancePolicy = defineHook({
+  name: 'provenance-policy',
+  trigger: 'before-add',
+  validate: quad => {
+    // In a real implementation, this would check for provenance metadata
+    // For example, check that quad.graph is not the default graph
+    return quad.graph && quad.graph.termType === 'NamedNode';
+  },
+  metadata: {
+    description: 'Provenance policy - require provenance metadata',
+    policy: 'audit',
+  },
+});
+
+/* ========================================================================= */
+/* Example Usage                                                             */
+/* ========================================================================= */
+
+/**
+ * Create and configure hook registry with policies.
+ */
+function setupPolicyRegistry() {
+  const registry = createHookRegistry();
+
+  // Register all policy hooks
+  registerHook(registry, aclPolicy);
+  registerHook(registry, dataTypePolicy);
+  registerHook(registry, privacyPolicy);
+  registerHook(registry, provenancePolicy);
+
+  return registry;
+}
+
+/**
+ * Test quads against policy hooks.
+ */
+function testPolicies() {
+  const registry = setupPolicyRegistry();
+  const store = createStore();
+
+  console.log('🔒 Policy Hooks Example\n');
+  console.log('='.repeat(60));
+
+  // Test 1: Trusted namespace (should pass ACL)
+  console.log('\n✅ Test 1: Trusted namespace');
+  const q1 = quad(
+    namedNode('http://example.org/alice'),
+    namedNode('http://xmlns.com/foaf/0.1/name'),
+    literal('Alice'),
+    namedNode('http://example.org/graph1')
+  );
+
+  const hooks1 = [aclPolicy, dataTypePolicy, privacyPolicy, provenancePolicy];
+  const results1 = executeHooksByTrigger(hooks1, 'before-add', q1);
+  const passedCount1 = results1.results.filter(r => r.valid).length;
+  console.log(`   Passed: ${passedCount1}/${results1.results.length}`);
+  console.log(`   Failed: ${results1.results.length - passedCount1}/${results1.results.length}`);
+  if (!results1.valid) {
+    results1.results.filter(r => !r.valid).forEach(r => console.log(`   ❌ ${r.hookName}: ${r.error}`));
+  }
+
+  // Test 2: Untrusted namespace (should fail ACL)
+  console.log('\n❌ Test 2: Untrusted namespace');
+  const q2 = quad(
+    namedNode('http://untrusted.org/bob'),
+    namedNode('http://untrusted.org/property'),
+    literal('Bob'),
+    namedNode('http://example.org/graph1')
+  );
+
+  const hooks2 = [aclPolicy, dataTypePolicy, privacyPolicy, provenancePolicy];
+  const results2 = executeHooksByTrigger(hooks2, 'before-add', q2);
+  const passedCount2 = results2.results.filter(r => r.valid).length;
+  console.log(`   Passed: ${passedCount2}/${results2.results.length}`);
+  console.log(`   Failed: ${results2.results.length - passedCount2}/${results2.results.length}`);
+  if (!results2.valid) {
+    results2.results.filter(r => !r.valid).forEach(r => console.log(`   ❌ ${r.hookName}: ${r.error}`));
+  }
+
+  // Test 3: Valid age (should pass data type policy)
+  console.log('\n✅ Test 3: Valid age constraint');
+  const q3 = quad(
+    namedNode('http://example.org/alice'),
+    namedNode('http://xmlns.com/foaf/0.1/age'),
+    literal('30'),
+    namedNode('http://example.org/graph1')
+  );
+
+  const hooks3 = [aclPolicy, dataTypePolicy, privacyPolicy, provenancePolicy];
+  const results3 = executeHooksByTrigger(hooks3, 'before-add', q3);
+  const passedCount3 = results3.results.filter(r => r.valid).length;
+  console.log(`   Passed: ${passedCount3}/${results3.results.length}`);
+  console.log(`   Failed: ${results3.results.length - passedCount3}/${results3.results.length}`);
+
+  // Test 4: Invalid age (should fail data type policy)
+  console.log('\n❌ Test 4: Invalid age constraint');
+  const q4 = quad(
+    namedNode('http://example.org/bob'),
+    namedNode('http://xmlns.com/foaf/0.1/age'),
+    literal('999'),
+    namedNode('http://example.org/graph1')
+  );
+
+  const hooks4 = [aclPolicy, dataTypePolicy, privacyPolicy, provenancePolicy];
+  const results4 = executeHooksByTrigger(hooks4, 'before-add', q4);
+  const passedCount4 = results4.results.filter(r => r.valid).length;
+  console.log(`   Passed: ${passedCount4}/${results4.results.length}`);
+  console.log(`   Failed: ${results4.results.length - passedCount4}/${results4.results.length}`);
+  if (!results4.valid) {
+    results4.results.filter(r => !r.valid).forEach(r => console.log(`   ❌ ${r.hookName}: ${r.error}`));
+  }
+
+  // Test 5: Email privacy transformation
+  console.log('\n🔐 Test 5: Privacy policy transformation');
+  const q5 = quad(
+    namedNode('http://example.org/alice'),
+    namedNode('http://xmlns.com/foaf/0.1/mbox'),
+    literal('alice@example.org'),
+    namedNode('http://example.org/graph1')
+  );
+
+  const privacyResult = executeHook(privacyPolicy, q5);
+  console.log(`   Status: ${privacyResult.valid ? 'PASSED' : 'FAILED'}`);
+  if (privacyResult.quad && privacyResult.quad.object.value !== q5.object.value) {
+    console.log(`   Original: ${q5.object.value}`);
+    console.log(`   Transformed: ${privacyResult.quad.object.value}`);
+  }
+
+  // Test 6: Missing provenance (should fail provenance policy)
+  console.log('\n❌ Test 6: Missing provenance');
+  const q6 = quad(
+    namedNode('http://example.org/charlie'),
+    namedNode('http://xmlns.com/foaf/0.1/name'),
+    literal('Charlie')
+    // No graph parameter - uses default graph
+  );
+
+  const hooks6 = [aclPolicy, dataTypePolicy, privacyPolicy, provenancePolicy];
+  const results6 = executeHooksByTrigger(hooks6, 'before-add', q6);
+  const passedCount6 = results6.results.filter(r => r.valid).length;
+  console.log(`   Passed: ${passedCount6}/${results6.results.length}`);
+  console.log(`   Failed: ${results6.results.length - passedCount6}/${results6.results.length}`);
+  if (!results6.valid) {
+    results6.results.filter(r => !r.valid).forEach(r => console.log(`   ❌ ${r.hookName}: ${r.error}`));
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log('✨ Policy Hooks Example Complete\n');
+}
+
+/* ========================================================================= */
+/* Export API                                                                */
+/* ========================================================================= */
+
+export {
+  aclPolicy,
+  dataTypePolicy,
+  privacyPolicy,
+  provenancePolicy,
+  setupPolicyRegistry,
+  testPolicies,
+};
+
+// Run example if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  testPolicies();
+}