@devilsdev/rag-pipeline-utils 2.4.5 → 2.6.0

package/src/security/plugin-signature-verifier.js

@@ -3,6 +3,22 @@
  * Verifies Ed25519 digital signatures for plugin manifests to ensure authenticity
  * Enforces fail-closed verification for production security
  *
+ * What is signed: the canonical JSON of the manifest (keys sorted
+ * recursively, without `signature`, `signerId` and `signedAt`). To bind the
+ * plugin's code to the signature, put a `contentDigest` in the manifest
+ * before signing (see computeContentDigest). Because `contentDigest` is part
+ * of the signed manifest, changing any covered file invalidates it.
+ *
+ * Defaults (2.5.0):
+ * - The trust store starts EMPTY. Nothing verifies until a signer is added
+ *   with addTrustedSigner() or a trustedKeysPath file.
+ * - If a manifest declares `contentDigest`, the plugin content (files or
+ *   contents) MUST be supplied to verifyPluginSignature() and must match;
+ *   otherwise verification fails.
+ * - A manifest without `contentDigest` still verifies (manifest-only
+ *   signatures keep working); pass `requireContentDigest: true` to reject
+ *   manifests that do not bind the code.
+ *
  * @author DevilsDev Team
  * @since 2.1.8
  */
@@ -12,6 +28,132 @@ const fs = require('fs');
 const path = require('path');
 const { logger } = require('../utils/logger');
 
+const DIGEST_PREFIX = 'sha256-';
+const HEX_KEY_RE = /^[0-9a-fA-F]{64}$/;
+const INVALID_KEY_MESSAGE =
+  'Public key must be 64 hex characters (32 bytes), or a PEM/DER-encoded Ed25519 public key';
+
+/**
+ * Convert supported public key encodings to an Ed25519 KeyObject.
+ *
+ * Accepted: a KeyObject; a 64-character hex string or 32-byte Buffer (raw
+ * key); a PEM string ("-----BEGIN PUBLIC KEY-----"); a DER (SPKI) Buffer or
+ * base64 string.
+ *
+ * @param {crypto.KeyObject|Buffer|string} publicKey
+ * @returns {crypto.KeyObject}
+ */
+function toEd25519PublicKey(publicKey) {
+  let keyObject;
+  try {
+    if (publicKey instanceof crypto.KeyObject) {
+      keyObject =
+        publicKey.type === 'private'
+          ? crypto.createPublicKey(publicKey)
+          : publicKey;
+    } else if (Buffer.isBuffer(publicKey) && publicKey.length === 32) {
+      keyObject = rawToKeyObject(publicKey);
+    } else if (Buffer.isBuffer(publicKey)) {
+      keyObject = crypto.createPublicKey({
+        key: publicKey,
+        format: 'der',
+        type: 'spki',
+      });
+    } else if (typeof publicKey === 'string' && HEX_KEY_RE.test(publicKey)) {
+      keyObject = rawToKeyObject(Buffer.from(publicKey, 'hex'));
+    } else if (
+      typeof publicKey === 'string' &&
+      publicKey.includes('-----BEGIN')
+    ) {
+      keyObject = crypto.createPublicKey({ key: publicKey, format: 'pem' });
+    } else if (typeof publicKey === 'string' && publicKey.length > 0) {
+      keyObject = crypto.createPublicKey({
+        key: Buffer.from(publicKey, 'base64'),
+        format: 'der',
+        type: 'spki',
+      });
+    }
+  } catch {
+    keyObject = undefined;
+  }
+
+  if (
+    !keyObject ||
+    keyObject.type !== 'public' ||
+    keyObject.asymmetricKeyType !== 'ed25519'
+  ) {
+    throw new Error(INVALID_KEY_MESSAGE);
+  }
+  return keyObject;
+}
+
+function rawToKeyObject(raw) {
+  return crypto.createPublicKey({
+    key: { kty: 'OKP', crv: 'Ed25519', x: raw.toString('base64url') },
+    format: 'jwk',
+  });
+}
+
+/**
+ * Compute the content digest of a plugin.
+ *
+ * The digest is `sha256-<hex>` of the lines `<relativePath>\0<sha256 of
+ * file>\n`, sorted by relative path. Paths are relative to `baseDir` and use
+ * forward slashes, so the digest is identical on Windows and POSIX.
+ *
+ * @param {Object} options
+ * @param {string[]} [options.files] - File paths (absolute or relative to baseDir)
+ * @param {string} [options.baseDir] - Plugin root; files must be inside it
+ * @param {Object<string, Buffer|string>} [options.contents] - In-memory
+ *   files keyed by relative path (alternative or addition to `files`)
+ * @returns {string} `sha256-<hex>`
+ */
+function computeContentDigest({ files = [], baseDir, contents = {} } = {}) {
+  const root = path.resolve(baseDir || process.cwd());
+  const entries = new Map();
+
+  for (const file of files) {
+    const abs = path.resolve(root, file);
+    const rel = path.relative(root, abs);
+    if (
+      !rel ||
+      rel === '..' ||
+      rel.startsWith(`..${path.sep}`) ||
+      path.isAbsolute(rel)
+    ) {
+      throw new Error(`Plugin file is outside the plugin directory: ${file}`);
+    }
+    entries.set(rel.split(path.sep).join('/'), fs.readFileSync(abs));
+  }
+
+  for (const [name, value] of Object.entries(contents)) {
+    const rel = path.posix.normalize(String(name).split('\\').join('/'));
+    if (
+      rel === '..' ||
+      rel.startsWith('../') ||
+      rel === '.' ||
+      path.posix.isAbsolute(rel)
+    ) {
+      throw new Error(`Plugin content path is not relative: ${name}`);
+    }
+    entries.set(rel, Buffer.isBuffer(value) ? value : Buffer.from(value));
+  }
+
+  if (entries.size === 0) {
+    throw new Error('No plugin content supplied for digest');
+  }
+
+  const hash = crypto.createHash('sha256');
+  for (const rel of [...entries.keys()].sort()) {
+    const fileHash = crypto
+      .createHash('sha256')
+      .update(entries.get(rel))
+      .digest('hex');
+    hash.update(`${rel}\0${fileHash}\n`, 'utf8');
+  }
+  return DIGEST_PREFIX + hash.digest('hex');
+}
+
 /**
  * Plugin signature verification with Ed25519
  */
@@ -22,23 +164,20 @@ class PluginSignatureVerifier {
     this.auditLogger =
       options.auditLogger || this._defaultAuditLogger.bind(this);
     this.failClosed = options.failClosed !== false; // Default to fail-closed
+    // Opt-in: reject manifests that do not bind the plugin code
+    this.requireContentDigest = options.requireContentDigest === true;
 
     // Load trusted public keys
     this._loadTrustedKeys(options.trustedKeysPath);
   }
 
   /**
-   * Load trusted public keys from configuration
+   * Load trusted public keys from configuration.
+   * Without a keys file the trust store stays empty (no built-in keys).
    * @param {string} keysPath - Path to trusted keys file
    */
   _loadTrustedKeys(keysPath) {
     if (!keysPath) {
-      // Default trusted keys for the DevilsDev organization
-      this.trustStore.set('devilsdev-official', {
-        publicKey: 'your-ed25519-public-key-here',
-        name: 'DevilsDev Official Plugins',
-        verified: true,
-      });
       return;
     }
 
@@ -49,6 +188,8 @@ class PluginSignatureVerifier {
 
         for (const [keyId, keyInfo] of Object.entries(trustedKeys)) {
           if (keyInfo.publicKey && keyInfo.name) {
+            // Reject unusable keys up front instead of at verification time
+            toEd25519PublicKey(keyInfo.publicKey);
             this.trustStore.set(keyId, keyInfo);
           }
         }
@@ -57,6 +198,9 @@ class PluginSignatureVerifier {
       if (this.failClosed) {
         throw new Error(`Failed to load trusted keys: ${error.message}`);
       }
+      logger.warn(
+        `[PLUGIN_SIGNATURE] Failed to load trusted keys: ${error.message}`,
+      );
     }
   }
 
@@ -65,11 +209,15 @@ class PluginSignatureVerifier {
    * @param {object} manifest - Plugin manifest
    * @param {string} signature - Base64 encoded signature
    * @param {string} signerId - Signer identifier
+   * @param {object} [content] - Plugin content to check against
+   *   manifest.contentDigest: `{ files, baseDir, contents }` (see
+   *   computeContentDigest)
    * @returns {Promise<object>} Verification result
    */
-  async verifyPluginSignature(manifest, signature, signerId) {
+  async verifyPluginSignature(manifest, signature, signerId, content = null) {
     const verificationResult = {
       verified: false,
+      contentVerified: false,
       signerId,
       timestamp: new Date().toISOString(),
       error: null,
@@ -115,15 +263,8 @@ class PluginSignatureVerifier {
         'utf8',
       );
 
-      // Decode signature
-      let signatureBuffer;
-      try {
-        signatureBuffer = Buffer.from(signature, 'base64');
-      } catch (error) {
-        throw new Error(`Invalid signature encoding: ${error.message}`);
-      }
+      const signatureBuffer = Buffer.from(signature, 'base64');
 
-      // Verify signature using Web Crypto API or Node.js crypto
       const isValid = await this._verifyEd25519Signature(
         manifestData,
         signatureBuffer,
@@ -134,14 +275,22 @@ class PluginSignatureVerifier {
         throw new Error('Signature verification failed');
       }
 
+      // The signature covers contentDigest; now check the code matches it.
+      verificationResult.contentVerified = this._verifyContentDigest(
+        canonicalManifest,
+        content,
+      );
+
       verificationResult.verified = true;
       verificationResult.auditTrail.push({
         action: 'signature_verified',
         signerId,
         timestamp: new Date().toISOString(),
         manifestHash: this._hashManifest(canonicalManifest),
+        contentVerified: verificationResult.contentVerified,
       });
     } catch (error) {
+      verificationResult.verified = false;
       verificationResult.error = error.message;
       verificationResult.auditTrail.push({
         action: 'verification_failed',
@@ -163,58 +312,66 @@ class PluginSignatureVerifier {
   }
 
   /**
-   * Verify Ed25519 signature
-   * @param {Buffer} data - Data that was signed
-   * @param {Buffer} signature - Signature bytes
-   * @param {string} publicKeyHex - Public key in hex format
-   * @returns {Promise<boolean>} Verification result
+   * Check the supplied plugin content against the signed contentDigest.
+   * @param {object} canonicalManifest - Signed manifest
+   * @param {object|null} content - `{ files, baseDir, contents }`
+   * @returns {boolean} true when the content digest was checked and matched
+   * @private
    */
-  async _verifyEd25519Signature(data, signature, publicKeyHex) {
-    try {
-      // Convert hex public key to buffer
-      const publicKeyBuffer = Buffer.from(publicKeyHex, 'hex');
-
-      // Use Node.js crypto for Ed25519 verification
-      const verify = crypto.createVerify('Ed25519');
-      verify.update(data);
+  _verifyContentDigest(canonicalManifest, content) {
+    const declared = canonicalManifest.contentDigest;
+    const hasContent =
+      content &&
+      ((Array.isArray(content.files) && content.files.length > 0) ||
+        (content.contents && Object.keys(content.contents).length > 0));
+
+    if (declared === undefined || declared === null) {
+      if (this.requireContentDigest) {
+        throw new Error(
+          'Manifest has no contentDigest; the signature does not cover the plugin code',
+        );
+      }
+      return false;
+    }
 
-      // Create public key object
-      const publicKeyObject = crypto.createPublicKey({
-        key: publicKeyBuffer,
-        format: 'der',
-        type: 'spki',
-      });
+    if (typeof declared !== 'string' || !declared.startsWith(DIGEST_PREFIX)) {
+      throw new Error('Invalid contentDigest: expected "sha256-<hex>"');
+    }
 
-      return verify.verify(publicKeyObject, signature);
-    } catch (error) {
-      // Fallback to Web Crypto API if available
-      if (typeof crypto.subtle !== 'undefined') {
-        try {
-          const publicKeyBuffer = Buffer.from(publicKeyHex, 'hex');
-          const publicKey = await crypto.subtle.importKey(
-            'raw',
-            publicKeyBuffer,
-            {
-              name: 'Ed25519',
-              namedCurve: 'Ed25519',
-            },
-            false,
-            ['verify'],
-          );
+    if (!hasContent) {
+      throw new Error(
+        'Manifest declares a contentDigest but no plugin content was supplied to verify it',
+      );
+    }
 
-          return await crypto.subtle.verify(
-            'Ed25519',
-            publicKey,
-            signature,
-            data,
-          );
-        } catch (webCryptoError) {
-          throw new Error(`Ed25519 verification failed: ${error.message}`);
-        }
-      }
+    const actual = Buffer.from(computeContentDigest(content), 'utf8');
+    const expected = Buffer.from(declared.toLowerCase(), 'utf8');
+    if (
+      actual.length !== expected.length ||
+      !crypto.timingSafeEqual(actual, expected)
+    ) {
+      throw new Error(
+        'Plugin content digest mismatch: plugin code does not match the signed manifest',
+      );
+    }
+    return true;
+  }
 
-      throw new Error(`Ed25519 verification failed: ${error.message}`);
+  /**
+   * Verify Ed25519 signature
+   * @param {Buffer} data - Data that was signed
+   * @param {Buffer} signature - Signature bytes
+   * @param {crypto.KeyObject|Buffer|string} publicKey - Ed25519 public key
+   *   (raw hex, PEM, DER or KeyObject)
+   * @returns {Promise<boolean>} Verification result
+   */
+  async _verifyEd25519Signature(data, signature, publicKey) {
+    const keyObject = toEd25519PublicKey(publicKey);
+    if (!Buffer.isBuffer(signature) || signature.length !== 64) {
+      return false;
     }
+    // Ed25519 takes no digest algorithm: pass null.
+    return crypto.verify(null, data, keyObject, signature);
   }
 
   /**
@@ -233,6 +390,18 @@ class PluginSignatureVerifier {
     return this._sortObjectKeys(canonical);
   }
 
+  /**
+   * Bytes that a signer must sign for a manifest (canonical JSON).
+   * @param {object} manifest - Plugin manifest
+   * @returns {Buffer}
+   */
+  getSigningPayload(manifest) {
+    return Buffer.from(
+      JSON.stringify(this._canonicalizeManifest(manifest)),
+      'utf8',
+    );
+  }
+
   /**
    * Sort object keys recursively
    * @param {any} obj - Object to sort
@@ -276,10 +445,11 @@ class PluginSignatureVerifier {
     const auditEntry = {
       timestamp: result.timestamp,
       action: 'plugin_signature_verification',
-      pluginId: manifest.name || 'unknown',
-      pluginVersion: manifest.version || 'unknown',
+      pluginId: (manifest && manifest.name) || 'unknown',
+      pluginVersion: (manifest && manifest.version) || 'unknown',
       signerId: result.signerId,
       verified: result.verified,
+      contentVerified: result.contentVerified,
       error: result.error,
       auditTrail: result.auditTrail,
     };
@@ -309,7 +479,8 @@ class PluginSignatureVerifier {
   /**
    * Add trusted signer
    * @param {string} signerId - Signer identifier
-   * @param {string} publicKey - Ed25519 public key in hex
+   * @param {string|Buffer|crypto.KeyObject} publicKey - Ed25519 public key:
+   *   64 hex characters (raw 32 bytes), PEM, DER (SPKI) or a KeyObject
    * @param {string} name - Human-readable name
    * @param {object} metadata - Additional metadata
    */
@@ -318,13 +489,15 @@ class PluginSignatureVerifier {
       throw new Error('signerId, publicKey, and name are required');
     }
 
-    // Validate public key format
-    if (!/^[0-9a-fA-F]{64}$/.test(publicKey)) {
-      throw new Error('Public key must be 64 hex characters (32 bytes)');
-    }
+    // Validate the key is a usable Ed25519 public key
+    const keyObject = toEd25519PublicKey(publicKey);
+    const storedKey =
+      typeof publicKey === 'string' && HEX_KEY_RE.test(publicKey)
+        ? publicKey.toLowerCase()
+        : keyObject.export({ format: 'pem', type: 'spki' });
 
     this.trustStore.set(signerId, {
-      publicKey: publicKey.toLowerCase(),
+      publicKey: storedKey,
       name,
       verified: metadata.verified || false,
       addedAt: new Date().toISOString(),
@@ -409,4 +582,6 @@ function createPluginVerifier(options = {}) {
 module.exports = {
   PluginSignatureVerifier,
   createPluginVerifier,
+  computeContentDigest,
+  toEd25519PublicKey,
 };

package/src/testing.js

@@ -0,0 +1,254 @@
+'use strict';
+
+/**
+ * @devilsdev/rag-pipeline-utils/testing
+ *
+ * Deterministic, offline stand-ins for testing code that uses this library:
+ * no network, no API keys, the same output on every run.
+ *
+ * - HashEmbedder: bag-of-words vectors from hashed words.
+ * - EchoLLM: answers with the top retrieved document (or an answer you set)
+ *   and records every call.
+ * - fixtures: a few short policy documents.
+ * - createTestPipeline(): a ready, indexed pipeline built from the above.
+ */
+
+const { createRagPipeline } = require('./core/create-pipeline');
+const { MemoryRetriever } = require('./connectors/memory-retriever');
+
+function throwIfAborted(signal) {
+  if (signal && signal.aborted) {
+    throw signal.reason || new Error('Aborted');
+  }
+}
+
+/**
+ * Deterministic embedder: hashed bag of words, L2-normalised. Texts that
+ * share words get similar vectors, so retrieval ranks sensibly in tests.
+ */
+class HashEmbedder {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.dimensions=256] - Vector length
+   */
+  constructor({ dimensions = 256 } = {}) {
+    if (!Number.isInteger(dimensions) || dimensions < 1) {
+      throw new Error('dimensions must be a positive integer');
+    }
+    this.dimensions = dimensions;
+    this.metadata = {
+      name: 'hash-embedder',
+      version: '1.0.0',
+      type: 'embedder',
+    };
+  }
+
+  /**
+   * Cache identity for createRagPipeline({ cache }).
+   * @param {string} role
+   * @returns {string|null}
+   */
+  getCacheKey(role) {
+    return role === 'embedder' ? `hash-embedder|${this.dimensions}` : null;
+  }
+
+  /** @private */
+  _vector(text) {
+    const vector = new Array(this.dimensions).fill(0);
+    for (const word of String(text)
+      .toLowerCase()
+      .match(/[\p{L}\p{N}]+/gu) || []) {
+      let hash = 2166136261;
+      for (const ch of word) {
+        hash ^= ch.codePointAt(0);
+        hash = Math.imul(hash, 16777619) >>> 0;
+      }
+      // FNV-1a's low bits are weak (e.g. "above" and "vacation" agree in
+      // their low 10 bits), so mix them (MurmurHash3 fmix32) before taking
+      // the bucket.
+      hash ^= hash >>> 16;
+      hash = Math.imul(hash, 0x85ebca6b);
+      hash ^= hash >>> 13;
+      hash = Math.imul(hash, 0xc2b2ae35);
+      hash ^= hash >>> 16;
+      hash >>>= 0;
+      // Signed feature hashing: the top bit picks the sign, so colliding
+      // words cancel out on average instead of adding up.
+      vector[hash % this.dimensions] += hash & 0x80000000 ? -1 : 1;
+    }
+    const norm = Math.hypot(...vector);
+    return norm > 0 ? vector.map((v) => v / norm) : vector;
+  }
+
+  /**
+   * @param {string} text
+   * @param {{ signal?: AbortSignal }} [options]
+   * @returns {Promise<number[]>}
+   */
+  async embed(text, { signal } = {}) {
+    throwIfAborted(signal);
+    return this._vector(text);
+  }
+
+  /**
+   * Same as embed().
+   * @param {string} text
+   * @param {{ signal?: AbortSignal }} [options]
+   * @returns {Promise<number[]>}
+   */
+  async embedQuery(text, options) {
+    return this.embed(text, options);
+  }
+
+  /**
+   * @param {string[]} texts
+   * @param {{ signal?: AbortSignal }} [options]
+   * @returns {Promise<number[][]>}
+   */
+  async embedBatch(texts, { signal } = {}) {
+    throwIfAborted(signal);
+    return texts.map((t) => this._vector(t));
+  }
+}
+
+/**
+ * LLM stand-in. Answers with `answer` (a string, or a function of the query
+ * and documents), or else with the top document's content. Every call is
+ * recorded in `calls`, so tests can assert on what the pipeline sent.
+ */
+class EchoLLM {
+  /**
+   * @param {Object} [options]
+   * @param {string|function(string, Array<Object>): string} [options.answer]
+   * @param {string} [options.fallback='No information found.'] - Answer when
+   *   there are no documents and no `answer`
+   */
+  constructor({ answer, fallback = 'No information found.' } = {}) {
+    this.answer = answer;
+    this.fallback = fallback;
+    /** @type {Array<{query: string, docs: Array<Object>, options: Object}>} */
+    this.calls = [];
+    this.metadata = { name: 'echo-llm', version: '1.0.0', type: 'llm' };
+  }
+
+  /**
+   * Cache identity for createRagPipeline({ cache }); none when `answer` is a
+   * function, since its output cannot be identified.
+   * @param {string} role
+   * @returns {string|null}
+   */
+  getCacheKey(role) {
+    if (role !== 'llm' || typeof this.answer === 'function') return null;
+    return `echo-llm|${JSON.stringify([this.answer ?? null, this.fallback])}`;
+  }
+
+  /** @private */
+  _answer(query, docs) {
+    if (typeof this.answer === 'function')
+      return String(this.answer(query, docs));
+    if (typeof this.answer === 'string') return this.answer;
+    const top = docs && docs[0];
+    if (!top) return this.fallback;
+    return typeof top === 'string'
+      ? top
+      : String(top.content ?? top.text ?? '');
+  }
+
+  /**
+   * @param {string} query
+   * @param {Array<Object>} [docs]
+   * @param {{ signal?: AbortSignal }} [options]
+   * @returns {Promise<string>}
+   */
+  async generate(query, docs = [], options = {}) {
+    throwIfAborted(options.signal);
+    this.calls.push({ query, docs, options });
+    return this._answer(query, docs);
+  }
+
+  /**
+   * Streams the same answer word by word, then a done chunk.
+   * @param {string} query
+   * @param {Array<Object>} [docs]
+   * @param {{ signal?: AbortSignal }} [options]
+   * @yields {{ token: string, done: boolean }}
+   */
+  async *generateStream(query, docs = [], options = {}) {
+    throwIfAborted(options.signal);
+    this.calls.push({ query, docs, options, stream: true });
+    for (const token of this._answer(query, docs).split(/(?<= )/)) {
+      throwIfAborted(options.signal);
+      yield { token, done: false };
+    }
+    yield { token: '', done: true };
+  }
+}
+
+/** Short documents for tests and examples. */
+const fixtures = Object.freeze({
+  documents: Object.freeze([
+    Object.freeze({
+      id: 'vacation',
+      content:
+        'Full-time employees receive twenty days of paid vacation per year. Unused days carry over to March.',
+      metadata: Object.freeze({ source: 'vacation.md' }),
+    }),
+    Object.freeze({
+      id: 'remote-work',
+      content:
+        'Employees may work remotely up to three days per week with manager approval.',
+      metadata: Object.freeze({ source: 'remote-work.md' }),
+    }),
+    Object.freeze({
+      id: 'expenses',
+      content:
+        'Submit receipts within thirty days. Travel above 500 EUR needs pre-approval from finance.',
+      metadata: Object.freeze({ source: 'expenses.md' }),
+    }),
+  ]),
+});
+
+/**
+ * A pipeline with HashEmbedder, a MemoryRetriever already holding
+ * `documents`, and EchoLLM (or the llm you pass).
+ *
+ * @example
+ * const { createTestPipeline } = require('@devilsdev/rag-pipeline-utils/testing');
+ * const { pipeline, llm } = await createTestPipeline();
+ * const result = await pipeline.run({ query: 'How many vacation days?' });
+ * // result.results[0].id === 'vacation'; llm.calls.length === 1
+ *
+ * @param {Object} [options]
+ * @param {Array<{id: string, content: string, metadata?: Object}>} [options.documents=fixtures.documents]
+ * @param {Object} [options.embedder] - Defaults to a new HashEmbedder
+ * @param {Object|null} [options.llm] - Defaults to a new EchoLLM; null for retrieval only
+ * @param {Object} [options.pipeline] - Extra createRagPipeline options (e.g. reranker)
+ * @returns {Promise<{ pipeline: Object, embedder: Object, retriever: MemoryRetriever, llm: Object|null }>}
+ */
+async function createTestPipeline({
+  documents = fixtures.documents,
+  embedder = new HashEmbedder(),
+  llm = new EchoLLM(),
+  pipeline: pipelineOptions = {},
+} = {}) {
+  const retriever = new MemoryRetriever();
+  const vectors = await Promise.all(
+    documents.map((d) => embedder.embed(d.content)),
+  );
+  await retriever.store(
+    documents.map((d, i) => ({
+      ...d,
+      metadata: { ...(d.metadata || {}) },
+      vector: vectors[i],
+    })),
+  );
+  const pipeline = createRagPipeline({
+    ...pipelineOptions,
+    embedder,
+    retriever,
+    ...(llm && { llm }),
+  });
+  return { pipeline, embedder, retriever, llm: llm || null };
+}
+
+module.exports = { HashEmbedder, EchoLLM, fixtures, createTestPipeline };