@devilsdev/rag-guardrails 0.0.0-stage → 3.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Kahwaji
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @devilsdev/rag-guardrails
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Guardrails for RAG: prompt-injection detection and pre-retrieval, retrieval and post-generation guards.
+
+Part of [@devilsdev/rag-pipeline-utils](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils), split into packages so you install only what you use. The objects are the same ones the full package exports; versions move in lockstep.
+
+```bash
+npm install @devilsdev/rag-guardrails
+```
+
+Exports: `PreRetrievalGuard`, `detectInjection`, `RetrievalGuard`, `PostGenerationGuard`, `GuardrailsPipeline`.
+
+Documentation: https://devilsdev.github.io/rag-pipeline-utils/
+
+The other packages:
+
+- [`@devilsdev/rag-core`](https://www.npmjs.com/package/@devilsdev/rag-core)
+- [`@devilsdev/rag-connectors`](https://www.npmjs.com/package/@devilsdev/rag-connectors)
+- [`@devilsdev/rag-eval`](https://www.npmjs.com/package/@devilsdev/rag-eval)

package/dist/index.cjs

@@ -0,0 +1,850 @@
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __commonJS = (cb, mod2) => function __require() {
+  return mod2 || (0, cb[__getOwnPropNames(cb)[0]])((mod2 = { exports: {} }).exports, mod2), mod2.exports;
+};
+
+// src/security/validator.js
+var require_validator = __commonJS({
+  "src/security/validator.js"(exports2, module2) {
+    "use strict";
+    function validateInput(input, opts = {}) {
+      const maxLength = opts.maxLength || 2e4;
+      const inputStr = String(input);
+      const reasons = [];
+      if (inputStr.length > maxLength) {
+        reasons.push(`Input exceeds maximum length of ${maxLength} characters`);
+      }
+      const disallowedTokens = ["```", "${", "</script", "--", ";", "||", "&&"];
+      const lowerInput = inputStr.toLowerCase();
+      for (const token of disallowedTokens) {
+        if (lowerInput.includes(token.toLowerCase())) {
+          reasons.push(`Input contains disallowed token: ${token}`);
+        }
+      }
+      const valid = reasons.length === 0;
+      const sanitized = inputStr.substring(0, maxLength);
+      return {
+        valid,
+        reasons,
+        sanitized
+      };
+    }
+    module2.exports = { validateInput };
+  }
+});
+
+// scoped:@devilsdev/rag-core|evaluate/scoring.js
+var require_scoring = __commonJS({
+  "scoped:@devilsdev/rag-core|evaluate/scoring.js"(exports2, module2) {
+    module2.exports = require("@devilsdev/rag-core")[Symbol.for("@devilsdev/rag-core/internal")]("evaluate/scoring.js");
+  }
+});
+
+// src/guardrails/injection-detector.js
+var require_injection_detector = __commonJS({
+  "src/guardrails/injection-detector.js"(exports2, module2) {
+    "use strict";
+    function charClass(items) {
+      const hex = (cp) => "\\u" + cp.toString(16).padStart(4, "0");
+      return items.map((it) => Array.isArray(it) ? `${hex(it[0])}-${hex(it[1])}` : hex(it)).join("");
+    }
+    var INVISIBLE_RE = new RegExp(
+      `[${charClass([
+        173,
+        // soft hyphen
+        847,
+        // combining grapheme joiner
+        1564,
+        // arabic letter mark
+        4447,
+        4448,
+        // hangul fillers
+        6068,
+        6069,
+        [6155, 6159],
+        // mongolian variation selectors / vowel separator
+        [8203, 8207],
+        // zero-width space/joiners, LRM/RLM
+        [8234, 8238],
+        // bidi embeddings/overrides
+        [8288, 8303],
+        // word joiner, invisible operators, bidi isolates
+        12644,
+        // hangul filler
+        [65024, 65039],
+        // variation selectors
+        65279,
+        // BOM / zero-width no-break space
+        65440
+        // halfwidth hangul filler
+      ])}]`,
+      "g"
+    );
+    var CONTROL_RE = new RegExp(
+      `[${charClass([[0, 8], 11, 12, [14, 31], [127, 159]])}]`,
+      "g"
+    );
+    var HOMOGLYPH_CODEPOINTS = [
+      // Cyrillic
+      [1072, "a"],
+      [1074, "b"],
+      [1077, "e"],
+      [1105, "e"],
+      [1082, "k"],
+      [1084, "m"],
+      [1085, "h"],
+      [1086, "o"],
+      [1088, "p"],
+      [1089, "c"],
+      [1090, "t"],
+      [1091, "y"],
+      [1093, "x"],
+      [1109, "s"],
+      [1110, "i"],
+      [1111, "i"],
+      [1112, "j"],
+      [1281, "d"],
+      [1307, "q"],
+      [1309, "w"],
+      [1231, "l"],
+      [609, "g"],
+      // Greek
+      [945, "a"],
+      [946, "b"],
+      [949, "e"],
+      [951, "n"],
+      [953, "i"],
+      [954, "k"],
+      [957, "v"],
+      [959, "o"],
+      [961, "p"],
+      [964, "t"],
+      [965, "u"],
+      [967, "x"],
+      [969, "w"],
+      [1010, "c"]
+    ];
+    var HOMOGLYPHS = Object.fromEntries(
+      HOMOGLYPH_CODEPOINTS.map(([cp, letter]) => [
+        String.fromCodePoint(cp),
+        letter
+      ])
+    );
+    var LEET = {
+      0: "o",
+      1: "i",
+      3: "e",
+      4: "a",
+      5: "s",
+      7: "t",
+      8: "b",
+      "@": "a",
+      $: "s",
+      "!": "i",
+      "|": "l"
+    };
+    function normalizeText(text) {
+      return String(text).normalize("NFKC").replace(INVISIBLE_RE, "").replace(CONTROL_RE, " ").normalize("NFD").replace(new RegExp("\\p{Mn}+", "gu"), "").normalize("NFC").replace(/[^\S\n]+/g, " ").replace(/ ?\n\s*/g, "\n").trim();
+    }
+    function foldText(text) {
+      const lower = normalizeText(text).toLowerCase();
+      let out = "";
+      for (const ch of lower) {
+        out += HOMOGLYPHS[ch] || LEET[ch] || ch;
+      }
+      return out.replace(
+        /\b(?:[a-z][.\-_* ]){3,}[a-z]\b/g,
+        (m) => m.replace(/[.\-_* ]/g, "")
+      );
+    }
+    var DEFAULT_RULES = [
+      {
+        id: "ignore-instructions",
+        pattern: /\b(?:ignore|disregard|forget|skip|override|bypass)\s+(?:all\s+|any\s+|the\s+|your\s+|my\s+|of\s+)*(?:previous|prior|above|preceding|earlier|former|original|system|initial)\s+(?:instructions?|prompts?|directions?|directives?|rules|guidelines|context|messages?)\b/
+      },
+      {
+        id: "forget-everything",
+        pattern: /\bforget\s+(?:everything|all)\s+(?:you(?:'ve|\s+have|\s+were|\s+know|\s+learned)|(?:previous|prior|above|before|that\s+came))/
+      },
+      {
+        id: "role-override",
+        pattern: /\byou\s+are\s+now\s+(?:an?\s+|my\s+|the\s+)?(?:[a-z'-]+\s+){0,2}(?:ai|assistant|bot|chatbot|model|llm|dan|hacker|unrestricted|unfiltered|uncensored|jailbroken|evil|persona|character)\b|\byou\s+are\s+now\s+(?:in\s+)?(?:developer|dan|god|admin|jailbreak|unrestricted)\s+mode\b|\byou\s+are\s+no\s+longer\s+(?:an?\s+)?(?:ai|assistant|bound|restricted|limited|chatgpt|claude)\b|\byou\s+are\s+dan\b/
+      },
+      {
+        // "act as" only in imperative position: start of text/sentence, or after
+        // please/now/you must/will/should. "Redis acts as a cache" is not flagged.
+        id: "act-as",
+        pattern: /(?:^|[.!?:;\n]\s*|\b(?:please|now|you\s+(?:must|will|should|shall|can|are\s+to)|i\s+want\s+you\s+to)\s+)act\s+as\s+(?:if\s+you\b|an?\s+|my\s+|the\s+|though\b)/
+      },
+      {
+        id: "pretend",
+        pattern: /\bpretend\s+(?:that\s+)?(?:you\s+are|you're|youre|you\s+have\s+no|to\s+be\s+(?:an?\s+)?(?:\w+\s+)?(?:ai|assistant|model|bot|chatbot|dan|unrestricted|unfiltered|uncensored|evil|hacker|jailbroken))\b/
+      },
+      {
+        // Chat-template role markers: "system:" as a line prefix, [system],
+        // <|im_start|>system, [INST], <<SYS>>, "### system".
+        id: "role-marker",
+        pattern: /(?:^|\n)\s*(?:system|assistant|developer)\s*:|\[\s*(?:system|inst)\s*\]|<\|?\s*(?:im_start|system)\s*\|?>|<<\s*sys\s*>>|#{2,}\s*(?:system|instruction)s?\b/
+      },
+      {
+        id: "dan",
+        pattern: /\bdan\s+(?:mode|prompt|jailbreak)\b|\bdo\s+anything\s+now\b/
+      },
+      {
+        id: "bypass-restrictions",
+        pattern: /\b(?:bypass|circumvent|evade)\s+(?:all\s+|any\s+|your\s+|the\s+|of\s+)*(?:ai\s+|safety\s+|content\s+|ethical\s+)?(?:restrictions|guardrails|safeguards|safety\s+(?:rules|measures|guidelines|filters?)|content\s+(?:polic(?:y|ies)|filters?)|moderation)\b|\b(?:disable|ignore|remove|turn\s+off|drop)\s+(?:all\s+(?:of\s+)?)?your\s+(?:safety\s+|content\s+|ethical\s+)?(?:restrictions|filters?|guardrails|safeguards|safety|rules|guidelines|programming)\b/
+      },
+      {
+        id: "override-safety",
+        pattern: /\boverride\s+(?:your\s+|the\s+|all\s+)?(?:safety|content\s+(?:filters?|polic(?:y|ies))|system\s+(?:prompt|instructions?))\b/
+      },
+      {
+        id: "jailbreak",
+        pattern: /\bjailbr(?:ea|o)k(?:ing|en)?\s+(?:the\s+|this\s+|your\s+|an?\s+)?(?:model|ai|assistant|llm|chatbot|gpt|claude|system|prompt|you)\b|\bjailbreak\s+(?:mode|prompt)\b|\byou\s+are\s+jailbroken\b/
+      },
+      {
+        id: "prompt-exfiltration",
+        pattern: /\b(?:reveal|show|print|repeat|output|leak|display|tell\s+me)\s+(?:me\s+)?(?:your|the)\s+(?:system\s+prompt|hidden\s+(?:prompt|instructions)|initial\s+(?:prompt|instructions)|original\s+(?:prompt|instructions)|instructions\s+above)\b/
+      }
+    ];
+    function toStatelessRegExp(pattern) {
+      if (pattern instanceof RegExp) {
+        if (!pattern.global && !pattern.sticky) return pattern;
+        return new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ""));
+      }
+      return new RegExp(String(pattern), "i");
+    }
+    function detectInjection(text, opts = {}) {
+      const normalized = normalizeText(text == null ? "" : text);
+      const lower = normalized.toLowerCase();
+      const folded = foldText(normalized);
+      const matches = [];
+      if (opts.useDefaults !== false) {
+        for (const rule of DEFAULT_RULES) {
+          const m = rule.pattern.exec(lower) || rule.pattern.exec(folded);
+          if (m) {
+            matches.push({
+              id: rule.id,
+              pattern: String(rule.pattern),
+              match: m[0].trim()
+            });
+          }
+        }
+      }
+      for (const raw of opts.patterns || []) {
+        const re = toStatelessRegExp(raw);
+        const m = re.exec(normalized) || re.exec(folded);
+        if (m) {
+          matches.push({ id: "custom", pattern: String(raw), match: m[0].trim() });
+        }
+      }
+      return { detected: matches.length > 0, matches, normalized };
+    }
+    module2.exports = {
+      detectInjection,
+      normalizeText,
+      foldText,
+      DEFAULT_RULES
+    };
+  }
+});
+
+// src/guardrails/pre-retrieval-guard.js
+var require_pre_retrieval_guard = __commonJS({
+  "src/guardrails/pre-retrieval-guard.js"(exports2, module2) {
+    "use strict";
+    var { EventEmitter } = require("events");
+    var { validateInput } = require_validator();
+    var { tokenize } = require_scoring();
+    var { detectInjection, DEFAULT_RULES } = require_injection_detector();
+    var DEFAULT_CONFIG = {
+      maxQueryLength: 1e4,
+      enableInjectionDetection: true,
+      enableTopicFiltering: false,
+      blockedTopics: [],
+      allowedTopics: [],
+      // Built-in rules (see ./injection-detector). They match against normalised
+      // text (NFKC, zero-width/control characters removed, homoglyph and
+      // leetspeak folding). options.injectionPatterns adds extra patterns.
+      injectionPatterns: DEFAULT_RULES.map((rule) => rule.pattern)
+    };
+    var PreRetrievalGuard = class extends EventEmitter {
+      /**
+       * @param {object} [options] - Override default configuration
+       * @param {number} [options.maxQueryLength=10000] - Maximum allowed query length
+       * @param {boolean} [options.enableInjectionDetection=true] - Whether to check for prompt injection
+       * @param {boolean} [options.enableTopicFiltering=false] - Whether to enforce topic constraints
+       * @param {string[]} [options.blockedTopics=[]] - Topics to reject
+       * @param {string[]} [options.allowedTopics=[]] - If non-empty, only these topics are permitted
+       * @param {RegExp[]} [options.injectionPatterns] - Additional injection patterns (merged with defaults)
+       */
+      constructor(options = {}) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...options };
+        this._customPatterns = options.injectionPatterns ? [...options.injectionPatterns] : [];
+        if (options.injectionPatterns) {
+          this.config.injectionPatterns = [
+            ...DEFAULT_CONFIG.injectionPatterns,
+            ...options.injectionPatterns
+          ];
+        }
+      }
+      /**
+       * Check a query for safety issues, injection attempts, and topic violations.
+       *
+       * @param {string} query - The user query to validate
+       * @returns {{
+       *   safe: boolean,
+       *   issues: string[],
+       *   sanitizedQuery: string,
+       *   injection: { detected: boolean, matches: Array<{id: string, pattern: string, match: string}> }
+       * }}
+       * `sanitizedQuery` is the query truncated to maxQueryLength; it is never
+       * rewritten. Injection findings are reported in `issues` and `injection`
+       * and make `safe` false; blocking is up to the caller (GuardrailsPipeline
+       * blocks in strict mode).
+       * @fires PreRetrievalGuard#checked
+       */
+      check(query) {
+        const issues = [];
+        if (query == null || typeof query !== "string" || query.trim().length === 0) {
+          issues.push("Query must be a non-empty string");
+          const result2 = {
+            safe: false,
+            issues,
+            sanitizedQuery: "",
+            injection: { detected: false, matches: [] }
+          };
+          this.emit("checked", result2);
+          return result2;
+        }
+        const validation = validateInput(query, {
+          maxLength: this.config.maxQueryLength
+        });
+        if (!validation.valid) {
+          for (const reason of validation.reasons) {
+            issues.push(reason);
+          }
+        }
+        const sanitizedQuery = validation.sanitized;
+        let injection = { detected: false, matches: [] };
+        if (this.config.enableInjectionDetection) {
+          const found = detectInjection(sanitizedQuery, {
+            patterns: this._customPatterns
+          });
+          injection = { detected: found.detected, matches: found.matches };
+          for (const m of found.matches) {
+            issues.push(
+              `Potential prompt injection detected: ${m.id} (${JSON.stringify(m.match)})`
+            );
+          }
+        }
+        if (this.config.enableTopicFiltering) {
+          const tokens = tokenize(sanitizedQuery);
+          if (this.config.blockedTopics.length > 0) {
+            for (const topic of this.config.blockedTopics) {
+              const topicLower = topic.toLowerCase();
+              if (tokens.includes(topicLower)) {
+                issues.push(`Query contains blocked topic: ${topic}`);
+              }
+            }
+          }
+          if (this.config.allowedTopics.length > 0) {
+            const allowedLower = this.config.allowedTopics.map(
+              (t) => t.toLowerCase()
+            );
+            const hasAllowedTopic = tokens.some(
+              (token) => allowedLower.includes(token)
+            );
+            if (!hasAllowedTopic) {
+              issues.push("Query does not match any allowed topics");
+            }
+          }
+        }
+        const result = {
+          safe: issues.length === 0,
+          issues,
+          sanitizedQuery,
+          injection
+        };
+        this.emit("checked", result);
+        return result;
+      }
+    };
+    module2.exports = { PreRetrievalGuard, DEFAULT_CONFIG };
+  }
+});
+
+// src/guardrails/retrieval-guard.js
+var require_retrieval_guard = __commonJS({
+  "src/guardrails/retrieval-guard.js"(exports2, module2) {
+    "use strict";
+    var { EventEmitter } = require("events");
+    var { detectInjection } = require_injection_detector();
+    var DEFAULT_CONFIG = {
+      minRelevanceScore: 0,
+      maxAgeDays: 0,
+      // 0 = disabled
+      enforceACL: false,
+      // Opt-in scan of retrieved document text for prompt injection (indirect
+      // injection). 'remove' drops flagged documents, 'flag' keeps them and
+      // marks them with `injection` details.
+      detectInjection: false,
+      injectionAction: "remove",
+      injectionPatterns: []
+    };
+    var RetrievalGuard = class extends EventEmitter {
+      /**
+       * @param {object} [options] - Override default configuration
+       * @param {number} [options.minRelevanceScore=0] - Minimum relevance score threshold
+       * @param {number} [options.maxAgeDays=0] - Maximum document age in days (0 = disabled)
+       * @param {boolean} [options.enforceACL=false] - Whether to enforce access control
+       * @param {boolean} [options.detectInjection=false] - Scan document text for prompt injection
+       * @param {'remove'|'flag'} [options.injectionAction='remove'] - Remove flagged documents or keep and mark them
+       * @param {RegExp[]} [options.injectionPatterns=[]] - Extra injection patterns for the scan
+       */
+      constructor(options = {}) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...options };
+      }
+      /**
+       * Filter retrieval results based on configured guards.
+       *
+       * @param {Array<object>} results - Array of retrieval results, each with .score and optional .metadata
+       * @param {object} [context={}] - Request context
+       * @param {string[]} [context.userPermissions] - User's permission roles for ACL filtering
+       * @returns {{
+       *   results: Array<object>,
+       *   removed: Array<object>,
+       *   metadata: { reasons: Object<string, number> }
+       * }}
+       * @fires RetrievalGuard#filtered
+       */
+      filter(results, context = {}) {
+        if (!Array.isArray(results)) {
+          const output2 = { results: [], removed: [], metadata: { reasons: {} } };
+          this.emit("filtered", output2);
+          return output2;
+        }
+        const kept = [];
+        const removed = [];
+        const reasons = {};
+        const now = Date.now();
+        const maxAgeMs = this.config.maxAgeDays > 0 ? this.config.maxAgeDays * 24 * 60 * 60 * 1e3 : 0;
+        for (const result of results) {
+          let dominated = false;
+          const doc = result.metadata || result.doc || result;
+          if (this.config.minRelevanceScore > 0) {
+            const score = result.score != null ? result.score : 0;
+            if (score < this.config.minRelevanceScore) {
+              dominated = true;
+              reasons.relevance = (reasons.relevance || 0) + 1;
+            }
+          }
+          if (!dominated && maxAgeMs > 0) {
+            const timestamp = doc.updatedAt || doc.timestamp;
+            if (timestamp) {
+              const docTime = new Date(timestamp).getTime();
+              if (!isNaN(docTime) && now - docTime > maxAgeMs) {
+                dominated = true;
+                reasons.freshness = (reasons.freshness || 0) + 1;
+              }
+            }
+          }
+          if (!dominated && this.config.enforceACL) {
+            const userPermissions = context.userPermissions || [];
+            const restriction = result.requiredRole ?? result.acl ?? doc.requiredRole ?? doc.acl;
+            const requiredRoles = restriction ? [].concat(restriction) : null;
+            if (requiredRoles && requiredRoles.length > 0) {
+              const hasAccess = requiredRoles.some(
+                (role) => userPermissions.includes(role)
+              );
+              if (!hasAccess) {
+                dominated = true;
+                reasons.acl = (reasons.acl || 0) + 1;
+              }
+            }
+          }
+          if (!dominated && this.config.detectInjection) {
+            const text = documentText(result);
+            const found = detectInjection(text, {
+              patterns: this.config.injectionPatterns
+            });
+            if (found.detected) {
+              reasons.injection = (reasons.injection || 0) + 1;
+              if (this.config.injectionAction === "flag") {
+                kept.push({
+                  ...result,
+                  injection: { detected: true, matches: found.matches }
+                });
+                continue;
+              }
+              dominated = true;
+            }
+          }
+          if (dominated) {
+            removed.push(result);
+          } else {
+            kept.push(result);
+          }
+        }
+        const output = {
+          results: kept,
+          removed,
+          metadata: { reasons }
+        };
+        this.emit("filtered", { original: results, filtered: kept, removed });
+        return output;
+      }
+    };
+    function documentText(result) {
+      if (typeof result === "string") return result;
+      if (!result || typeof result !== "object") return "";
+      const doc = result.doc && typeof result.doc === "object" ? result.doc : {};
+      return String(
+        result.content || result.text || result.pageContent || doc.content || doc.text || ""
+      );
+    }
+    module2.exports = { RetrievalGuard, DEFAULT_CONFIG };
+  }
+});
+
+// scoped:@devilsdev/rag-core|citation/citation-tracker.js
+var require_citation_tracker = __commonJS({
+  "scoped:@devilsdev/rag-core|citation/citation-tracker.js"(exports2, module2) {
+    module2.exports = require("@devilsdev/rag-core")[Symbol.for("@devilsdev/rag-core/internal")]("citation/citation-tracker.js");
+  }
+});
+
+// src/guardrails/post-generation-guard.js
+var require_post_generation_guard = __commonJS({
+  "src/guardrails/post-generation-guard.js"(exports2, module2) {
+    "use strict";
+    var { EventEmitter } = require("events");
+    var DEFAULT_CONFIG = {
+      enablePIIDetection: true,
+      enableGroundednessCheck: true,
+      groundednessThreshold: 0.3,
+      maxResponseLength: 5e4,
+      minResponseLength: 0,
+      piiPatterns: {
+        email: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
+        phone: /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g,
+        ssn: /\b\d{3}-\d{2}-\d{4}\b/g,
+        creditCard: /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/g
+      }
+    };
+    var PostGenerationGuard = class extends EventEmitter {
+      /**
+       * @param {object} [options] - Override default configuration
+       * @param {boolean} [options.enablePIIDetection=true] - Whether to detect PII in output
+       * @param {boolean} [options.enableGroundednessCheck=true] - Whether to check groundedness
+       * @param {number} [options.groundednessThreshold=0.3] - Minimum groundedness score
+       * @param {number} [options.maxResponseLength=50000] - Maximum allowed response length
+       * @param {number} [options.minResponseLength=0] - Minimum response length
+       * @param {object} [options.piiPatterns] - Custom PII regex patterns (merged with defaults)
+       */
+      constructor(options = {}) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...options };
+        if (options.piiPatterns) {
+          this.config.piiPatterns = {
+            ...DEFAULT_CONFIG.piiPatterns,
+            ...options.piiPatterns
+          };
+        }
+      }
+      /**
+       * Check generated output for safety issues, PII, and groundedness.
+       *
+       * @param {string} output - The LLM-generated output text
+       * @param {Array<object>} [retrievedDocs=[]] - Source documents for groundedness checking
+       * @returns {{
+       *   safe: boolean,
+       *   issues: string[],
+       *   sanitizedOutput: string,
+       *   groundednessScore?: number
+       * }}
+       * @fires PostGenerationGuard#checked
+       */
+      check(output, retrievedDocs = []) {
+        const issues = [];
+        if (output == null || typeof output !== "string") {
+          issues.push("Output must be a string");
+          const result2 = { safe: false, issues, sanitizedOutput: "" };
+          this.emit("checked", result2);
+          return result2;
+        }
+        if (this.config.maxResponseLength > 0 && output.length > this.config.maxResponseLength) {
+          issues.push(
+            `Output exceeds maximum length of ${this.config.maxResponseLength} characters`
+          );
+        }
+        if (this.config.minResponseLength > 0 && output.length < this.config.minResponseLength) {
+          issues.push(
+            `Output is shorter than minimum length of ${this.config.minResponseLength} characters`
+          );
+        }
+        const piiMatches = {};
+        if (this.config.enablePIIDetection) {
+          for (const [name, pattern] of Object.entries(this.config.piiPatterns)) {
+            pattern.lastIndex = 0;
+            const matches = output.match(pattern);
+            if (matches && matches.length > 0) {
+              piiMatches[name] = matches;
+              issues.push(
+                `PII detected (${name}): ${matches.length} occurrence(s)`
+              );
+            }
+          }
+        }
+        let groundednessScore;
+        if (this.config.enableGroundednessCheck && Array.isArray(retrievedDocs) && retrievedDocs.length > 0) {
+          try {
+            const { CitationTracker } = require_citation_tracker();
+            const tracker = new CitationTracker();
+            const tracking = tracker.track(output, retrievedDocs);
+            groundednessScore = tracking.groundednessScore;
+            if (groundednessScore < this.config.groundednessThreshold) {
+              issues.push(
+                `Groundedness score (${groundednessScore.toFixed(2)}) is below threshold (${this.config.groundednessThreshold})`
+              );
+            }
+          } catch (err) {
+            issues.push(`Groundedness check failed: ${err.message}`);
+          }
+        }
+        let sanitizedOutput = output;
+        if (Object.keys(piiMatches).length > 0) {
+          for (const [, matches] of Object.entries(piiMatches)) {
+            for (const match of matches) {
+              sanitizedOutput = sanitizedOutput.split(match).join("[REDACTED]");
+            }
+          }
+        }
+        if (this.config.maxResponseLength > 0 && sanitizedOutput.length > this.config.maxResponseLength) {
+          sanitizedOutput = sanitizedOutput.substring(
+            0,
+            this.config.maxResponseLength
+          );
+        }
+        const result = {
+          safe: issues.length === 0,
+          issues,
+          sanitizedOutput
+        };
+        if (groundednessScore !== void 0) {
+          result.groundednessScore = groundednessScore;
+        }
+        this.emit("checked", result);
+        return result;
+      }
+      /**
+       * Replace PII matches in arbitrary text with [REDACTED], using the same
+       * patterns as check(). Used to scrub text derived from the answer, such as
+       * citation sentences.
+       *
+       * @param {string} text
+       * @returns {string}
+       */
+      redact(text) {
+        if (typeof text !== "string" || !this.config.enablePIIDetection) {
+          return text;
+        }
+        let redacted = text;
+        for (const pattern of Object.values(this.config.piiPatterns)) {
+          redacted = redacted.replace(pattern, "[REDACTED]");
+        }
+        return redacted;
+      }
+    };
+    module2.exports = { PostGenerationGuard, DEFAULT_CONFIG };
+  }
+});
+
+// src/guardrails/guardrails-pipeline.js
+var require_guardrails_pipeline = __commonJS({
+  "src/guardrails/guardrails-pipeline.js"(exports2, module2) {
+    "use strict";
+    var { EventEmitter } = require("events");
+    var { PreRetrievalGuard } = require_pre_retrieval_guard();
+    var { RetrievalGuard } = require_retrieval_guard();
+    var { PostGenerationGuard } = require_post_generation_guard();
+    var DEFAULT_CONFIG = {
+      preRetrieval: {},
+      // PreRetrievalGuard options, or false to disable
+      retrieval: {},
+      // RetrievalGuard options, or false to disable
+      postGeneration: {},
+      // PostGenerationGuard options, or false to disable
+      strict: false
+      // If true, block on any guard failure; if false, warn and continue
+    };
+    function summarizeFilter(filterOutput) {
+      return {
+        ...filterOutput,
+        removed: filterOutput.removed.map((doc) => ({ id: doc.id }))
+      };
+    }
+    var GuardrailsPipeline = class extends EventEmitter {
+      /**
+       * @param {object} pipeline - The underlying RAG pipeline (must have a .run() method)
+       * @param {object} [options] - Override default configuration
+       * @param {object|false} [options.preRetrieval={}] - PreRetrievalGuard options, or false to disable
+       * @param {object|false} [options.retrieval={}] - RetrievalGuard options, or false to disable
+       * @param {object|false} [options.postGeneration={}] - PostGenerationGuard options, or false to disable
+       * @param {boolean} [options.strict=false] - Whether to block on any guard failure
+       */
+      constructor(pipeline, options = {}) {
+        super();
+        if (!pipeline || typeof pipeline.run !== "function") {
+          throw new Error(
+            "GuardrailsPipeline requires a pipeline with a .run() method"
+          );
+        }
+        this.pipeline = pipeline;
+        this.config = { ...DEFAULT_CONFIG, ...options };
+        this.preGuard = this.config.preRetrieval !== false ? new PreRetrievalGuard(this.config.preRetrieval || {}) : null;
+        this.retrievalGuard = this.config.retrieval !== false ? new RetrievalGuard(this.config.retrieval || {}) : null;
+        this.postGuard = this.config.postGeneration !== false ? new PostGenerationGuard(this.config.postGeneration || {}) : null;
+      }
+      /**
+       * Run the full guarded pipeline.
+       *
+       * @param {object} input - Pipeline input
+       * @param {string} input.query - The user query
+       * @param {Float32Array} [input.queryVector] - Optional precomputed query vector
+       * @param {object} [input.options] - Additional pipeline options
+       * @param {object} [input.context] - Request context (e.g. userPermissions for ACL)
+       * @returns {Promise<object>} Pipeline result with guardrails metadata attached
+       */
+      async run(input) {
+        const guardrails = {
+          preRetrieval: null,
+          retrieval: null,
+          postGeneration: null
+        };
+        let query = input.query;
+        if (this.preGuard) {
+          guardrails.preRetrieval = this.preGuard.check(query);
+          this.emit("preRetrieval", guardrails.preRetrieval);
+          if (!guardrails.preRetrieval.safe && this.config.strict) {
+            return {
+              success: false,
+              error: "Pre-retrieval guard blocked query",
+              guardrails
+            };
+          }
+          query = guardrails.preRetrieval.sanitizedQuery;
+        }
+        let preGenerationFilter = null;
+        const filterOptions = this.retrievalGuard ? {
+          filterResults: (docs) => {
+            preGenerationFilter = this.retrievalGuard.filter(
+              docs,
+              input.context
+            );
+            return preGenerationFilter.results;
+          }
+        } : {};
+        const result = await this.pipeline.run({
+          ...input,
+          query,
+          options: { ...input.options, citations: true, ...filterOptions }
+        });
+        if (this.retrievalGuard && preGenerationFilter) {
+          guardrails.retrieval = summarizeFilter(preGenerationFilter);
+          this.emit("retrieval", guardrails.retrieval);
+        } else if (this.retrievalGuard && result.results) {
+          guardrails.retrieval = summarizeFilter(
+            this.retrievalGuard.filter(result.results, input.context)
+          );
+          this.emit("retrieval", guardrails.retrieval);
+          result.results = guardrails.retrieval.results;
+          if (guardrails.retrieval.metadata.reasons.acl) {
+            return {
+              success: false,
+              error: "Retrieval guard removed access-controlled documents after generation; answer withheld",
+              guardrails
+            };
+          }
+        }
+        if (this.postGuard && result.answer) {
+          guardrails.postGeneration = this.postGuard.check(
+            result.answer,
+            result.results
+          );
+          this.emit("postGeneration", guardrails.postGeneration);
+          if (!guardrails.postGeneration.safe && this.config.strict) {
+            return {
+              success: false,
+              error: "Post-generation guard flagged output",
+              guardrails
+            };
+          }
+          result.answer = guardrails.postGeneration.sanitizedOutput;
+          this._redactDeep(result.citations);
+          this._redactDeep(result.evaluation);
+        }
+        result.guardrails = guardrails;
+        return result;
+      }
+      /**
+       * Citations and evaluation details copy sentences from the raw answer, so
+       * scrub every string in them with the same PII patterns as the answer.
+       *
+       * @param {*} value - Object, array or string to redact in place
+       * @returns {*} The redacted value
+       * @private
+       */
+      _redactDeep(value) {
+        if (typeof value === "string") return this.postGuard.redact(value);
+        if (value && typeof value === "object") {
+          for (const key of Object.keys(value)) {
+            value[key] = this._redactDeep(value[key]);
+          }
+        }
+        return value;
+      }
+    };
+    module2.exports = { GuardrailsPipeline, DEFAULT_CONFIG };
+  }
+});
+
+// src/packages/guardrails.js
+var require_guardrails = __commonJS({
+  "src/packages/guardrails.js"(exports2, module2) {
+    "use strict";
+    var { PreRetrievalGuard } = require_pre_retrieval_guard();
+    var { detectInjection } = require_injection_detector();
+    var { RetrievalGuard } = require_retrieval_guard();
+    var { PostGenerationGuard } = require_post_generation_guard();
+    var { GuardrailsPipeline } = require_guardrails_pipeline();
+    module2.exports = {
+      PreRetrievalGuard,
+      detectInjection,
+      RetrievalGuard,
+      PostGenerationGuard,
+      GuardrailsPipeline
+    };
+  }
+});
+
+// src/package-entry.js
+var mod = require_guardrails();
+var modules = {
+  "guardrails/guardrails-pipeline.js": () => require_guardrails_pipeline(),
+  "guardrails/injection-detector.js": () => require_injection_detector(),
+  "guardrails/post-generation-guard.js": () => require_post_generation_guard(),
+  "guardrails/pre-retrieval-guard.js": () => require_pre_retrieval_guard(),
+  "guardrails/retrieval-guard.js": () => require_retrieval_guard(),
+  "packages/guardrails.js": () => require_guardrails(),
+  "security/validator.js": () => require_validator()
+};
+Object.defineProperty(mod, Symbol.for("@devilsdev/rag-guardrails/internal"), {
+  value: (file) => {
+    if (!modules[file]) throw new Error("@devilsdev/rag-guardrails has no module " + file);
+    return modules[file]();
+  }
+});
+module.exports = mod;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { PreRetrievalGuard, detectInjection, RetrievalGuard, PostGenerationGuard, GuardrailsPipeline } from "@devilsdev/rag-core/all-types";

package/dist/index.mjs

@@ -0,0 +1,5 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const mod = require('./index.cjs');
+export const { PreRetrievalGuard, detectInjection, RetrievalGuard, PostGenerationGuard, GuardrailsPipeline } = mod;
+export default mod;

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@devilsdev/rag-guardrails",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.2.0",
+  "description": "Guardrails for RAG: prompt-injection detection and pre-retrieval, retrieval and post-generation guards.",
+  "keywords": [
+    "rag",
+    "guardrails",
+    "prompt-injection",
+    "llm-security"
+  ],
+  "license": "MIT",
+  "author": "Ali Kahwaji",
+  "homepage": "https://devilsdev.github.io/rag-pipeline-utils/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DevilsDev/rag-pipeline-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DevilsDev/rag-pipeline-utils/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@devilsdev/rag-core": "3.2.0"
+  }
+}