@intflows/genkit-guard 0.0.10 → 0.0.12

package/README.md

@@ -203,45 +203,48 @@ pii: {
 By default, PII is stored in an in-memory vault scoped to a single tokenizer instance. Tokens include a generated vault scope:
 
 ```txt
-"Email john.doe@example.com" -> "Email [[EMAIL_<namespace>_0]]"
+"Email john.doe@example.com" -> "Email [[EMAIL_<namespace>_0]]"
 ```
 
-That generated namespace prevents two concurrent calls from sharing the same visible placeholder names. Vault lookups are isolated by the configured storage scope, so User A and User B can safely produce their own email tokens without cross-resolving each other's PII.
+That generated namespace prevents two concurrent calls from sharing the same visible placeholder names. Vault lookups are isolated by the configured storage scope, so User A and User B can safely produce their own email tokens without cross-resolving each other's PII.
 
-For applications that need persistence, distributed workers, audits, or tenant-specific storage, provide a vault storage backend:
+For applications that need persistence, distributed workers, audits, or tenant-specific storage, provide a vault storage backend. Redis clients can be passed through the built-in helper:
+For applications that need persistence, distributed workers, audits, or tenant-specific storage, provide a vault storage backend. Redis clients can be passed through the built-in helper:
 
 ```ts
-import { guard, type PiiVaultStorage } from "@intflows/genkit-guard";
+import { createClient } from "redis";
+import { guard, createRedisPiiVaultStorage } from "@intflows/genkit-guard";
 
-class RedisPiiVaultStorage implements PiiVaultStorage {
-  constructor(private redis: RedisClient) {}
-
-  async get(scopeId: string, token: string) {
-    return this.redis.hget(`pii:${scopeId}`, token);
-  }
-
-  async set(scopeId: string, token: string, value: string) {
-    await this.redis.hset(`pii:${scopeId}`, token, value);
-  }
-
-  async entries(scopeId: string) {
-    const values = await this.redis.hgetall(`pii:${scopeId}`);
-    return Object.entries(values).map(([token, value]) => ({ token, value }));
-  }
-}
+const redis = createClient({ url: "redis://localhost:6379" });
+await redis.connect();
 
 guard({
   pii: {
     reversible: true,
     vault: {
-      storage: new RedisPiiVaultStorage(redis),
+      storage: createRedisPiiVaultStorage(redis, {
+        keyPrefix: "my-app:pii",
+        ttlSeconds: 3600,
+        fallbackToMemory: true
+      }),
       scopeId: (req, ctx) => ctx?.auth?.sessionId ?? req?.metadata?.requestId
     }
   }
 });
 ```
 
-Choose a `scopeId` that matches your isolation boundary, such as request ID, session ID, tenant/user ID, or a combination like `tenantId:userId:requestId`. A shared external backend should never ignore `scopeId`, because placeholders are only safe when resolved against the correct vault scope. The placeholder sent to the model uses an opaque generated namespace rather than exposing your `scopeId`.
+`ttlSeconds` applies the configured expiry to both the scoped vault and token index. When
+`fallbackToMemory` is enabled, successful writes are also mirrored in process memory and Redis
+operation failures fall back to that mirror. The fallback is disabled by default, is local to one
+process, and is not a replacement for Redis persistence or multi-worker availability. Its in-memory
+entries observe the same TTL. Redis errors continue to propagate when fallback is disabled.
+
+For another backend, use `createPiiVaultStorage({ get, set, entries, getByToken })` with your database, cache, or secret store.
+
+Choose a `scopeId` that matches your isolation boundary, such as request ID, session ID, tenant/user ID, or a combination like `tenantId:userId:requestId`. A shared external backend should never ignore `scopeId`, because placeholders are only safe when resolved against the correct vault scope. The placeholder sent to the model uses an opaque generated namespace rather than exposing your `scopeId`.
+
+### Screenshots
+![Redis Stored PII ](redis-scan.png)
 
 ---
 

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { guard, guardAction, guardMiddleware, guardPlugin } from './middleware/middleware.js';
-export { InMemoryPiiVaultStorage, defaultPiiVaultStorage } from './pii/storage.js';
-export type { PiiVaultEntry, PiiVaultStorage } from './pii/storage.js';
+export type { GuardConfig } from './middleware/middleware.js';
+export { InMemoryPiiVaultStorage, createPiiVaultStorage, createRedisPiiVaultStorage, defaultPiiVaultStorage, } from './pii/storage.js';
+export type { PiiVaultEntry, PiiVaultStorage, PiiVaultStorageAdapter, RedisPiiVaultClient, RedisPiiVaultStorageOptions, } from './pii/storage.js';
 export * from './core/types.js';
 /**
  * Pre-load the model to avoid cold-start delay on first user request.

package/dist/index.js

@@ -1,7 +1,7 @@
 import { ModelSingleton } from './util/singleton.js';
 // export { intentGuard, piiGuard  } from './middleware/middleware.js';
 export { guard, guardAction, guardMiddleware, guardPlugin } from './middleware/middleware.js';
-export { InMemoryPiiVaultStorage, defaultPiiVaultStorage } from './pii/storage.js';
+export { InMemoryPiiVaultStorage, createPiiVaultStorage, createRedisPiiVaultStorage, defaultPiiVaultStorage, } from './pii/storage.js';
 export * from './core/types.js';
 function logGuardEvent(eventName, body, attributes = {}) {
     console.log(JSON.stringify({

package/dist/middleware/middleware.d.ts

@@ -1,254 +1,34 @@
 import { z } from 'genkit';
 import { type PiiVaultStorage } from '../pii/storage.js';
-declare const guardConfigSchema: z.ZodObject<{
-    intent: z.ZodOptional<z.ZodObject<{
-        mode: z.ZodOptional<z.ZodString>;
-        allowedIntent: z.ZodOptional<z.ZodString>;
-        semantic: z.ZodObject<{
-            threshold: z.ZodOptional<z.ZodNumber>;
-            intents: z.ZodRecord<z.ZodString, z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            intents: Record<string, string>;
-            threshold?: number | undefined;
-        }, {
-            intents: Record<string, string>;
-            threshold?: number | undefined;
-        }>;
-    }, "strip", z.ZodTypeAny, {
-        semantic: {
-            intents: Record<string, string>;
-            threshold?: number | undefined;
-        };
-        mode?: string | undefined;
-        allowedIntent?: string | undefined;
-    }, {
-        semantic: {
-            intents: Record<string, string>;
-            threshold?: number | undefined;
-        };
-        mode?: string | undefined;
-        allowedIntent?: string | undefined;
-    }>>;
-    pii: z.ZodOptional<z.ZodObject<{
-        reversible: z.ZodOptional<z.ZodBoolean>;
-        model: z.ZodOptional<z.ZodString>;
-        mode: z.ZodOptional<z.ZodEnum<["ner", "classifier"]>>;
-        vault: z.ZodOptional<z.ZodObject<{
-            storage: z.ZodOptional<z.ZodAny>;
-            scopeId: z.ZodOptional<z.ZodAny>;
-        }, "strip", z.ZodTypeAny, {
-            storage?: any;
-            scopeId?: any;
-        }, {
-            storage?: any;
-            scopeId?: any;
-        }>>;
-    }, "strip", z.ZodTypeAny, {
-        mode?: "ner" | "classifier" | undefined;
-        reversible?: boolean | undefined;
-        model?: string | undefined;
-        vault?: {
-            storage?: any;
-            scopeId?: any;
-        } | undefined;
-    }, {
-        mode?: "ner" | "classifier" | undefined;
-        reversible?: boolean | undefined;
-        model?: string | undefined;
-        vault?: {
-            storage?: any;
-            scopeId?: any;
-        } | undefined;
-    }>>;
-    logging: z.ZodOptional<z.ZodObject<{
-        enabled: z.ZodOptional<z.ZodBoolean>;
-        level: z.ZodOptional<z.ZodEnum<["debug", "info", "warn", "error"]>>;
-        serviceName: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        enabled?: boolean | undefined;
-        level?: "debug" | "info" | "warn" | "error" | undefined;
-        serviceName?: string | undefined;
-    }, {
-        enabled?: boolean | undefined;
-        level?: "debug" | "info" | "warn" | "error" | undefined;
-        serviceName?: string | undefined;
-    }>>;
-    models: z.ZodOptional<z.ZodObject<{
-        extractor: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        extractor?: string | undefined;
-    }, {
-        extractor?: string | undefined;
-    }>>;
-}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    intent: z.ZodOptional<z.ZodObject<{
-        mode: z.ZodOptional<z.ZodString>;
-        allowedIntent: z.ZodOptional<z.ZodString>;
-        semantic: z.ZodObject<{
-            threshold: z.ZodOptional<z.ZodNumber>;
-            intents: z.ZodRecord<z.ZodString, z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            intents: Record<string, string>;
-            threshold?: number | undefined;
-        }, {
-            intents: Record<string, string>;
-            threshold?: number | undefined;
-        }>;
-    }, "strip", z.ZodTypeAny, {
-        semantic: {
-            intents: Record<string, string>;
-            threshold?: number | undefined;
-        };
-        mode?: string | undefined;
-        allowedIntent?: string | undefined;
-    }, {
-        semantic: {
-            intents: Record<string, string>;
-            threshold?: number | undefined;
-        };
-        mode?: string | undefined;
-        allowedIntent?: string | undefined;
-    }>>;
-    pii: z.ZodOptional<z.ZodObject<{
-        reversible: z.ZodOptional<z.ZodBoolean>;
-        model: z.ZodOptional<z.ZodString>;
-        mode: z.ZodOptional<z.ZodEnum<["ner", "classifier"]>>;
-        vault: z.ZodOptional<z.ZodObject<{
-            storage: z.ZodOptional<z.ZodAny>;
-            scopeId: z.ZodOptional<z.ZodAny>;
-        }, "strip", z.ZodTypeAny, {
-            storage?: any;
-            scopeId?: any;
-        }, {
-            storage?: any;
-            scopeId?: any;
-        }>>;
-    }, "strip", z.ZodTypeAny, {
-        mode?: "ner" | "classifier" | undefined;
-        reversible?: boolean | undefined;
-        model?: string | undefined;
-        vault?: {
-            storage?: any;
-            scopeId?: any;
-        } | undefined;
-    }, {
-        mode?: "ner" | "classifier" | undefined;
-        reversible?: boolean | undefined;
-        model?: string | undefined;
-        vault?: {
-            storage?: any;
-            scopeId?: any;
-        } | undefined;
-    }>>;
-    logging: z.ZodOptional<z.ZodObject<{
-        enabled: z.ZodOptional<z.ZodBoolean>;
-        level: z.ZodOptional<z.ZodEnum<["debug", "info", "warn", "error"]>>;
-        serviceName: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        enabled?: boolean | undefined;
-        level?: "debug" | "info" | "warn" | "error" | undefined;
-        serviceName?: string | undefined;
-    }, {
-        enabled?: boolean | undefined;
-        level?: "debug" | "info" | "warn" | "error" | undefined;
-        serviceName?: string | undefined;
-    }>>;
-    models: z.ZodOptional<z.ZodObject<{
-        extractor: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        extractor?: string | undefined;
-    }, {
-        extractor?: string | undefined;
-    }>>;
-}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    intent: z.ZodOptional<z.ZodObject<{
-        mode: z.ZodOptional<z.ZodString>;
-        allowedIntent: z.ZodOptional<z.ZodString>;
-        semantic: z.ZodObject<{
-            threshold: z.ZodOptional<z.ZodNumber>;
-            intents: z.ZodRecord<z.ZodString, z.ZodString>;
-        }, "strip", z.ZodTypeAny, {
-            intents: Record<string, string>;
-            threshold?: number | undefined;
-        }, {
-            intents: Record<string, string>;
-            threshold?: number | undefined;
-        }>;
-    }, "strip", z.ZodTypeAny, {
-        semantic: {
-            intents: Record<string, string>;
-            threshold?: number | undefined;
-        };
-        mode?: string | undefined;
-        allowedIntent?: string | undefined;
-    }, {
-        semantic: {
+export type GuardConfig = {
+    intent?: {
+        mode?: string;
+        allowedIntent?: string;
+        semantic?: {
+            threshold?: number;
             intents: Record<string, string>;
-            threshold?: number | undefined;
         };
-        mode?: string | undefined;
-        allowedIntent?: string | undefined;
-    }>>;
-    pii: z.ZodOptional<z.ZodObject<{
-        reversible: z.ZodOptional<z.ZodBoolean>;
-        model: z.ZodOptional<z.ZodString>;
-        mode: z.ZodOptional<z.ZodEnum<["ner", "classifier"]>>;
-        vault: z.ZodOptional<z.ZodObject<{
-            storage: z.ZodOptional<z.ZodAny>;
-            scopeId: z.ZodOptional<z.ZodAny>;
-        }, "strip", z.ZodTypeAny, {
-            storage?: any;
-            scopeId?: any;
-        }, {
-            storage?: any;
-            scopeId?: any;
-        }>>;
-    }, "strip", z.ZodTypeAny, {
-        mode?: "ner" | "classifier" | undefined;
-        reversible?: boolean | undefined;
-        model?: string | undefined;
-        vault?: {
-            storage?: any;
-            scopeId?: any;
-        } | undefined;
-    }, {
-        mode?: "ner" | "classifier" | undefined;
-        reversible?: boolean | undefined;
-        model?: string | undefined;
-        vault?: {
-            storage?: any;
-            scopeId?: any;
-        } | undefined;
-    }>>;
-    logging: z.ZodOptional<z.ZodObject<{
-        enabled: z.ZodOptional<z.ZodBoolean>;
-        level: z.ZodOptional<z.ZodEnum<["debug", "info", "warn", "error"]>>;
-        serviceName: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        enabled?: boolean | undefined;
-        level?: "debug" | "info" | "warn" | "error" | undefined;
-        serviceName?: string | undefined;
-    }, {
-        enabled?: boolean | undefined;
-        level?: "debug" | "info" | "warn" | "error" | undefined;
-        serviceName?: string | undefined;
-    }>>;
-    models: z.ZodOptional<z.ZodObject<{
-        extractor: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        extractor?: string | undefined;
-    }, {
-        extractor?: string | undefined;
-    }>>;
-}, z.ZodTypeAny, "passthrough">>;
-type GuardConfig = z.infer<typeof guardConfigSchema> & {
+    };
     pii?: {
+        reversible?: boolean;
+        model?: string;
+        mode?: 'ner' | 'classifier';
         vault?: {
             storage?: PiiVaultStorage;
             scopeId?: string | ((req: any, ctx: any) => string | undefined);
         };
     };
+    logging?: {
+        enabled?: boolean;
+        level?: LogSeverity;
+        serviceName?: string;
+    };
+    models?: {
+        extractor?: string;
+    };
+    [key: string]: any;
 };
+type LogSeverity = 'debug' | 'info' | 'warn' | 'error';
 export declare const guardMiddleware: import("genkit").GenerateMiddleware<z.ZodObject<{
     intent: z.ZodOptional<z.ZodObject<{
         mode: z.ZodOptional<z.ZodString>;

package/dist/pii/storage.d.ts

@@ -8,6 +8,34 @@ export interface PiiVaultStorage {
     set(scopeId: string, token: string, value: string): void | Promise<void>;
     entries(scopeId: string): PiiVaultEntry[] | Promise<PiiVaultEntry[]>;
 }
+export type PiiVaultStorageAdapter = {
+    get: PiiVaultStorage['get'];
+    getByToken?: PiiVaultStorage['getByToken'];
+    set: PiiVaultStorage['set'];
+    entries: PiiVaultStorage['entries'];
+};
+export declare function createPiiVaultStorage(adapter: PiiVaultStorageAdapter): PiiVaultStorage;
+export type RedisPiiVaultClient = {
+    hGet?: (key: string, field: string) => Promise<string | null | undefined>;
+    hSet?: (key: string, field: string, value: string) => Promise<unknown>;
+    hGetAll?: (key: string) => Promise<Record<string, string>>;
+    hget?: (key: string, field: string) => Promise<string | null | undefined>;
+    hset?: (key: string, field: string, value: string) => Promise<unknown>;
+    hgetall?: (key: string) => Promise<Record<string, string>>;
+    expire?: (key: string, seconds: number) => Promise<unknown>;
+};
+export type RedisPiiVaultStorageOptions = {
+    keyPrefix?: string;
+    tokenIndexKey?: string;
+    /** Expire Redis vault keys after this many seconds. Omit to keep them indefinitely. */
+    ttlSeconds?: number;
+    /**
+     * Keep a process-local mirror and use it when a Redis operation fails.
+     * Disabled by default so Redis failures remain visible to callers.
+     */
+    fallbackToMemory?: boolean;
+};
+export declare function createRedisPiiVaultStorage(redis: RedisPiiVaultClient, options?: RedisPiiVaultStorageOptions): PiiVaultStorage;
 export declare class InMemoryPiiVaultStorage implements PiiVaultStorage {
     private scopes;
     private tokenIndex;

package/dist/pii/storage.js

@@ -1,3 +1,98 @@
+export function createPiiVaultStorage(adapter) {
+    return adapter;
+}
+export function createRedisPiiVaultStorage(redis, options = {}) {
+    const keyPrefix = options.keyPrefix ?? 'genkit-guard:pii';
+    const tokenIndexKey = options.tokenIndexKey ?? `${keyPrefix}:tokens`;
+    const ttlSeconds = options.ttlSeconds;
+    if (ttlSeconds !== undefined && (!Number.isInteger(ttlSeconds) || ttlSeconds <= 0)) {
+        throw new Error('Redis PII vault ttlSeconds must be a positive integer.');
+    }
+    if (ttlSeconds !== undefined && !redis.expire) {
+        throw new Error('Redis PII vault ttlSeconds requires an expire method on the Redis client.');
+    }
+    const hGet = redis.hGet?.bind(redis) ?? redis.hget?.bind(redis);
+    const hSet = redis.hSet?.bind(redis) ?? redis.hset?.bind(redis);
+    const hGetAll = redis.hGetAll?.bind(redis) ?? redis.hgetall?.bind(redis);
+    if (!hGet || !hSet || !hGetAll) {
+        throw new Error('Redis PII vault storage requires hGet/hSet/hGetAll or hget/hset/hgetall methods.');
+    }
+    const scopeKey = (scopeId) => `${keyPrefix}:scope:${scopeId}`;
+    const fallback = options.fallbackToMemory ? new ExpiringInMemoryPiiVaultStorage(ttlSeconds) : undefined;
+    async function maybeExpire(key) {
+        if (ttlSeconds !== undefined) {
+            await redis.expire(key, ttlSeconds);
+        }
+    }
+    async function withFallback(redisOperation, memoryOperation) {
+        try {
+            return await redisOperation();
+        }
+        catch (error) {
+            if (!fallback)
+                throw error;
+            return memoryOperation();
+        }
+    }
+    return createPiiVaultStorage({
+        async get(scopeId, token) {
+            return withFallback(async () => (await hGet(scopeKey(scopeId), token)) ?? undefined, () => fallback.get(scopeId, token));
+        },
+        async getByToken(token) {
+            return withFallback(async () => (await hGet(tokenIndexKey, token)) ?? undefined, () => fallback.getByToken(token));
+        },
+        async set(scopeId, token, value) {
+            const scopedKey = scopeKey(scopeId);
+            // Warm the opt-in fallback on every write so data written before an outage is available.
+            await fallback?.set(scopeId, token, value);
+            await withFallback(async () => {
+                await hSet(scopedKey, token, value);
+                await hSet(tokenIndexKey, token, value);
+                await maybeExpire(scopedKey);
+                await maybeExpire(tokenIndexKey);
+            }, () => undefined);
+        },
+        async entries(scopeId) {
+            return withFallback(async () => {
+                const values = await hGetAll(scopeKey(scopeId));
+                return Object.entries(values).map(([token, value]) => ({ token, value }));
+            }, () => fallback.entries(scopeId));
+        },
+    });
+}
+class ExpiringInMemoryPiiVaultStorage {
+    ttlSeconds;
+    storage = new InMemoryPiiVaultStorage();
+    scopeExpiresAt = new Map();
+    tokenIndexExpiresAt;
+    constructor(ttlSeconds) {
+        this.ttlSeconds = ttlSeconds;
+    }
+    get(scopeId, token) {
+        return this.isScopeExpired(scopeId) ? undefined : this.storage.get(scopeId, token);
+    }
+    getByToken(token) {
+        return this.isTokenIndexExpired() ? undefined : this.storage.getByToken(token);
+    }
+    set(scopeId, token, value) {
+        this.storage.set(scopeId, token, value);
+        if (this.ttlSeconds !== undefined) {
+            const expiry = Date.now() + this.ttlSeconds * 1_000;
+            this.scopeExpiresAt.set(scopeId, expiry);
+            this.tokenIndexExpiresAt = expiry;
+        }
+    }
+    entries(scopeId) {
+        return this.isScopeExpired(scopeId) ? [] : this.storage.entries(scopeId);
+    }
+    isScopeExpired(scopeId) {
+        const expiry = this.scopeExpiresAt.get(scopeId);
+        return expiry !== undefined && expiry <= Date.now();
+    }
+    isTokenIndexExpired() {
+        return this.tokenIndexExpiresAt !== undefined && this.tokenIndexExpiresAt <= Date.now();
+    }
+}
 export class InMemoryPiiVaultStorage {
     scopes = new Map();
     tokenIndex = new Map();

package/package.json

@@ -22,7 +22,7 @@
     "huggingface"
   ],
   "license": "Apache-2.0",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "type": "module",
   "exports": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -32,12 +32,16 @@
     "scripts/",
     "dist/"
   ],
-  "scripts": {
-    "prepare-models": "node scripts/download-model.js",
-    "build": "tsc",
-    "test:concurrency": "npm run build && node scripts/test-concurrent-vault.js",
-    "prepublishOnly": "npm run build"
-  },
+  "scripts": {
+    "prepare-models": "node scripts/download-model.js",
+    "build": "tsc",
+    "test": "npm run test:types && npm run test:storage && npm run test:concurrency",
+    "test:types": "tsc --noEmit --ignoreConfig --module NodeNext --moduleResolution NodeNext --target ESNext --strict --skipLibCheck scripts/test-types.ts",
+    "test:storage": "npm run build && node scripts/test-storage.js",
+    "test:concurrency": "npm run build && node scripts/test-concurrent-vault.js",
+    "test:redis": "npm run build && node scripts/test-redis-vault.js",
+    "prepublishOnly": "npm run build"
+  },
   "dependencies": {
     "@huggingface/transformers": "^4.2.0",
     "zod": "^4.4.3"

package/scripts/test-redis-vault.js

@@ -0,0 +1,153 @@
+import assert from 'node:assert/strict';
+import net from 'node:net';
+import { createRedisPiiVaultStorage } from '../dist/index.js';
+import { PiiTokenizer } from '../dist/pii/tokenizer.js';
+
+class RespRedisClient {
+  constructor(host = '127.0.0.1', port = 6379) {
+    this.host = host;
+    this.port = port;
+  }
+
+  async hGet(key, field) {
+    return this.command('HGET', key, field);
+  }
+
+  async hSet(key, field, value) {
+    return this.command('HSET', key, field, value);
+  }
+
+  async hGetAll(key) {
+    const values = await this.command('HGETALL', key);
+    const out = {};
+    for (let i = 0; i < values.length; i += 2) {
+      out[values[i]] = values[i + 1];
+    }
+    return out;
+  }
+
+  async expire(key, seconds) {
+    return this.command('EXPIRE', key, String(seconds));
+  }
+
+  async del(key) {
+    return this.command('DEL', key);
+  }
+
+  command(...parts) {
+    return new Promise((resolve, reject) => {
+      const socket = net.createConnection({ host: this.host, port: this.port });
+      let buffer = Buffer.alloc(0);
+
+      socket.setTimeout(3000);
+      socket.once('error', reject);
+      socket.once('timeout', () => {
+        socket.destroy();
+        reject(new Error(`Timed out connecting to Redis at ${this.host}:${this.port}`));
+      });
+      socket.once('connect', () => {
+        socket.write(encodeCommand(parts));
+      });
+      socket.on('data', (chunk) => {
+        buffer = Buffer.concat([buffer, chunk]);
+        try {
+          const [value, offset] = parseResp(buffer, 0);
+          if (offset <= buffer.length) {
+            socket.end();
+            resolve(value);
+          }
+        } catch (error) {
+          if (error.message !== 'Incomplete RESP response') {
+            socket.destroy();
+            reject(error);
+          }
+        }
+      });
+    });
+  }
+}
+
+const redis = new RespRedisClient(process.env.REDIS_HOST ?? '127.0.0.1', Number(process.env.REDIS_PORT ?? 6379));
+const keyPrefix = `genkit-guard:test:${Date.now()}`;
+const storage = createRedisPiiVaultStorage(redis, { keyPrefix, ttlSeconds: 60 });
+
+try {
+  const userA = new PiiTokenizer({ scopeId: 'tenant:userA', storage });
+  const userB = new PiiTokenizer({ scopeId: 'tenant:userB', storage });
+
+  const maskedA = await userA.mask('Email alice@example.com', [
+    { type: 'EMAIL', value: 'alice@example.com' },
+  ]);
+  const maskedB = await userB.mask('Email bob@example.com', [
+    { type: 'EMAIL', value: 'bob@example.com' },
+  ]);
+
+  assert.equal(await userA.unmask(maskedA.maskedText), 'Email alice@example.com');
+  assert.equal(await userB.unmask(maskedB.maskedText), 'Email bob@example.com');
+  assert.equal(await userA.unmask(maskedB.maskedText), maskedB.maskedText);
+
+  const laterPass = new PiiTokenizer({ scopeId: 'tenant:userA:later', storage });
+  await laterPass.importTokens(maskedA.maskedText);
+  assert.equal(await laterPass.unmask(maskedA.maskedText), 'Email alice@example.com');
+
+  console.log('Live Redis PII vault test passed.');
+} finally {
+  await redis.del(`${keyPrefix}:tokens`).catch(() => {});
+  await redis.del(`${keyPrefix}:scope:tenant:userA`).catch(() => {});
+  await redis.del(`${keyPrefix}:scope:tenant:userB`).catch(() => {});
+  await redis.del(`${keyPrefix}:scope:tenant:userA:later`).catch(() => {});
+}
+
+function encodeCommand(parts) {
+  return `*${parts.length}\r\n${parts.map((part) => {
+    const value = String(part);
+    return `$${Buffer.byteLength(value)}\r\n${value}\r\n`;
+  }).join('')}`;
+}
+
+function parseResp(buffer, offset) {
+  if (offset >= buffer.length) {
+    throw new Error('Incomplete RESP response');
+  }
+
+  const prefix = String.fromCharCode(buffer[offset]);
+  if (prefix === '+') return parseSimple(buffer, offset);
+  if (prefix === '-') {
+    const [message] = parseSimple(buffer, offset);
+    throw new Error(message);
+  }
+  if (prefix === ':') {
+    const [value, next] = parseSimple(buffer, offset);
+    return [Number(value), next];
+  }
+  if (prefix === '$') return parseBulk(buffer, offset);
+  if (prefix === '*') return parseArray(buffer, offset);
+  throw new Error(`Unsupported RESP prefix: ${prefix}`);
+}
+
+function parseSimple(buffer, offset) {
+  const end = buffer.indexOf('\r\n', offset);
+  if (end === -1) throw new Error('Incomplete RESP response');
+  return [buffer.toString('utf8', offset + 1, end), end + 2];
+}
+
+function parseBulk(buffer, offset) {
+  const [lengthText, valueStart] = parseSimple(buffer, offset);
+  const length = Number(lengthText);
+  if (length === -1) return [null, valueStart];
+  const valueEnd = valueStart + length;
+  if (buffer.length < valueEnd + 2) throw new Error('Incomplete RESP response');
+  return [buffer.toString('utf8', valueStart, valueEnd), valueEnd + 2];
+}
+
+function parseArray(buffer, offset) {
+  const [lengthText, start] = parseSimple(buffer, offset);
+  const values = [];
+  let next = start;
+  for (let i = 0; i < Number(lengthText); i++) {
+    const [value, newOffset] = parseResp(buffer, next);
+    values.push(value);
+    next = newOffset;
+  }
+  return [values, next];
+}

package/scripts/test-storage.js

@@ -0,0 +1,137 @@
+import assert from 'node:assert/strict';
+import {
+  createPiiVaultStorage,
+  createRedisPiiVaultStorage,
+  InMemoryPiiVaultStorage,
+} from '../dist/index.js';
+import { PiiTokenizer } from '../dist/pii/tokenizer.js';
+
+class FakeRedis {
+  hashes = new Map();
+  expirations = new Map();
+
+  async hGet(key, field) {
+    return this.hashes.get(key)?.[field] ?? null;
+  }
+
+  async hSet(key, field, value) {
+    const hash = this.hashes.get(key) ?? {};
+    hash[field] = value;
+    this.hashes.set(key, hash);
+  }
+
+  async hGetAll(key) {
+    return this.hashes.get(key) ?? {};
+  }
+
+  async expire(key, seconds) {
+    this.expirations.set(key, seconds);
+  }
+}
+
+const memory = new InMemoryPiiVaultStorage();
+await memory.set('scope-a', '[[EMAIL_token_0]]', 'a@example.com');
+assert.equal(await memory.get('scope-a', '[[EMAIL_token_0]]'), 'a@example.com');
+assert.equal(await memory.get('scope-b', '[[EMAIL_token_0]]'), undefined);
+assert.equal(await memory.getByToken('[[EMAIL_token_0]]'), 'a@example.com');
+
+const custom = createPiiVaultStorage({
+  async get(scopeId, token) {
+    return scopeId === 'custom' && token === '[[EMAIL_custom_0]]' ? 'custom@example.com' : undefined;
+  },
+  async set() {},
+  async entries(scopeId) {
+    return scopeId === 'custom'
+      ? [{ token: '[[EMAIL_custom_0]]', value: 'custom@example.com' }]
+      : [];
+  },
+});
+
+const customTokenizer = new PiiTokenizer({ scopeId: 'custom', storage: custom });
+assert.equal(await customTokenizer.unmask('Hi [[EMAIL_custom_0]]'), 'Hi custom@example.com');
+
+const redis = new FakeRedis();
+const redisStorage = createRedisPiiVaultStorage(redis, {
+  keyPrefix: 'test:pii',
+  ttlSeconds: 60,
+});
+
+const userATokenizer = new PiiTokenizer({ scopeId: 'tenant:userA', storage: redisStorage });
+const userBTokenizer = new PiiTokenizer({ scopeId: 'tenant:userB', storage: redisStorage });
+
+const userAMasked = await userATokenizer.mask('Email alice@example.com', [
+  { type: 'EMAIL', value: 'alice@example.com' },
+]);
+const userBMasked = await userBTokenizer.mask('Email bob@example.com', [
+  { type: 'EMAIL', value: 'bob@example.com' },
+]);
+
+assert.notEqual(userAMasked.maskedText, userBMasked.maskedText);
+assert.equal(await userATokenizer.unmask(userAMasked.maskedText), 'Email alice@example.com');
+assert.equal(await userBTokenizer.unmask(userBMasked.maskedText), 'Email bob@example.com');
+assert.equal(await userATokenizer.unmask(userBMasked.maskedText), userBMasked.maskedText);
+
+const laterPassTokenizer = new PiiTokenizer({ scopeId: 'tenant:userA:later', storage: redisStorage });
+await laterPassTokenizer.importTokens(userAMasked.maskedText);
+assert.equal(await laterPassTokenizer.unmask(userAMasked.maskedText), 'Email alice@example.com');
+
+assert.equal(redis.expirations.get('test:pii:scope:tenant:userA'), 60);
+assert.equal(redis.expirations.get('test:pii:tokens'), 60);
+
+class FailingRedis extends FakeRedis {
+  failed = false;
+
+  fail() {
+    this.failed = true;
+  }
+
+  async hGet(key, field) {
+    if (this.failed) throw new Error('Redis unavailable');
+    return super.hGet(key, field);
+  }
+
+  async hSet(key, field, value) {
+    if (this.failed) throw new Error('Redis unavailable');
+    return super.hSet(key, field, value);
+  }
+
+  async hGetAll(key) {
+    if (this.failed) throw new Error('Redis unavailable');
+    return super.hGetAll(key);
+  }
+}
+
+const failingRedis = new FailingRedis();
+const resilientStorage = createRedisPiiVaultStorage(failingRedis, { fallbackToMemory: true });
+await resilientStorage.set('resilient-scope', '[[EMAIL_resilient_0]]', 'safe@example.com');
+failingRedis.fail();
+assert.equal(
+  await resilientStorage.get('resilient-scope', '[[EMAIL_resilient_0]]'),
+  'safe@example.com'
+);
+assert.equal(await resilientStorage.getByToken('[[EMAIL_resilient_0]]'), 'safe@example.com');
+assert.deepEqual(await resilientStorage.entries('resilient-scope'), [
+  { token: '[[EMAIL_resilient_0]]', value: 'safe@example.com' },
+]);
+await resilientStorage.set('resilient-scope', '[[PHONE_resilient_1]]', '0400000000');
+assert.equal(await resilientStorage.getByToken('[[PHONE_resilient_1]]'), '0400000000');
+
+const strictRedis = new FailingRedis();
+const strictStorage = createRedisPiiVaultStorage(strictRedis);
+strictRedis.fail();
+await assert.rejects(() => strictStorage.get('scope', 'token'), /Redis unavailable/);
+
+assert.throws(
+  () => createRedisPiiVaultStorage(new FakeRedis(), { ttlSeconds: 0 }),
+  /positive integer/
+);
+assert.throws(
+  () =>
+    createRedisPiiVaultStorage(
+      { hGet: async () => null, hSet: async () => undefined, hGetAll: async () => ({}) },
+      { ttlSeconds: 60 }
+    ),
+  /requires an expire method/
+);
+
+console.log('PII vault storage tests passed.');

package/scripts/test-types.ts

@@ -0,0 +1,21 @@
+import { guard, createRedisPiiVaultStorage, type RedisPiiVaultClient } from '../src/index.js';
+
+const redis: RedisPiiVaultClient = {
+  async hGet() {
+    return undefined;
+  },
+  async hSet() {},
+  async hGetAll() {
+    return {};
+  },
+};
+
+guard({
+  pii: {
+    reversible: true,
+    vault: {
+      storage: createRedisPiiVaultStorage(redis),
+      scopeId: (req: any, ctx: any) => ctx?.auth?.sessionId ?? req?.metadata?.requestId,
+    },
+  },
+});