@intflows/genkit-guard 0.0.9 → 0.0.11

package/README.md

@@ -1,7 +1,5 @@
 # **@intflows/genkit-guard** 
 
-#### _This version uses OpenAI/privacy-filter instead of bert-base-NER_
-
 ### **Lightweight Intent, PII, and Safety Guardrails for Genkit**
 
 `@intflows/genkit-guard` provides a modular guardrail layer for Genkit flows.  
@@ -114,6 +112,29 @@ const response = await ai.generate({
 
 ![Image showing PII data masked ](./MaskedPII.png)
 
+---
+## Example
+
+An example genkit flow is present in `example` directory.
+
+```bash
+git clone https://github.com/IntFlows/genkit-guard.git
+cd genkit-guard/example
+npm install
+node node_modules/@intflows/genkit-guard/scripts/download-model.js
+npx tsx src/index.ts
+```
+
+Or you can run the flow with genkit dev UI
+
+```bash
+git clone https://github.com/IntFlows/genkit-guard.git
+cd genkit-guard/example
+npm install
+node node_modules/@intflows/genkit-guard/scripts/download-model.js
+genkit start -- npx tsx src/index.ts
+```
+
 ---
 
 ## 🧠 How It Works
@@ -177,6 +198,46 @@ pii: {
 }
 ```
 
+### **PII Vault Isolation and External Storage**
+
+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]]"
+```
+
+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. Redis clients can be passed through the built-in helper:
+
+```ts
+import { createClient } from "redis";
+import { guard, createRedisPiiVaultStorage } from "@intflows/genkit-guard";
+
+const redis = createClient({ url: "redis://localhost:6379" });
+await redis.connect();
+
+guard({
+  pii: {
+    reversible: true,
+    vault: {
+      storage: createRedisPiiVaultStorage(redis, {
+        keyPrefix: "my-app:pii",
+        ttlSeconds: 3600
+      }),
+      scopeId: (req, ctx) => ctx?.auth?.sessionId ?? req?.metadata?.requestId
+    }
+  }
+});
+```
+
+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)
+
 ---
 
 ## 🛡️ Why This Library Exists

package/dist/index.d.ts

@@ -1,4 +1,7 @@
-export { guard } from './middleware/middleware.js';
+export { guard, guardAction, guardMiddleware, guardPlugin } from './middleware/middleware.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,12 +1,31 @@
 import { ModelSingleton } from './util/singleton.js';
 // export { intentGuard, piiGuard  } from './middleware/middleware.js';
-export { guard } from './middleware/middleware.js';
+export { guard, guardAction, guardMiddleware, guardPlugin } from './middleware/middleware.js';
+export { InMemoryPiiVaultStorage, createPiiVaultStorage, createRedisPiiVaultStorage, defaultPiiVaultStorage, } from './pii/storage.js';
 export * from './core/types.js';
+function logGuardEvent(eventName, body, attributes = {}) {
+    console.log(JSON.stringify({
+        timestamp: new Date().toISOString(),
+        severityText: 'INFO',
+        severityNumber: 9,
+        body,
+        resource: {
+            attributes: {
+                'service.name': '@intflows/genkit-guard',
+            },
+        },
+        attributes: {
+            'event.name': eventName,
+            'code.namespace': 'genkit-guard',
+            ...attributes,
+        },
+    }));
+}
 /**
  * Pre-load the model to avoid cold-start delay on first user request.
  */
 export async function initGuard(config) {
-    console.log('[Guard] Loading local models...');
+    logGuardEvent('guard.models.loading', 'Loading local guard models');
     const extractorModel = config?.models?.extractor ?? 'Xenova/all-MiniLM-L6-v2';
     const piiModel = config?.pii?.model;
     const piiMode = config?.pii?.mode ?? 'ner';
@@ -18,5 +37,7 @@ export async function initGuard(config) {
         tasks.push(ModelSingleton.getPIIClassifier(piiModel ?? 'openai/privacy-filter'));
     }
     await Promise.all(tasks);
-    console.log('[Guard] Models loaded');
+    logGuardEvent('guard.models.loaded', 'Local guard models loaded', {
+        piiMode,
+    });
 }

package/dist/middleware/middleware.d.ts

@@ -1,54 +1,35 @@
 import { z } from 'genkit';
-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;
-        }, {
+import { type PiiVaultStorage } from '../pii/storage.js';
+export type GuardConfig = {
+    intent?: {
+        mode?: string;
+        allowedIntent?: string;
+        semantic?: {
+            threshold?: number;
             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;
+    };
+    pii?: {
+        reversible?: boolean;
+        model?: string;
+        mode?: 'ner' | 'classifier';
+        vault?: {
+            storage?: PiiVaultStorage;
+            scopeId?: string | ((req: any, ctx: any) => string | 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"]>>;
-    }, "strip", z.ZodTypeAny, {
-        mode?: "ner" | "classifier" | undefined;
-        reversible?: boolean | undefined;
-        model?: string | undefined;
-    }, {
-        mode?: "ner" | "classifier" | undefined;
-        reversible?: boolean | undefined;
-        model?: 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<{
+    };
+    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>;
         allowedIntent: z.ZodOptional<z.ZodString>;
@@ -81,113 +62,45 @@ declare const guardConfigSchema: z.ZodObject<{
         reversible: z.ZodOptional<z.ZodBoolean>;
         model: z.ZodOptional<z.ZodString>;
         mode: z.ZodOptional<z.ZodEnum<["ner", "classifier"]>>;
-    }, "strip", z.ZodTypeAny, {
-        mode?: "ner" | "classifier" | undefined;
-        reversible?: boolean | undefined;
-        model?: string | undefined;
-    }, {
-        mode?: "ner" | "classifier" | undefined;
-        reversible?: boolean | undefined;
-        model?: 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>;
+        vault: z.ZodOptional<z.ZodObject<{
+            storage: z.ZodOptional<z.ZodAny>;
+            scopeId: z.ZodOptional<z.ZodAny>;
         }, "strip", z.ZodTypeAny, {
-            intents: Record<string, string>;
-            threshold?: number | undefined;
+            storage?: any;
+            scopeId?: any;
         }, {
-            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"]>>;
+            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;
     }>>;
-    models: z.ZodOptional<z.ZodObject<{
-        extractor: z.ZodOptional<z.ZodString>;
+    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, {
-        extractor?: string | undefined;
+        enabled?: boolean | undefined;
+        level?: "debug" | "info" | "warn" | "error" | undefined;
+        serviceName?: string | undefined;
     }, {
-        extractor?: string | undefined;
-    }>>;
-}, z.ZodTypeAny, "passthrough">>;
-export declare const guardMiddleware: import("genkit").GenerateMiddleware<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"]>>;
-    }, "strip", z.ZodTypeAny, {
-        mode?: "ner" | "classifier" | undefined;
-        reversible?: boolean | undefined;
-        model?: string | undefined;
-    }, {
-        mode?: "ner" | "classifier" | undefined;
-        reversible?: boolean | undefined;
-        model?: string | undefined;
+        enabled?: boolean | undefined;
+        level?: "debug" | "info" | "warn" | "error" | undefined;
+        serviceName?: string | undefined;
     }>>;
     models: z.ZodOptional<z.ZodObject<{
         extractor: z.ZodOptional<z.ZodString>;
@@ -229,14 +142,45 @@ export declare const guardMiddleware: import("genkit").GenerateMiddleware<z.ZodO
         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>;
@@ -278,14 +222,45 @@ export declare const guardMiddleware: import("genkit").GenerateMiddleware<z.ZodO
         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>;
@@ -296,5 +271,6 @@ export declare const guardMiddleware: import("genkit").GenerateMiddleware<z.ZodO
     }>>;
 }, z.ZodTypeAny, "passthrough">>, void>;
 export declare const guardPlugin: (pluginOptions: void) => import("@genkit-ai/ai").GenkitPluginV2;
-export declare function guard(config?: z.infer<typeof guardConfigSchema>): (req: any, ctxOrNext: any, maybeNext?: any) => Promise<any>;
+export declare function guard(config?: GuardConfig): (req: any, ctxOrNext: any, maybeNext?: any) => Promise<any>;
+export declare const guardAction: typeof guard;
 export {};