@princeverma130104/agentguard 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AgentGuard Contributors
+
+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,334 @@
-# Temporary Holding Version
+# 🛡️ AgentGuard
 
-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.
+> **Privacy & Context Redaction Middleware for AI Agents**  
+> Detect, tokenise, and restore PII/credentials in real time — sensitive values are kept in your configured Redis vault and are not sent to the LLM.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org)
+
+---
+
+## The Problem
+
+When you build AI agents that handle user data — resumes, emails, SSNs, API keys — that data flows raw into your LLM provider's servers. This violates GDPR, SOC2, and HIPAA, and exposes your users to data breaches.
+
+## The Solution
+
+AgentGuard acts as an invisible middleware layer between your agent framework and the LLM:
+
+```
+┌──────────────────────┐
+│  Agent Framework      │  (1) Raw Prompt: "Register John at john@x.com"
+│  (Mastra / LangChain)│
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  AgentGuard SDK       │  (2) Detect PII with Regex/NLP patterns
+│  (Local Middleware)   │  (3) Store in Redis: {[EMAIL_1]: john@x.com}
+└──────────┬───────────┘
+           │ (4) Sanitized: "Register [NAME_1] at [EMAIL_1]"
+           ▼
+┌──────────────────────┐
+│  LLM Provider         │  ← Never sees real PII
+│  (OpenAI / Claude)    │
+└──────────┬───────────┘
+           │ (5) Response: "Fill form with [NAME_1], [EMAIL_1]"
+           ▼
+┌──────────────────────┐
+│  AgentGuard SDK       │  (6) Restore: "Fill form with John, john@x.com"
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Tool / Browser       │  ← Gets real values for execution
+└──────────────────────┘
+```
+
+---
+
+## Features
+
+| Feature | Status |
+|---|---|
+| 📧 Email, 📱 Phone, 🔑 API Key detection | ✅ |
+| 🇺🇸 SSN, 🇮🇳 Aadhaar, 💳 Credit Card | ✅ |
+| ☁️ AWS Access Keys, Bearer Tokens | ✅ |
+| 🔒 URL with embedded credentials | ✅ |
+| 🧠 Multi-turn session deduplication | ✅ |
+| ⚡ Redis-backed ephemeral vault (TTL) | ✅ |
+| 🔄 Mastra framework wrapper | ✅ |
+| 🦜 LangChain.js callback handler | ✅ |
+| 🌐 Express HTTP middleware | ✅ |
+| 📊 Audit log (metadata only, no PII) | ✅ |
+| 🐳 Docker Compose ready | ✅ |
+| 🧪 Vitest test suite (80% coverage) | ✅ |
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install @princeverma130104/agentguard
+```
+
+### 2. Start Redis
+
+```bash
+docker-compose up -d
+```
+
+### 3. Use
+
+```typescript
+import { AgentGuard } from '@princeverma130104/agentguard';
+
+const guard = new AgentGuard({
+  redisUrl: 'redis://localhost:6379',
+  ttlSeconds: 900,
+});
+
+// Anonymize before sending to LLM
+const { sanitizedText, sessionId } = await guard.anonymize(
+  'Please register John Smith at john@acme.com, SSN 123-45-6789'
+);
+// sanitizedText → "Please register [NAME_1] at [EMAIL_1], SSN [SSN_1]"
+
+// ... send sanitizedText to your LLM ...
+
+// Deanonymize before tool execution
+const toolInput = await guard.deanonymize(
+  'Fill form: [NAME_1] <[EMAIL_1]>',
+  sessionId
+);
+// toolInput → "Fill form: John Smith <john@acme.com>"
+
+await guard.destroySession(sessionId);
+await guard.close();
+```
+
+---
+
+## Mastra Integration
+
+```typescript
+import { createMastraGuard } from '@princeverma130104/agentguard/mastra';
+
+const { wrapStep } = createMastraGuard({
+  redisUrl: process.env.REDIS_URL,
+});
+
+// Wrap any Mastra step — anonymization/deanonymization is automatic
+const myStep = {
+  execute: wrapStep(async ({ context }) => {
+    // context.prompt is already sanitized here
+    const response = await callLLM(context.prompt);
+    return { text: response }; // response tokens are auto-restored
+  }),
+};
+```
+
+---
+
+## LangChain.js Integration
+
+```typescript
+import { createLangChainGuard } from '@princeverma130104/agentguard/langchain';
+import { ChatOpenAI } from '@langchain/openai';
+
+const { handler, restore } = createLangChainGuard({
+  redisUrl: process.env.REDIS_URL,
+});
+
+// Just pass the handler as a callback — no other changes needed
+const llm = new ChatOpenAI({ callbacks: [handler] });
+const result = await llm.invoke('My SSN is 123-45-6789');
+
+// Restore real values in the output before using in tools
+const clean = await restore(result.content, handler.sessionId);
+```
+
+---
+
+## Express Middleware
+
+```typescript
+import express from 'express';
+import { createGuardMiddleware } from '@princeverma130104/agentguard/middleware';
+
+const app = express();
+app.use(express.json());
+app.use(...createGuardMiddleware({ redisUrl: process.env.REDIS_URL }));
+
+// All request body strings are automatically anonymized
+// All response body strings are automatically deanonymized
+app.post('/chat', async (req, res) => {
+  const response = await callLLM(req.body.prompt); // already sanitized
+  res.json({ text: response }); // auto-deanonymized before sending
+});
+```
+
+---
+
+## Detected Entity Types
+
+| Token Pattern | Detects |
+|---|---|
+| `[EMAIL_N]` | Email addresses |
+| `[PHONE_N]` | US phone numbers |
+| `[SSN_N]` | US Social Security Numbers |
+| `[AADHAAR_N]` | Indian Aadhaar numbers |
+| `[CREDIT_CARD_N]` | Visa, Mastercard, Amex, Discover |
+| `[API_KEY_N]` | Stripe, OpenAI-style secret keys |
+| `[BEARER_TOKEN_N]` | HTTP Bearer tokens |
+| `[AWS_KEY_N]` | AWS Access Key IDs |
+| `[PRIVATE_KEY_N]` | PEM private keys |
+| `[URL_WITH_CREDS_N]` | `user:pass@host` style URLs |
+| `[IP_ADDRESS_N]` | IPv4 addresses |
+| `[NAME_N]` | Named entity heuristic |
+
+---
+
+## Configuration
+
+```typescript
+const guard = new AgentGuard({
+  redisUrl: 'redis://localhost:6379',  // default
+  ttlSeconds: 900,                     // 15 minutes default
+  verbose: false,                      // console logging (no PII)
+});
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `redisUrl` | `string` | `redis://localhost:6379` | Redis connection URL |
+| `ttlSeconds` | `number` | `900` | Session TTL in seconds |
+| `verbose` | `boolean` | `false` | Log operation metadata (never PII) |
+
+---
+
+## Running Tests
+
+```bash
+# Unit tests only (no Redis required)
+npm run test:unit
+
+# All tests (requires Redis via docker-compose up -d)
+npm test
+
+# With coverage report
+npm run test:coverage
+```
+
+---
+
+## Deploying AgentGuard
+
+AgentGuard is a Node.js library, not a standalone web application. Deploy it by
+publishing the package to npm and using it from your agent/API service. The Redis
+vault must be reachable from that service.
+
+### Prepare a release
+
+1. The published package name is `@princeverma130104/agentguard`. To publish
+   under a different npm account, change `name` in `package.json` and the
+   lockfile to a scope that account owns.
+2. Replace the repository, bugs, homepage, and author placeholders in
+   `package.json` with your project details.
+3. Run the production checks and inspect the package contents:
+
+   ```bash
+   npm ci
+   npm run build
+   npm test
+   npm pack --dry-run
+   ```
+
+4. Sign in to npm and publish:
+
+   ```bash
+   npm login
+   npm publish
+   ```
+
+   For a scoped package intended for public use, publish with
+   `npm publish --access public`. `prepublishOnly` rebuilds the package and runs
+   the test suite before publication.
+
+### Deploy the consuming service
+
+1. Provision a Redis instance reachable only by your application. Use a managed
+   Redis service with TLS for production; do not expose the local Docker Redis
+   port to the public internet.
+2. Set `REDIS_URL` in the application host's secret/environment settings. Use
+   the provider's TLS URL (`rediss://...`) when offered, and never commit
+   credentials in `.env` or source control.
+3. Set `AGENTGUARD_TTL_SECONDS` if the default 900 seconds is not appropriate.
+   Configure your app to pass `REDIS_URL` and the desired TTL to `AgentGuard`.
+4. Install the published package in the application, deploy the service using
+   its normal Node.js deployment process, and verify Redis connectivity with
+   `await guard.healthCheck()` before accepting traffic.
+5. Ensure your Redis provider's persistence, backups, access controls, and
+   retention settings meet your privacy requirements. AgentGuard cannot disable
+   persistence on an externally managed Redis service.
+
+The included `docker-compose.yml` is for local development only. It binds Redis
+to localhost and disables RDB snapshots and AOF persistence; it is not a
+production Redis deployment. Your service host and Redis must be networked
+together, and the service must receive the Redis URL through its secret manager.
+
+---
+
+## Project Structure
+
+```
+agentguard/
+├── src/
+│   ├── index.ts          # Public API barrel exports
+│   ├── guard.ts          # Core AgentGuard class
+│   ├── vault.ts          # Redis token vault
+│   ├── scanner.ts        # PII detection engine
+│   ├── patterns.ts       # Regex pattern registry
+│   ├── middleware.ts      # Express middleware
+│   ├── mastra.ts         # Mastra framework wrapper
+│   └── langchain.ts      # LangChain.js callback handler
+├── tests/
+│   ├── scanner.test.ts   # Scanner unit tests
+│   ├── vault.test.ts     # Vault unit tests
+│   └── guard.test.ts     # Integration tests
+├── examples/
+│   ├── basic-usage.ts    # Standalone example
+│   └── mastra-quickstart.ts
+├── docker-compose.yml
+├── .env.example
+├── tsconfig.json
+└── vitest.config.ts
+```
+
+---
+
+## Security & Compliance
+
+- **Ephemeral vault**: Raw PII is stored in Redis and is not sent to the LLM; configure Redis persistence and access controls to match your privacy requirements
+- **TTL enforcement**: All session data expires automatically (default 15 min)
+- **Session isolation**: Each session has its own Redis key namespace — no cross-session leakage
+- **Audit log**: All operations are logged with timestamps and entity types only — never raw PII values
+- **Pipeline batching**: Vault reads/writes use Redis pipelines to minimise latency overhead
+
+### NFR Compliance
+
+| Requirement | Target | Implementation |
+|---|---|---|
+| Latency overhead | < 15ms | Redis pipeline batching |
+| Zero persistence | No disk writes | Local Compose disables RDB/AOF; production Redis persistence is provider-configured |
+| Session isolation | Per session | Namespaced Redis keys per session UUID |
+| Scalability | Horizontal | Stateless middleware + shared Redis |
+
+---
+
+## License
+
+MIT © AgentGuard Contributors

package/dist/guard.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @file guard.ts
+ * @description Core AgentGuard class — the main public API.
+ * Orchestrates scanning, tokenization, vault storage, and deanonymization.
+ */
+import { VaultOptions } from './vault';
+import { PatternKey } from './patterns';
+export interface GuardOptions extends VaultOptions {
+    /**
+     * Custom pattern overrides or additions. Keys are entity type labels,
+     * values are RegExp factory functions (must return a /g-flagged RegExp).
+     */
+    customPatterns?: Partial<Record<PatternKey, () => RegExp>>;
+    /**
+     * If true, logs redaction summaries to console (no raw PII ever logged).
+     * Defaults to false.
+     */
+    verbose?: boolean;
+}
+export interface AnonymizeResult {
+    /** The sanitized text with all PII replaced by placeholder tokens */
+    sanitizedText: string;
+    /** The session ID that maps tokens back to their raw values in the vault */
+    sessionId: string;
+    /** Summary of what was redacted (types and counts only — no raw values) */
+    redactionSummary: Record<string, number>;
+}
+export interface AuditEntry {
+    timestamp: string;
+    sessionId: string;
+    operation: 'anonymize' | 'deanonymize' | 'session_destroy';
+    entityTypesRedacted?: string[];
+    totalTokensRestored?: number;
+}
+export declare class AgentGuard {
+    private readonly options;
+    private readonly vault;
+    private readonly verbose;
+    private readonly auditLog;
+    constructor(options?: GuardOptions);
+    /**
+     * Scans input text, replaces all detected PII with deterministic tokens,
+     * and stores the (token → rawValue) mapping in the ephemeral Redis vault.
+     *
+     * If a `sessionId` is provided, tokens are added to the existing session.
+     * Otherwise, a new session UUID is created automatically.
+     *
+     * @param text       Raw text potentially containing PII/credentials
+     * @param sessionId  Optional existing session to extend
+     * @returns          Sanitized text, session ID, and a redaction summary
+     */
+    anonymize(text: string, sessionId?: string): Promise<AnonymizeResult>;
+    /**
+     * Re-injects raw PII values into tokenized text before tool execution.
+     * Looks up all tokens from the session vault and replaces them with
+     * their original values.
+     *
+     * @param tokenizedText  Text containing AgentGuard placeholder tokens
+     * @param sessionId      The session ID returned from `anonymize()`
+     * @returns              Text with all tokens replaced by original values
+     */
+    deanonymize(tokenizedText: string, sessionId: string): Promise<string>;
+    /**
+     * Wraps an async function, automatically anonymizing its string input
+     * and deanonymizing the string output. Useful for wrapping LLM calls.
+     *
+     * @example
+     * const safeCall = guard.wrapCall(openai.chat.completions.create.bind(openai));
+     */
+    wrapCall<T>(fn: (sanitizedInput: string) => Promise<T>, rawInput: string, sessionId?: string, outputExtractor?: (result: T) => string, outputInjector?: (result: T, restored: string) => T): Promise<{
+        result: T;
+        sessionId: string;
+    }>;
+    /**
+     * Explicitly destroys a session and all its vault data from Redis.
+     * Call this when a user session completes to proactively free memory.
+     */
+    destroySession(sessionId: string): Promise<void>;
+    /**
+     * Returns the in-memory audit log (no PII, only metadata).
+     */
+    getAuditLog(): ReadonlyArray<AuditEntry>;
+    /**
+     * Checks Redis connectivity. Use in health-check endpoints.
+     */
+    healthCheck(): Promise<{
+        status: 'ok' | 'degraded';
+        redis: boolean;
+    }>;
+    /**
+     * Gracefully shuts down the vault connection.
+     */
+    close(): Promise<void>;
+    private recordAudit;
+}
+//# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAc,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,MAAM,CAAC,CAAC,CAAC;IAC3D;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,WAAW,GAAG,aAAa,GAAG,iBAAiB,CAAC;IAC3D,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,qBAAa,UAAU;IAKT,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;gBAEhB,OAAO,GAAE,YAAiB;IAQvD;;;;;;;;;;OAUG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAsE3E;;;;;;;;OAQG;IACG,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4B5E;;;;;;OAMG;IACG,QAAQ,CAAC,CAAC,EACd,EAAE,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,EACvC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC,GAClD,OAAO,CAAC;QAAE,MAAM,EAAE,CAAC,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAa5C;;;OAGG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtD;;OAEG;IACH,WAAW,IAAI,aAAa,CAAC,UAAU,CAAC;IAIxC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,IAAI,GAAG,UAAU,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAK3E;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,OAAO,CAAC,WAAW;CAOpB"}

package/dist/guard.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * @file guard.ts
+ * @description Core AgentGuard class — the main public API.
+ * Orchestrates scanning, tokenization, vault storage, and deanonymization.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentGuard = void 0;
+const uuid_1 = require("uuid");
+const scanner_1 = require("./scanner");
+const vault_1 = require("./vault");
+class AgentGuard {
+    constructor(options = {}) {
+        this.options = options;
+        this.auditLog = [];
+        this.vault = new vault_1.TokenVault({
+            redisUrl: options.redisUrl,
+            ttlSeconds: options.ttlSeconds,
+        });
+        this.verbose = options.verbose ?? false;
+    }
+    /**
+     * Scans input text, replaces all detected PII with deterministic tokens,
+     * and stores the (token → rawValue) mapping in the ephemeral Redis vault.
+     *
+     * If a `sessionId` is provided, tokens are added to the existing session.
+     * Otherwise, a new session UUID is created automatically.
+     *
+     * @param text       Raw text potentially containing PII/credentials
+     * @param sessionId  Optional existing session to extend
+     * @returns          Sanitized text, session ID, and a redaction summary
+     */
+    async anonymize(text, sessionId) {
+        const activeSession = sessionId ?? (0, uuid_1.v4)();
+        const scan = (0, scanner_1.scanText)(text, this.options.customPatterns);
+        if (!scan.hasSensitiveData) {
+            return {
+                sanitizedText: text,
+                sessionId: activeSession,
+                redactionSummary: {},
+            };
+        }
+        const uniqueValues = (0, scanner_1.extractUniqueValues)(scan);
+        const typeCounters = {};
+        const redactedCounts = {};
+        const existingVault = await this.vault.getVault(activeSession);
+        for (const token of Object.keys(existingVault)) {
+            const match = /^\[([A-Z_]+)_(\d+)\]$/.exec(token);
+            if (match) {
+                typeCounters[match[1]] = Math.max(typeCounters[match[1]] ?? 0, Number(match[2]));
+            }
+        }
+        let sanitizedText = text;
+        for (const [rawValue, entityType] of uniqueValues.entries()) {
+            // Check if this value already has a token in the session (deduplication)
+            const existingToken = await this.vault.lookupToken(activeSession, rawValue);
+            let token;
+            if (existingToken) {
+                token = existingToken;
+            }
+            else {
+                typeCounters[entityType] = (typeCounters[entityType] ?? 0) + 1;
+                token = `[${entityType}_${typeCounters[entityType]}]`;
+                while (Object.prototype.hasOwnProperty.call(existingVault, token)) {
+                    typeCounters[entityType]++;
+                    token = `[${entityType}_${typeCounters[entityType]}]`;
+                }
+                await this.vault.store(activeSession, token, rawValue);
+                existingVault[token] = rawValue;
+                redactedCounts[entityType] = (redactedCounts[entityType] ?? 0) + 1;
+            }
+            // Replace ALL occurrences of rawValue in the text
+            sanitizedText = sanitizedText.split(rawValue).join(token);
+        }
+        const redactionSummary = redactedCounts;
+        this.recordAudit({
+            timestamp: new Date().toISOString(),
+            sessionId: activeSession,
+            operation: 'anonymize',
+            entityTypesRedacted: Object.keys(redactionSummary),
+        });
+        if (this.verbose) {
+            console.log(`[AgentGuard] Anonymized | session=${activeSession} | types=${JSON.stringify(redactionSummary)}`);
+        }
+        return { sanitizedText, sessionId: activeSession, redactionSummary };
+    }
+    /**
+     * Re-injects raw PII values into tokenized text before tool execution.
+     * Looks up all tokens from the session vault and replaces them with
+     * their original values.
+     *
+     * @param tokenizedText  Text containing AgentGuard placeholder tokens
+     * @param sessionId      The session ID returned from `anonymize()`
+     * @returns              Text with all tokens replaced by original values
+     */
+    async deanonymize(tokenizedText, sessionId) {
+        const vault = await this.vault.getVault(sessionId);
+        let restoredText = tokenizedText;
+        let restoredCount = 0;
+        for (const [token, rawValue] of Object.entries(vault)) {
+            if (restoredText.includes(token)) {
+                restoredText = restoredText.split(token).join(rawValue);
+                restoredCount++;
+            }
+        }
+        this.recordAudit({
+            timestamp: new Date().toISOString(),
+            sessionId,
+            operation: 'deanonymize',
+            totalTokensRestored: restoredCount,
+        });
+        if (this.verbose) {
+            console.log(`[AgentGuard] Deanonymized | session=${sessionId} | tokensRestored=${restoredCount}`);
+        }
+        return restoredText;
+    }
+    /**
+     * Wraps an async function, automatically anonymizing its string input
+     * and deanonymizing the string output. Useful for wrapping LLM calls.
+     *
+     * @example
+     * const safeCall = guard.wrapCall(openai.chat.completions.create.bind(openai));
+     */
+    async wrapCall(fn, rawInput, sessionId, outputExtractor, outputInjector) {
+        const { sanitizedText, sessionId: sid } = await this.anonymize(rawInput, sessionId);
+        const result = await fn(sanitizedText);
+        if (outputExtractor && outputInjector) {
+            const rawOutput = outputExtractor(result);
+            const restoredOutput = await this.deanonymize(rawOutput, sid);
+            return { result: outputInjector(result, restoredOutput), sessionId: sid };
+        }
+        return { result, sessionId: sid };
+    }
+    /**
+     * Explicitly destroys a session and all its vault data from Redis.
+     * Call this when a user session completes to proactively free memory.
+     */
+    async destroySession(sessionId) {
+        await this.vault.destroySession(sessionId);
+        this.recordAudit({
+            timestamp: new Date().toISOString(),
+            sessionId,
+            operation: 'session_destroy',
+        });
+        if (this.verbose) {
+            console.log(`[AgentGuard] Session destroyed | session=${sessionId}`);
+        }
+    }
+    /**
+     * Returns the in-memory audit log (no PII, only metadata).
+     */
+    getAuditLog() {
+        return this.auditLog;
+    }
+    /**
+     * Checks Redis connectivity. Use in health-check endpoints.
+     */
+    async healthCheck() {
+        const redis = await this.vault.ping();
+        return { status: redis ? 'ok' : 'degraded', redis };
+    }
+    /**
+     * Gracefully shuts down the vault connection.
+     */
+    async close() {
+        await this.vault.close();
+    }
+    recordAudit(entry) {
+        this.auditLog.push(entry);
+        // Keep audit log bounded to last 1000 entries
+        if (this.auditLog.length > 1000) {
+            this.auditLog.shift();
+        }
+    }
+}
+exports.AgentGuard = AgentGuard;
+//# sourceMappingURL=guard.js.map

package/dist/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file index.ts
+ * @description Public API surface for the AgentGuard npm package.
+ * Import from 'agentguard' for core functionality.
+ * Import from 'agentguard/mastra' for Mastra-specific wrappers.
+ * Import from 'agentguard/langchain' for LangChain.js integration.
+ */
+export { AgentGuard } from './guard';
+export type { GuardOptions, AnonymizeResult, AuditEntry } from './guard';
+export { TokenVault } from './vault';
+export type { VaultOptions } from './vault';
+export { scanText, extractUniqueValues } from './scanner';
+export type { DetectedEntity, ScanResult } from './scanner';
+export { PATTERN_REGISTRY, PATTERN_ORDER } from './patterns';
+export type { PatternKey } from './patterns';
+export { createRequestMiddleware, createResponseMiddleware, createGuardMiddleware, } from './middleware';
+export type { GuardRequest, GuardResponse } from './middleware';
+export { createMastraGuard } from './mastra';
+export type { MastraGuard, MastraStepContext, MastraStepResult } from './mastra';
+export { createLangChainGuard } from './langchain';
+export type { LangChainGuard, LangChainGuardHandler } from './langchain';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGzE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG5C,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}