redact-ai-stream 1.0.0 → 1.1.0

package/README.md

@@ -1,16 +1,24 @@
 # redact-ai-stream
 
+![NPM Version](https://img.shields.io/npm/v/redact-ai-stream)
+![License](https://img.shields.io/npm/l/redact-ai-stream)
+![Downloads](https://img.shields.io/npm/dm/redact-ai-stream)
+![TypeScript](https://img.shields.io/badge/types-included-blue)
+
 **Bi-directional PII Redaction for AI Streams**
 
-`redact-ai-stream` is a lightweight Node.js library designed to secure your AI applications by automatically redacting Personally Identifiable Information (PII) from data streams *before* they reach public APIs (like OpenAI, Anthropic, etc.) and restoring the original data in the response stream.
+`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.
+
+## 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
 
-*   **Stream-based Redaction**: Works directly with Node.js streams.
-*   **Bi-directional**: Redact on the way out, restore on the way back.
-*   **Session-based**: Keeps track of tokens per session to ensure correct restoration.
-*   **Secure**: Original PII never leaves your server (it is stored in a temporary map).
-*   **Simple API**: Just `.pipe()` it.
+*   **Stream-based Redaction**: Integrates natively with Node.js `Transform` streams.
+*   **Bi-directional**: Redacts outgoing data, restores incoming data.
+*   **Session-based Security**: Tokens are unique per session (`<EMAIL_UUID>`).
+*   **Zero-Persistence**: Original PII is held in memory only for the duration of the stream; never stored on disk.
+*   **TypeScript Support**: Written in TypeScript with full type definitions included.
 
 ## Installation
 
@@ -20,42 +28,54 @@ npm install redact-ai-stream
 
 ## Usage
 
-```javascript
-const RedactionSession = require('redact-ai-stream');
-const { Readable } = require('stream');
+### TypeScript / ES Modules
+
+```typescript
+import RedactionSession from 'redact-ai-stream';
+import { Readable } from 'stream';
 
 // 1. Create a session
 const session = new RedactionSession();
 
-// 2. Simulate user input stream (e.g., from a request)
+// 2. Mock input stream (e.g., from an API request)
 const userInput = Readable.from(["My email is alice@example.com."]);
 
-// 3. Redact the stream
+// 3. Pipe through redaction
 const redactedStream = userInput.pipe(session.redact());
 
 redactedStream.on('data', (chunk) => {
-    console.log('Sending to AI:', chunk.toString());
-    // Output: "Sending to AI: My email is <EMAIL_d41d...>"
+    console.log('To LLM:', chunk.toString());
+    // Output: "To LLM: My email is <EMAIL_1234-5678...>"
 });
 
-// 4. Simulate AI response (which might use the token)
-const aiResponse = Readable.from(["Sure, I will email <EMAIL_d41d...>."]);
+// ... Send to AI ...
 
-// 5. Restore the stream for the user
+// 4. Restore AI response
+const aiResponse = Readable.from(["Sending confirmation to <EMAIL_1234-5678...>."]);
 const finalStream = aiResponse.pipe(session.restore());
 
 finalStream.on('data', (chunk) => {
-    console.log('Sending to User:', chunk.toString());
-    // Output: "Sending to User: Sure, I will email alice@example.com."
+    console.log('To User:', chunk.toString());
+    // Output: "To User: Sending confirmation to alice@example.com."
 });
 ```
 
+### CommonJS
+
+```javascript
+const RedactionSession = require('redact-ai-stream');
+// Usage is identical to above
+```
+
 ## Supported Redactions
 
-*   **Emails**: `user@example.com` -> `<EMAIL_UUID>`
-*   **Credit Cards**: `1234 5678 1234 5678` -> `<CC_UUID>`
-*   **Phone Numbers**: `123-456-7890` -> `<PHONE_UUID>`
+| Type | Pattern Example | Token Format |
+| :--- | :--- | :--- |
+| **Email** | `alice@example.com` | `<EMAIL_UUID>` |
+| **Credit Card** | `4532 1234 5678 9012` | `<CC_UUID>` |
+| **Phone** | `+1-555-0123` | `<PHONE_UUID>` |
 
 ## License
 
-MIT
+MIT © Godfrey Lebo
+

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { Transform } from 'stream';
+declare class RedactionSession {
+    tokenMap: Map<string, string>;
+    constructor();
+    /**
+     * returns a Transform stream that accepts strings/buffers,
+     * identifies PII, replaces it with tokens, and stores the mapping.
+     */
+    redact(): Transform;
+    /**
+     * returns a Transform stream that restores original PII from tokens.
+     */
+    restore(): Transform;
+}
+export = RedactionSession;

package/{index.js → dist/index.js}

@@ -1,67 +1,50 @@
-const { Transform } = require('stream');
-const { v4: uuidv4 } = require('uuid');
-
+"use strict";
+const stream_1 = require("stream");
+const uuid_1 = require("uuid");
 const PATTERNS = {
     EMAIL: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
-    // Basic phone pattern: supports +1-555-555-5555, (555) 555-5555, 555 555 5555
     PHONE: /\b\+?(\d{1,4}?[-. ]?)?(\(?\d{3}\)?[-. ]?)?\d{3}[-. ]?\d{4}\b/g,
-    // Basic credit card: 12 digit sequences (Amex) to 16/19 digits
     CREDIT_CARD: /\b(?:\d[ -]*?){13,19}\b/g
 };
-
 class RedactionSession {
     constructor() {
         this.tokenMap = new Map();
     }
-
     /**
      * returns a Transform stream that accepts strings/buffers,
      * identifies PII, replaces it with tokens, and stores the mapping.
      */
     redact() {
         const session = this;
-        let buffer = ''; // Buffer for handling split PII across chunks
-
-        return new Transform({
+        let buffer = '';
+        return new stream_1.Transform({
             objectMode: true,
             transform(chunk, encoding, callback) {
                 let text = buffer + chunk.toString();
-
-                // Strategy: to handle split chunks, we technically should hold back 
-                // the end of the string if it looks like it *could* be the start of a PII.
-                // For this MVP version, we will process the whole chunk. 
-                // A production version would need sophisticated buffering.
-
                 // Redact Email
                 text = text.replace(PATTERNS.EMAIL, (match) => {
-                    const token = `<EMAIL_${uuidv4()}>`;
+                    const token = `<EMAIL_${(0, uuid_1.v4)()}>`;
                     session.tokenMap.set(token, match);
                     return token;
                 });
-
                 // Redact Credit Card
                 text = text.replace(PATTERNS.CREDIT_CARD, (match) => {
-                    // Simple luhn check could be added here for validity, 
-                    // but for security "better safe than sorry" is often okay.
-                    // To avoid false positives on simple numbers, let's strictly require length.
-                    if (match.replace(/\D/g, '').length < 13) return match;
-
-                    const token = `<CC_${uuidv4()}>`;
+                    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_${uuidv4()}>`;
+                    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 = ''; // Reset buffer (if we were using it for partials)
+                buffer = '';
                 callback();
             },
             flush(callback) {
@@ -72,31 +55,26 @@ class RedactionSession {
             }
         });
     }
-
     /**
      * returns a Transform stream that restores original PII from tokens.
      */
     restore() {
         const session = this;
-        return new Transform({
+        return new stream_1.Transform({
             objectMode: true,
             transform(chunk, encoding, callback) {
                 let text = chunk.toString();
-                // Token pattern: <TYPE_UUID>
                 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);
                 callback();
             }
         });
     }
 }
-
 module.exports = RedactionSession;

package/package.json

@@ -1,10 +1,16 @@
 {
     "name": "redact-ai-stream",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "Bi-directional PII redaction stream for AI applications",
-    "main": "index.js",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
     "scripts": {
-        "test": "node --test"
+        "build": "rimraf dist && tsc",
+        "prepublishOnly": "npm run build",
+        "test": "npm run build && node --test"
     },
     "keywords": [
         "ai",
@@ -24,5 +30,10 @@
     "dependencies": {
         "uuid": "^9.0.0"
     },
-    "devDependencies": {}
-}
+    "devDependencies": {
+        "@types/node": "^25.0.3",
+        "@types/uuid": "^10.0.0",
+        "rimraf": "^6.1.2",
+        "typescript": "^5.9.3"
+    }
+}

package/test/index.test.js

@@ -1,105 +0,0 @@
-const { test } = require('node:test');
-const assert = require('node:assert');
-const { Readable } = require('stream');
-const RedactionSession = require('../index.js');
-
-// Helper to convert stream to string
-async function streamToString(stream) {
-    const chunks = [];
-    for await (const chunk of stream) {
-        chunks.push(chunk.toString());
-    }
-    return chunks.join('');
-}
-
-test('RedactionSession redacts emails', async (t) => {
-    const session = new RedactionSession();
-    const input = "Hello, my email is john.doe@example.com and jane_doe+test@gmail.co.uk.";
-
-    // Create source stream
-    const source = Readable.from([input]);
-    const redactor = session.redact();
-
-    const redactedStream = source.pipe(redactor);
-    const result = await streamToString(redactedStream);
-
-    assert.doesNotMatch(result, /john\.doe@example\.com/);
-    assert.doesNotMatch(result, /jane_doe\+test@gmail\.co\.uk/);
-    assert.match(result, /Hello, my email is <EMAIL_[0-9a-f-]+> and <EMAIL_[0-9a-f-]+>\./);
-
-    // Check map size
-    assert.strictEqual(session.tokenMap.size, 2);
-});
-
-test('RedactionSession restores emails', async (t) => {
-    const session = new RedactionSession();
-    const input = "Contact me at bob@example.com please.";
-
-    const source = Readable.from([input]);
-    const redactor = session.redact();
-    const restorer = session.restore();
-
-    // Pipeline: source -> redactor -> restorer
-    const pipeline = source.pipe(redactor).pipe(restorer);
-    const result = await streamToString(pipeline);
-
-    assert.strictEqual(result, input);
-});
-
-test('RedactionSession redacts credit cards', async (t) => {
-    const session = new RedactionSession();
-    const cc = "4532 1234 5678 9012";
-    const input = `Payment info: ${cc}`;
-
-    const source = Readable.from([input]);
-    const redactor = session.redact();
-    const result = await streamToString(source.pipe(redactor));
-
-    assert.doesNotMatch(result, /4532 1234 5678 9012/);
-    assert.match(result, /Payment info: <CC_[0-9a-f-]+>/);
-
-    // Test restore
-    const restoredSource = Readable.from([result]);
-    const restorer = session.restore();
-    const finalResult = await streamToString(restoredSource.pipe(restorer));
-    assert.strictEqual(finalResult, input);
-});
-
-test('RedactionSession redacts phone numbers', async (t) => {
-    const session = new RedactionSession();
-    const phone = "555-0199";
-    // Our simplistic regex might need full 10 digits or be specific.
-    // Let's test standard 10 digit US number
-    const phoneFull = "123-456-7890";
-    const input = `Call ${phoneFull}`;
-
-    const source = Readable.from([input]);
-    const redactor = session.redact();
-    const result = await streamToString(source.pipe(redactor));
-
-    assert.doesNotMatch(result, /123-456-7890/);
-    assert.match(result, /Call <PHONE_[0-9a-f-]+>/);
-});
-
-test('Multiple chunks handling', async (t) => {
-    const session = new RedactionSession();
-    const inputChunks = ["My email ", "is t", "est@exa", "mple.com."];
-    // Note: The simple current implementation fails if the pattern is broken across chunks absolutely cleanly
-    // But since the regex engine matches on the *concatenation* of what it has seen if we buffered properly,
-    // OR, in our simple case, it redacts per chunk.
-    // Wait, our implementation does `text = buffer + chunk.toString()`.
-    // It does NOT hold back text. So "t", "est@exa" -> "test@exa" is not an email.
-    // This test confirms the limitation OR we fix the implementation.
-    // Given the constraints, let's test *sequential* chunks that don't split tokens,
-    // or acknowledge this is a "v1" limitation that streams usually chunk by line or buffer.
-    // Let's test a case where tokens are in separate chunks.
-
-    const inputChunksSafe = ["My email is ", "test@example.com", " today."];
-    const source = Readable.from(inputChunksSafe);
-
-    const redactor = session.redact();
-    const result = await streamToString(source.pipe(redactor));
-
-    assert.doesNotMatch(result, /test@example\.com/);
-    assert.match(result, /My email is <EMAIL_[0-9a-f-]+> today\./);
-});