redact-ai-stream 1.1.0 → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Godfrey Lebo
+
+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

@@ -5,11 +5,16 @@
 ![Downloads](https://img.shields.io/npm/dm/redact-ai-stream)
 ![TypeScript](https://img.shields.io/badge/types-included-blue)
 
+![Redact AI Stream Hero](assets/redact_ai_stream_hero_1766409977618.png)
+
 **Bi-directional PII Redaction for AI Streams**
 
 `redact-ai-stream` is a lightweight, specialized Node.js library designed to secure your AI applications. It acts as a middleware layer, automatically redacting Personally Identifiable Information (PII) from data streams *before* they exit your secure boundary (e.g., to OpenAI, Anthropic), and transparently restoring that data in the incoming response stream.
 
+![How It Works](assets/redact_ai_stream_how_it_works_1766409909844.png)
+
 ## Why use this?
+
 When building RAG requests or chat interfaces, you often need to send user context to an LLM. However, sending raw email addresses, phone numbers, or credit card details violates privacy compliance (GDPR, CCPA) and security best practices. `redact-ai-stream` solves this by tokenizing sensitive data on the fly.
 
 ## Features

package/dist/index.d.ts

@@ -2,13 +2,21 @@ import { Transform } from 'stream';
 declare class RedactionSession {
     tokenMap: Map<string, string>;
     constructor();
+    private redactBlock;
     /**
-     * returns a Transform stream that accepts strings/buffers,
-     * identifies PII, replaces it with tokens, and stores the mapping.
+     * Returns a Transform stream that accepts strings/buffers, identifies PII,
+     * replaces it with reversible tokens, and stores the original mapping.
+     *
+     * Chunk-boundary safety: a hold-back buffer of up to MAX_PATTERN_LENGTH
+     * characters is retained between chunks so that a PII pattern split across
+     * chunk boundaries (e.g. ["te", "st@example.com"]) is still detected.
      */
     redact(): Transform;
     /**
-     * returns a Transform stream that restores original PII from tokens.
+     * Returns a Transform stream that restores original PII from tokens.
+     *
+     * Tokens are fixed-shape (`<TYPE_<uuidv4>>`) so cross-chunk safety only
+     * requires holding back the last ~64 characters between chunks.
      */
     restore(): Transform;
 }

package/dist/index.js

@@ -6,13 +6,53 @@ const PATTERNS = {
     PHONE: /\b\+?(\d{1,4}?[-. ]?)?(\(?\d{3}\)?[-. ]?)?\d{3}[-. ]?\d{4}\b/g,
     CREDIT_CARD: /\b(?:\d[ -]*?){13,19}\b/g
 };
+// Maximum length any in-flight PII pattern could plausibly reach. Used as the
+// hold-back window when chunks arrive mid-pattern so we never finalise a chunk
+// while a PII match is still being assembled.
+const MAX_PATTERN_LENGTH = 128;
 class RedactionSession {
     constructor() {
         this.tokenMap = new Map();
     }
+    redactBlock(text) {
+        // Park already-emitted tokens behind NUL sentinels while we run the
+        // remaining PII patterns, then splice them back. NUL cannot appear in
+        // normal text and breaks the \b / \d / \w boundaries our subsequent
+        // phone / credit-card regexes rely on, so parked tokens are inert.
+        const PARKED = [];
+        const park = (token) => {
+            const i = PARKED.push(token) - 1;
+            return `\x00${i}\x00`;
+        };
+        let out = text;
+        out = out.replace(PATTERNS.EMAIL, (match) => {
+            const token = `<EMAIL_${(0, uuid_1.v4)()}>`;
+            this.tokenMap.set(token, match);
+            return park(token);
+        });
+        out = out.replace(PATTERNS.CREDIT_CARD, (match) => {
+            if (match.replace(/\D/g, '').length < 13)
+                return match;
+            const token = `<CC_${(0, uuid_1.v4)()}>`;
+            this.tokenMap.set(token, match);
+            return park(token);
+        });
+        out = out.replace(PATTERNS.PHONE, (match) => {
+            if (match.replace(/\D/g, '').length < 10)
+                return match;
+            const token = `<PHONE_${(0, uuid_1.v4)()}>`;
+            this.tokenMap.set(token, match);
+            return park(token);
+        });
+        return out.replace(/\x00(\d+)\x00/g, (_, idx) => PARKED[Number(idx)]);
+    }
     /**
-     * returns a Transform stream that accepts strings/buffers,
-     * identifies PII, replaces it with tokens, and stores the mapping.
+     * Returns a Transform stream that accepts strings/buffers, identifies PII,
+     * replaces it with reversible tokens, and stores the original mapping.
+     *
+     * Chunk-boundary safety: a hold-back buffer of up to MAX_PATTERN_LENGTH
+     * characters is retained between chunks so that a PII pattern split across
+     * chunk boundaries (e.g. ["te", "st@example.com"]) is still detected.
      */
     redact() {
         const session = this;
@@ -20,58 +60,67 @@ class RedactionSession {
         return new stream_1.Transform({
             objectMode: true,
             transform(chunk, encoding, callback) {
-                let text = buffer + chunk.toString();
-                // Redact Email
-                text = text.replace(PATTERNS.EMAIL, (match) => {
-                    const token = `<EMAIL_${(0, uuid_1.v4)()}>`;
-                    session.tokenMap.set(token, match);
-                    return token;
-                });
-                // Redact Credit Card
-                text = text.replace(PATTERNS.CREDIT_CARD, (match) => {
-                    if (match.replace(/\D/g, '').length < 13)
-                        return match;
-                    const token = `<CC_${(0, uuid_1.v4)()}>`;
-                    session.tokenMap.set(token, match);
-                    return token;
-                });
-                // Redact Phone
-                text = text.replace(PATTERNS.PHONE, (match) => {
-                    if (match.replace(/\D/g, '').length < 10)
-                        return match;
-                    const token = `<PHONE_${(0, uuid_1.v4)()}>`;
-                    session.tokenMap.set(token, match);
-                    return token;
-                });
-                this.push(text);
-                buffer = '';
+                const text = buffer + chunk.toString();
+                // Decide how much of `text` is safe to emit now: only the prefix
+                // that cannot be extended by the next chunk into a PII match.
+                // Hold the tail (up to MAX_PATTERN_LENGTH chars, snapped to the
+                // last whitespace boundary when possible) in the buffer.
+                let cut = text.length - MAX_PATTERN_LENGTH;
+                if (cut < 0)
+                    cut = 0;
+                if (cut > 0) {
+                    const ws = text.lastIndexOf(' ', cut);
+                    if (ws > 0)
+                        cut = ws + 1;
+                }
+                const head = text.slice(0, cut);
+                const tail = text.slice(cut);
+                if (head.length > 0) {
+                    this.push(session.redactBlock(head));
+                }
+                buffer = tail;
                 callback();
             },
             flush(callback) {
-                if (buffer) {
-                    this.push(buffer);
+                if (buffer.length > 0) {
+                    this.push(session.redactBlock(buffer));
+                    buffer = '';
                 }
                 callback();
             }
         });
     }
     /**
-     * returns a Transform stream that restores original PII from tokens.
+     * Returns a Transform stream that restores original PII from tokens.
+     *
+     * Tokens are fixed-shape (`<TYPE_<uuidv4>>`) so cross-chunk safety only
+     * requires holding back the last ~64 characters between chunks.
      */
     restore() {
         const session = this;
+        let buffer = '';
+        const TOKEN_MAX = 64;
+        const tokenPattern = /<(EMAIL|CC|PHONE)_[0-9a-fA-F-]{36}>/g;
+        const sub = (s) => s.replace(tokenPattern, (token) => session.tokenMap.get(token) ?? token);
         return new stream_1.Transform({
             objectMode: true,
             transform(chunk, encoding, callback) {
-                let text = chunk.toString();
-                const tokenPattern = /<(EMAIL|CC|PHONE)_[0-9a-fA-F-]{36}>/g;
-                text = text.replace(tokenPattern, (token) => {
-                    if (session.tokenMap.has(token)) {
-                        return session.tokenMap.get(token);
-                    }
-                    return token;
-                });
-                this.push(text);
+                const text = buffer + chunk.toString();
+                let cut = text.length - TOKEN_MAX;
+                if (cut < 0)
+                    cut = 0;
+                const head = text.slice(0, cut);
+                const tail = text.slice(cut);
+                if (head.length > 0)
+                    this.push(sub(head));
+                buffer = tail;
+                callback();
+            },
+            flush(callback) {
+                if (buffer.length > 0) {
+                    this.push(sub(buffer));
+                    buffer = '';
+                }
                 callback();
             }
         });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "redact-ai-stream",
-    "version": "1.1.0",
+    "version": "1.3.0",
     "description": "Bi-directional PII redaction stream for AI applications",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -27,6 +27,9 @@
         "type": "git",
         "url": "git+https://github.com/emorilebo/redact-ai-stream.git"
     },
+    "engines": {
+        "node": ">=18.0.0"
+    },
     "dependencies": {
         "uuid": "^9.0.0"
     },