@princeverma130104/agentguard 1.0.1 → 1.0.2

package/README.md

@@ -1,7 +1,7 @@
 # 🛡️ AgentGuard
 
 > **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.
+> Detect, tokenise, and restore supported PII/credential patterns. Detected 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)
@@ -11,7 +11,7 @@
 
 ## 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.
+When AI agents handle user data — such as resumes, emails, SSNs, or API keys — sensitive values may be sent to an LLM provider unless the application protects them.
 
 ## The Solution
 
@@ -19,30 +19,30 @@ AgentGuard acts as an invisible middleware layer between your agent framework an
 
 ```
 ┌──────────────────────┐
-│  Agent Framework      │  (1) Raw Prompt: "Register John at john@x.com"
+│  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}
+│  AgentGuard SDK      │  (2) Detect supported PII with 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)    │
+│  LLM Provider        │  ← Does not receive detected values
+│  (OpenAI / Claude)   │
 └──────────┬───────────┘
            │ (5) Response: "Fill form with [NAME_1], [EMAIL_1]"
            ▼
 ┌──────────────────────┐
-│  AgentGuard SDK       │  (6) Restore: "Fill form with John, john@x.com"
+│  AgentGuard SDK      │  (6) Restore: "Fill form with John, john@x.com"
 └──────────┬───────────┘
            │
            ▼
 ┌──────────────────────┐
-│  Tool / Browser       │  ← Gets real values for execution
+│  Tool / Browser      │  ← Gets real values for execution
 └──────────────────────┘
 ```
 
@@ -110,6 +110,56 @@ await guard.destroySession(sessionId);
 await guard.close();
 ```
 
+### Fail-closed outbound calls and approval
+
+Route model calls through `sendToLLM` so scanning and vault writes finish before
+the outbound callback is invoked. Add an approval callback when your application
+requires a policy or human decision:
+
+```typescript
+const { result, sessionId } = await guard.sendToLLM(
+  (sanitizedPrompt) => llm.generate(sanitizedPrompt),
+  userPrompt,
+  {
+    approve: async ({ sanitizedPrompt, redactionSummary }) =>
+      approvalPolicy.allow({ sanitizedPrompt, redactionSummary }),
+  },
+);
+```
+
+Only a literal `true` approves the call. A denial, thrown error, or sanitizer
+failure prevents the LLM callback from running. The approval callback receives
+sanitized text and entity counts only—not the original prompt or detected
+values. Without an `approve` callback this method still sanitizes, but sends
+without an approval decision; that is the default for compatibility and ease
+of use.
+
+Construct the prompt with only the minimum context needed before calling this
+API. AgentGuard cannot know which facts a user considers sensitive, certify
+arbitrary text as safe, or prevent an application from bypassing this method.
+Ensure every provider call uses the gate, and do not let the send callback
+ignore its `sanitizedPrompt` argument or close over the original prompt.
+
+### Structured JSON
+
+Use the core API when your model accepts structured input or when you are not
+using Express middleware. It traverses nested arrays and objects, redacts string
+values and property names, and uses one session for the complete structure:
+
+```typescript
+const { sanitizedValue, sessionId } = await guard.anonymizeObject({
+  customer: { email: 'jane@example.com' },
+  messages: ['Call me at 415-555-0123'],
+});
+
+// Send sanitizedValue to the model, then restore only for an authorized use:
+const restored = await guard.deanonymizeObject(modelOutput, sessionId);
+```
+
+Structured methods accept JSON-compatible values only, enforce the same text
+size limit per string, and reject cyclic, excessively deep, or unsupported
+objects. Keep and authorize `sessionId` as a bearer capability.
+
 ---
 
 ## Mastra Integration
@@ -198,6 +248,9 @@ app.post('/chat', async (req, res) => {
 const guard = new AgentGuard({
   redisUrl: 'redis://localhost:6379',  // default
   ttlSeconds: 900,                     // 15 minutes default
+  maxTokensPerSession: 10_000,         // cap vault growth per session
+  maxTextLength: 1_000_000,            // maximum characters per text input
+  vaultEncryptionKey: process.env.AGENTGUARD_VAULT_KEY, // optional 32-byte hex key
   verbose: false,                      // console logging (no PII)
 });
 ```
@@ -206,7 +259,17 @@ const guard = new AgentGuard({
 |---|---|---|---|
 | `redisUrl` | `string` | `redis://localhost:6379` | Redis connection URL |
 | `ttlSeconds` | `number` | `900` | Session TTL in seconds |
-| `verbose` | `boolean` | `false` | Log operation metadata (never PII) |
+| `maxTokensPerSession` | `number` | `10000` | Maximum distinct vault values per session |
+| `maxTextLength` | `number` | `1000000` | Maximum UTF-16 code units in a text input |
+| `vaultEncryptionKey` | `string` | unset | Optional 32-byte hex key for AES-256-GCM encryption of Redis vault values |
+| `verbose` | `boolean` | `false` | Log operation metadata and a truncated session hash (never raw session IDs or PII) |
+
+The Express-compatible middleware handles string bodies and nested JSON values.
+It also scans JSON property names, not just values. Configure a strict request
+body-size limit in your HTTP framework before AgentGuard middleware; the
+`maxTextLength` limit applies to each string passed to the core guard.
+The middleware factory returns an array-compatible stack with a `close()` method;
+call it during graceful shutdown to release its Redis connection.
 
 ---
 
@@ -264,16 +327,21 @@ vault must be reachable from that service.
    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.
+   the provider's TLS URL (`rediss://...`), authentication, and least-privilege
+   ACLs. Never commit credentials or encryption keys to source control.
+3. Set `AGENTGUARD_VAULT_KEY` to a secret 64-character hex value and pass it as
+   `vaultEncryptionKey` for application-level vault encryption. Keep it stable
+   across instances; wait for existing sessions to expire before rotation.
+4. 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
+5. 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
+6. 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.
+7. If using `createGuardMiddleware`, call `await stack.close()` during graceful
+   application shutdown to close its Redis connection.
 
 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
@@ -298,7 +366,9 @@ agentguard/
 ├── tests/
 │   ├── scanner.test.ts   # Scanner unit tests
 │   ├── vault.test.ts     # Vault unit tests
-│   └── guard.test.ts     # Integration tests
+│   ├── guard.test.ts     # Integration tests
+│   ├── structured.test.ts # Structured data API tests
+│   └── outbound.test.ts  # Outbound gate tests
 ├── examples/
 │   ├── basic-usage.ts    # Standalone example
 │   └── mastra-quickstart.ts
@@ -312,19 +382,33 @@ agentguard/
 
 ## 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
+- **Important limitation**: Detection is pattern-based and can miss sensitive information. Integrate and test AgentGuard for your application; it does not by itself guarantee security or regulatory compliance.
+- **Vault contents**: Configure `vaultEncryptionKey` from a secret manager to encrypt vault values with AES-256-GCM and HMAC the reverse index. Without it, values are stored unencrypted for compatibility. Use the same key across application instances; rotating it makes existing encrypted sessions unreadable, so wait for the maximum TTL or migrate before rotation. Also use private Redis with TLS (`rediss://`), authentication, least-privilege ACLs, network restrictions, and provider-controlled encryption/backup retention.
+- **Enabling encryption on an existing deployment**: Existing plaintext Redis entries remain readable during their TTL. Destroy those sessions or wait for expiration before treating the Redis dataset as fully encrypted.
 - **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
+- **Session isolation**: Each session has its own Redis key namespace; isolation assumes callers use the correct session ID and does not replace authorization.
+- **Session authorization**: Session IDs are bearer capabilities for restoring values. Keep them out of client-visible responses, prompts, logs, and URLs; authorize callers before reusing one. AgentGuard does not authenticate users or authorize access to sessions.
+- **Audit log**: Operations are logged with timestamps, entity types, counts, and a truncated SHA-256 session hash; raw PII and full session IDs are not logged.
+- **Atomic allocation and limits**: Redis Lua scripts allocate tokens atomically and enforce a per-session vault size cap.
+- **Middleware session handling**: The response-restoration middleware keeps session IDs in a weak map rather than attaching bearer IDs to request/response objects.
+- **Outbound gate**: `sendToLLM` awaits sanitization before sending and supports an optional fail-closed approval callback.
+
+Only restore tokens for an authorized destination. Validate LLM output and tool
+arguments independently; redaction is not authorization, prompt-injection
+protection, or a safe-execution mechanism. Never let a model choose privileged
+actions solely because AgentGuard restored a token. Treat custom regex patterns
+as trusted code; do not load patterns from users or other untrusted sources.
+Test each framework integration against the exact framework/model versions in
+your application to verify the sanitized content is what actually reaches the
+provider.
 
 ### 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 |
+| Latency overhead | Not benchmarked | Depends on text size, regex patterns, and Redis |
+| Redis persistence | Deployment-configured | Local Compose disables RDB/AOF; production Redis persistence is provider-configured |
+| Session isolation | Per session | Namespaced Redis keys per session identifier |
 | Scalability | Horizontal | Stateless middleware + shared Redis |
 
 ---

package/dist/guard.d.ts

@@ -16,6 +16,8 @@ export interface GuardOptions extends VaultOptions {
      * Defaults to false.
      */
     verbose?: boolean;
+    /** Maximum number of UTF-16 code units accepted in a single text input. Defaults to 1,000,000. */
+    maxTextLength?: number;
 }
 export interface AnonymizeResult {
     /** The sanitized text with all PII replaced by placeholder tokens */
@@ -25,19 +27,47 @@ export interface AnonymizeResult {
     /** Summary of what was redacted (types and counts only — no raw values) */
     redactionSummary: Record<string, number>;
 }
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface AnonymizeObjectResult {
+    sanitizedValue: JsonValue;
+    sessionId: string;
+    redactionSummary: Record<string, number>;
+}
 export interface AuditEntry {
     timestamp: string;
-    sessionId: string;
-    operation: 'anonymize' | 'deanonymize' | 'session_destroy';
+    sessionIdHash: string;
+    operation: 'anonymize' | 'deanonymize' | 'session_destroy' | 'outbound_approved' | 'outbound_rejected';
     entityTypesRedacted?: string[];
     totalTokensRestored?: number;
 }
+export interface OutboundApprovalRequest {
+    /** Sanitized content only. Raw input is never passed to the approval callback. */
+    sanitizedPrompt: string;
+    /** Entity types detected in this prompt; no matched values are included. */
+    redactionSummary: Readonly<Record<string, number>>;
+}
+export interface OutboundCallOptions {
+    sessionId?: string;
+    /** Return true to permit the outbound call. Any other result blocks it. */
+    approve?: (request: OutboundApprovalRequest) => boolean | Promise<boolean>;
+}
+export interface OutboundCallResult<T> {
+    result: T;
+    sessionId: string;
+    redactionSummary: Record<string, number>;
+}
+export declare class OutboundApprovalError extends Error {
+    constructor();
+}
 export declare class AgentGuard {
     private readonly options;
     private readonly vault;
     private readonly verbose;
     private readonly auditLog;
     constructor(options?: GuardOptions);
+    private readonly maxTextLength;
     /**
      * Scans input text, replaces all detected PII with deterministic tokens,
      * and stores the (token → rawValue) mapping in the ephemeral Redis vault.
@@ -60,6 +90,22 @@ export declare class AgentGuard {
      * @returns              Text with all tokens replaced by original values
      */
     deanonymize(tokenizedText: string, sessionId: string): Promise<string>;
+    /**
+     * Anonymizes strings throughout a JSON-compatible value, including property
+     * names, and reuses one vault session for the complete structure.
+     */
+    anonymizeObject(value: unknown, sessionId?: string): Promise<AnonymizeObjectResult>;
+    /**
+     * Restores tokens throughout a JSON-compatible value using one session.
+     * Only call this for a session authorized by the consuming application.
+     */
+    deanonymizeObject(value: unknown, sessionId: string): Promise<JsonValue>;
+    /**
+     * Anonymizes a prompt before invoking the caller's outbound LLM function.
+     * If supplied, approval receives sanitized text only; any result other than
+     * literal true blocks the call. Sanitization or approval errors fail closed.
+     */
+    sendToLLM<T>(send: (sanitizedPrompt: string) => Promise<T>, prompt: string, options?: OutboundCallOptions): Promise<OutboundCallResult<T>>;
     /**
      * Wraps an async function, automatically anonymizing its string input
      * and deanonymizing the string output. Useful for wrapping LLM calls.
@@ -92,5 +138,8 @@ export declare class AgentGuard {
      */
     close(): Promise<void>;
     private recordAudit;
+    private hashSessionId;
+    private validateSessionId;
+    private mapJsonValue;
 }
 //# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,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;IAClB,kGAAkG;IAClG,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;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,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,SAAS,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EACL,WAAW,GACX,aAAa,GACb,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,eAAe,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5E;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,CAAC;IACV,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,qBAAa,qBAAsB,SAAQ,KAAK;;CAK/C;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;IAevD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC;;;;;;;;;;OAUG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAmE3E;;;;;;;;OAQG;IACG,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoD5E;;;OAGG;IACG,eAAe,CACnB,KAAK,EAAE,OAAO,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,qBAAqB,CAAC;IAwBjC;;;OAGG;IACG,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAW9E;;;;OAIG;IACG,SAAS,CAAC,CAAC,EACf,IAAI,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC7C,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IA2CjC;;;;;;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;IAQnB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,iBAAiB;YAMX,YAAY;CAmE3B"}

package/dist/guard.js

@@ -5,19 +5,34 @@
  * Orchestrates scanning, tokenization, vault storage, and deanonymization.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentGuard = void 0;
+exports.AgentGuard = exports.OutboundApprovalError = void 0;
 const uuid_1 = require("uuid");
+const crypto_1 = require("crypto");
 const scanner_1 = require("./scanner");
 const vault_1 = require("./vault");
+class OutboundApprovalError extends Error {
+    constructor() {
+        super('Outbound LLM request was not approved.');
+        this.name = 'OutboundApprovalError';
+    }
+}
+exports.OutboundApprovalError = OutboundApprovalError;
 class AgentGuard {
     constructor(options = {}) {
         this.options = options;
         this.auditLog = [];
+        const maxTextLength = options.maxTextLength ?? 1000000;
+        if (!Number.isSafeInteger(maxTextLength) || maxTextLength <= 0) {
+            throw new RangeError('maxTextLength must be a positive safe integer.');
+        }
         this.vault = new vault_1.TokenVault({
             redisUrl: options.redisUrl,
             ttlSeconds: options.ttlSeconds,
+            maxTokensPerSession: options.maxTokensPerSession,
+            vaultEncryptionKey: options.vaultEncryptionKey,
         });
         this.verbose = options.verbose ?? false;
+        this.maxTextLength = maxTextLength;
     }
     /**
      * Scans input text, replaces all detected PII with deterministic tokens,
@@ -31,6 +46,15 @@ class AgentGuard {
      * @returns          Sanitized text, session ID, and a redaction summary
      */
     async anonymize(text, sessionId) {
+        if (typeof text !== 'string') {
+            throw new TypeError('text must be a string.');
+        }
+        if (text.length > this.maxTextLength) {
+            throw new RangeError(`text exceeds the configured maximum of ${this.maxTextLength} characters.`);
+        }
+        if (sessionId !== undefined && (typeof sessionId !== 'string' || sessionId.length === 0 || sessionId.length > 512)) {
+            throw new TypeError('sessionId must be a non-empty string of at most 512 characters.');
+        }
         const activeSession = sessionId ?? (0, uuid_1.v4)();
         const scan = (0, scanner_1.scanText)(text, this.options.customPatterns);
         if (!scan.hasSensitiveData) {
@@ -41,46 +65,32 @@ class AgentGuard {
             };
         }
         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;
+        const tokenByValue = new Map();
         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;
+            const { token, created } = await this.vault.getOrStore(activeSession, entityType, rawValue);
+            tokenByValue.set(rawValue, token);
+            if (created) {
                 redactedCounts[entityType] = (redactedCounts[entityType] ?? 0) + 1;
             }
-            // Replace ALL occurrences of rawValue in the text
-            sanitizedText = sanitizedText.split(rawValue).join(token);
         }
+        let sanitizedText = '';
+        let cursor = 0;
+        for (const entity of scan.entities) {
+            sanitizedText += text.slice(cursor, entity.startIndex);
+            sanitizedText += tokenByValue.get(entity.value);
+            cursor = entity.endIndex;
+        }
+        sanitizedText += text.slice(cursor);
         const redactionSummary = redactedCounts;
         this.recordAudit({
             timestamp: new Date().toISOString(),
-            sessionId: activeSession,
+            sessionIdHash: this.hashSessionId(activeSession),
             operation: 'anonymize',
             entityTypesRedacted: Object.keys(redactionSummary),
         });
         if (this.verbose) {
-            console.log(`[AgentGuard] Anonymized | session=${activeSession} | types=${JSON.stringify(redactionSummary)}`);
+            console.log(`[AgentGuard] Anonymized | sessionHash=${this.hashSessionId(activeSession)} | types=${JSON.stringify(redactionSummary)}`);
         }
         return { sanitizedText, sessionId: activeSession, redactionSummary };
     }
@@ -94,26 +104,122 @@ class AgentGuard {
      * @returns              Text with all tokens replaced by original values
      */
     async deanonymize(tokenizedText, sessionId) {
+        this.validateSessionId(sessionId);
+        if (typeof tokenizedText !== 'string') {
+            throw new TypeError('tokenizedText must be a string.');
+        }
+        if (tokenizedText.length > this.maxTextLength) {
+            throw new RangeError(`tokenizedText exceeds the configured maximum of ${this.maxTextLength} characters.`);
+        }
         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++;
+        let outputLength = 0;
+        let cursor = 0;
+        const parts = [];
+        const tokenPattern = /\[[A-Z_]+_\d+\]/g;
+        let match;
+        while ((match = tokenPattern.exec(tokenizedText)) !== null) {
+            const token = match[0];
+            const replacement = Object.prototype.hasOwnProperty.call(vault, token)
+                ? vault[token]
+                : token;
+            outputLength += match.index - cursor + replacement.length;
+            if (outputLength > this.maxTextLength) {
+                throw new RangeError(`restored text exceeds the configured maximum of ${this.maxTextLength} characters.`);
             }
+            parts.push(tokenizedText.slice(cursor, match.index), replacement);
+            cursor = match.index + token.length;
+            if (Object.prototype.hasOwnProperty.call(vault, token))
+                restoredCount++;
         }
+        const tail = tokenizedText.slice(cursor);
+        if (outputLength + tail.length > this.maxTextLength) {
+            throw new RangeError(`restored text exceeds the configured maximum of ${this.maxTextLength} characters.`);
+        }
+        parts.push(tail);
+        const restoredText = parts.join('');
         this.recordAudit({
             timestamp: new Date().toISOString(),
-            sessionId,
+            sessionIdHash: this.hashSessionId(sessionId),
             operation: 'deanonymize',
             totalTokensRestored: restoredCount,
         });
         if (this.verbose) {
-            console.log(`[AgentGuard] Deanonymized | session=${sessionId} | tokensRestored=${restoredCount}`);
+            console.log(`[AgentGuard] Deanonymized | sessionHash=${this.hashSessionId(sessionId)} | tokensRestored=${restoredCount}`);
         }
         return restoredText;
     }
+    /**
+     * Anonymizes strings throughout a JSON-compatible value, including property
+     * names, and reuses one vault session for the complete structure.
+     */
+    async anonymizeObject(value, sessionId) {
+        const initial = await this.anonymize('', sessionId);
+        const redactionSummary = {};
+        const sanitizedValue = await this.mapJsonValue(value, async (text) => {
+            const result = await this.anonymize(text, initial.sessionId);
+            for (const [entityType, count] of Object.entries(result.redactionSummary)) {
+                redactionSummary[entityType] = (redactionSummary[entityType] ?? 0) + count;
+            }
+            return result.sanitizedText;
+        }, new WeakSet(), 0, 'Request');
+        return {
+            sanitizedValue,
+            sessionId: initial.sessionId,
+            redactionSummary,
+        };
+    }
+    /**
+     * Restores tokens throughout a JSON-compatible value using one session.
+     * Only call this for a session authorized by the consuming application.
+     */
+    async deanonymizeObject(value, sessionId) {
+        this.validateSessionId(sessionId);
+        return this.mapJsonValue(value, (text) => this.deanonymize(text, sessionId), new WeakSet(), 0, 'Response');
+    }
+    /**
+     * Anonymizes a prompt before invoking the caller's outbound LLM function.
+     * If supplied, approval receives sanitized text only; any result other than
+     * literal true blocks the call. Sanitization or approval errors fail closed.
+     */
+    async sendToLLM(send, prompt, options = {}) {
+        if (typeof send !== 'function') {
+            throw new TypeError('send must be a function.');
+        }
+        if (options.approve !== undefined && typeof options.approve !== 'function') {
+            throw new TypeError('approve must be a function when provided.');
+        }
+        const { sanitizedText, sessionId, redactionSummary } = await this.anonymize(prompt, options.sessionId);
+        if (options.approve) {
+            let approved;
+            try {
+                approved = await options.approve({
+                    sanitizedPrompt: sanitizedText,
+                    redactionSummary: { ...redactionSummary },
+                });
+            }
+            catch (error) {
+                this.recordAudit({
+                    timestamp: new Date().toISOString(),
+                    sessionIdHash: this.hashSessionId(sessionId),
+                    operation: 'outbound_rejected',
+                    entityTypesRedacted: Object.keys(redactionSummary),
+                });
+                throw error;
+            }
+            this.recordAudit({
+                timestamp: new Date().toISOString(),
+                sessionIdHash: this.hashSessionId(sessionId),
+                operation: approved === true ? 'outbound_approved' : 'outbound_rejected',
+                entityTypesRedacted: Object.keys(redactionSummary),
+            });
+            if (approved !== true) {
+                throw new OutboundApprovalError();
+            }
+        }
+        const result = await send(sanitizedText);
+        return { result, sessionId, redactionSummary };
+    }
     /**
      * Wraps an async function, automatically anonymizing its string input
      * and deanonymizing the string output. Useful for wrapping LLM calls.
@@ -139,18 +245,18 @@ class AgentGuard {
         await this.vault.destroySession(sessionId);
         this.recordAudit({
             timestamp: new Date().toISOString(),
-            sessionId,
+            sessionIdHash: this.hashSessionId(sessionId),
             operation: 'session_destroy',
         });
         if (this.verbose) {
-            console.log(`[AgentGuard] Session destroyed | session=${sessionId}`);
+            console.log(`[AgentGuard] Session destroyed | sessionHash=${this.hashSessionId(sessionId)}`);
         }
     }
     /**
      * Returns the in-memory audit log (no PII, only metadata).
      */
     getAuditLog() {
-        return this.auditLog;
+        return this.auditLog.map((entry) => ({ ...entry }));
     }
     /**
      * Checks Redis connectivity. Use in health-check endpoints.
@@ -172,6 +278,65 @@ class AgentGuard {
             this.auditLog.shift();
         }
     }
+    hashSessionId(sessionId) {
+        return (0, crypto_1.createHash)('sha256').update(sessionId).digest('hex').slice(0, 16);
+    }
+    validateSessionId(sessionId) {
+        if (typeof sessionId !== 'string' || sessionId.length === 0 || sessionId.length > 512) {
+            throw new TypeError('sessionId must be a non-empty string of at most 512 characters.');
+        }
+    }
+    async mapJsonValue(value, mapText, ancestors, depth, label) {
+        if (depth > 100) {
+            throw new RangeError(`${label} body exceeds the maximum nesting depth of 100.`);
+        }
+        if (typeof value === 'string')
+            return mapText(value);
+        if (value === null ||
+            typeof value === 'boolean' ||
+            (typeof value === 'number' && Number.isFinite(value))) {
+            return value;
+        }
+        if (typeof value !== 'object') {
+            throw new TypeError(`${label} body must contain only JSON-compatible values.`);
+        }
+        if (ancestors.has(value)) {
+            throw new TypeError(`${label} body must not contain circular references.`);
+        }
+        if (!Array.isArray(value) &&
+            Object.getPrototypeOf(value) !== Object.prototype &&
+            Object.getPrototypeOf(value) !== null) {
+            throw new TypeError(`${label} body must contain only JSON-compatible objects.`);
+        }
+        ancestors.add(value);
+        try {
+            if (Array.isArray(value)) {
+                const result = [];
+                for (const item of value) {
+                    result.push(await this.mapJsonValue(item, mapText, ancestors, depth + 1, label));
+                }
+                return result;
+            }
+            const result = {};
+            for (const [key, item] of Object.entries(value)) {
+                const mappedKey = await mapText(key);
+                const mappedValue = await this.mapJsonValue(item, mapText, ancestors, depth + 1, label);
+                if (Object.prototype.hasOwnProperty.call(result, mappedKey)) {
+                    throw new TypeError(`${label} property names collide after anonymization.`);
+                }
+                Object.defineProperty(result, mappedKey, {
+                    configurable: true,
+                    enumerable: true,
+                    value: mappedValue,
+                    writable: true,
+                });
+            }
+            return result;
+        }
+        finally {
+            ancestors.delete(value);
+        }
+    }
 }
 exports.AgentGuard = AgentGuard;
 //# sourceMappingURL=guard.js.map