@datafog/fogclaw 0.1.4 → 0.1.6

package/src/index.ts

@@ -1,7 +1,14 @@
 import { Scanner } from "./scanner.js";
 import { redact } from "./redactor.js";
 import { loadConfig } from "./config.js";
-import type { GuardrailAction } from "./types.js";
+import type {
+  Entity,
+  FogClawConfig,
+  GuardrailAction,
+  RedactResult,
+  RedactStrategy,
+  ScanResult,
+} from "./types.js";
 
 export { Scanner } from "./scanner.js";
 export { redact } from "./redactor.js";
@@ -15,12 +22,84 @@ export type {
   GuardrailAction,
 } from "./types.js";
 
+function resolveAction(entity: Entity, config: FogClawConfig): GuardrailAction {
+  return config.entityActions[entity.label] ?? config.guardrail_mode;
+}
+
+function buildGuardrailPlan(entities: Entity[], config: FogClawConfig) {
+  const blocked: Entity[] = [];
+  const warned: Entity[] = [];
+  const redacted: Entity[] = [];
+
+  for (const entity of entities) {
+    const action = resolveAction(entity, config);
+    if (action === "block") blocked.push(entity);
+    else if (action === "warn") warned.push(entity);
+    else redacted.push(entity);
+  }
+
+  return { blocked, warned, redacted };
+}
+
+function planToSummary(plan: ReturnType<typeof buildGuardrailPlan>): {
+  total: number;
+  blocked: number;
+  warned: number;
+  redacted: number;
+  labels: {
+    blocked: string[];
+    warned: string[];
+    redacted: string[];
+  };
+} {
+  return {
+    total: plan.blocked.length + plan.warned.length + plan.redacted.length,
+    blocked: plan.blocked.length,
+    warned: plan.warned.length,
+    redacted: plan.redacted.length,
+    labels: {
+      blocked: [...new Set(plan.blocked.map((entity) => entity.label))],
+      warned: [...new Set(plan.warned.map((entity) => entity.label))],
+      redacted: [...new Set(plan.redacted.map((entity) => entity.label))],
+    },
+  };
+}
+
+function buildGuardrailContext(plan: ReturnType<typeof buildGuardrailPlan>, config: FogClawConfig): string[] {
+  const contextParts: string[] = [];
+
+  if (plan.blocked.length > 0) {
+    const types = [...new Set(plan.blocked.map((entity) => entity.label))].join(", ");
+    contextParts.push(
+      `[FOGCLAW GUARDRAIL — BLOCKED] The user's message contains sensitive information (${types}). ` +
+        `Do NOT process or repeat this information. Ask the user to rephrase without sensitive data.`,
+    );
+  }
+
+  if (plan.warned.length > 0) {
+    const types = [...new Set(plan.warned.map((entity) => entity.label))].join(", ");
+    contextParts.push(
+      `[FOGCLAW NOTICE] PII detected in user message: ${types}. Handle with care.`,
+    );
+  }
+
+  if (plan.redacted.length > 0) {
+    const labels = [...new Set(plan.redacted.map((entity) => entity.label))].join(", ");
+    contextParts.push(
+      `[FOGCLAW REDACTED] ${plan.redacted.length} entity(ies) prepared for ${config.redactStrategy} redaction (${labels}).`,
+    );
+  }
+
+  return contextParts;
+}
+
 /**
  * OpenClaw plugin definition.
  *
  * Registers:
  * - `before_agent_start` hook for automatic PII guardrail
  * - `fogclaw_scan` tool for on-demand entity detection
+ * - `fogclaw_preview` tool for dry-run policy simulation
  * - `fogclaw_redact` tool for on-demand redaction
  */
 const fogclaw = {
@@ -48,47 +127,35 @@ const fogclaw = {
       const message = event.prompt ?? "";
       if (!message) return;
 
-      const result = await scanner.scan(message);
-
+      const result: ScanResult = await scanner.scan(message);
       if (result.entities.length === 0) return;
 
-      // Classify entities by their configured action
-      const blocked: typeof result.entities = [];
-      const warned: typeof result.entities = [];
-      const toRedact: typeof result.entities = [];
-
-      for (const entity of result.entities) {
-        const action: GuardrailAction =
-          config.entityActions[entity.label] ?? config.guardrail_mode;
-        if (action === "block") blocked.push(entity);
-        else if (action === "warn") warned.push(entity);
-        else if (action === "redact") toRedact.push(entity);
-      }
-
-      const contextParts: string[] = [];
+      const plan = buildGuardrailPlan(result.entities, config);
+      const contextParts = buildGuardrailContext(plan, config);
 
-      // "block" — inject a strong instruction to refuse
-      if (blocked.length > 0) {
-        const types = [...new Set(blocked.map((e) => e.label))].join(", ");
-        contextParts.push(
-          `[FOGCLAW GUARDRAIL — BLOCKED] The user's message contains sensitive information (${types}). ` +
-          `Do NOT process or repeat this information. Ask the user to rephrase without sensitive data.`,
+      if (config.auditEnabled) {
+        const summary = planToSummary(plan);
+        api.logger?.info(
+          `[FOGCLAW AUDIT] guardrail_scan ${JSON.stringify({
+            totalEntities: summary.total,
+            blocked: summary.blocked,
+            warned: summary.warned,
+            redacted: summary.redacted,
+            blockedLabels: summary.labels.blocked,
+            warnedLabels: summary.labels.warned,
+            redactedLabels: summary.labels.redacted,
+          })}`,
         );
       }
 
-      // "warn" — inject a warning notice
-      if (warned.length > 0) {
-        const types = [...new Set(warned.map((e) => e.label))].join(", ");
-        contextParts.push(
-          `[FOGCLAW NOTICE] PII detected in user message: ${types}. Handle with care.`,
+      if (plan.redacted.length > 0) {
+        const redactedResult: RedactResult = redact(
+          message,
+          plan.redacted,
+          config.redactStrategy,
         );
-      }
-
-      // "redact" — replace PII with tokens
-      if (toRedact.length > 0) {
-        const redacted = redact(message, toRedact, config.redactStrategy);
         contextParts.push(
-          `[FOGCLAW REDACTED] The following is the user's message with PII redacted:\n${redacted.redacted_text}`,
+          `[FOGCLAW REDACTED] The following is the user's message with PII redacted:\n${redactedResult.redacted_text}`,
         );
       }
 
@@ -138,7 +205,7 @@ const fogclaw = {
                     count: result.entities.length,
                     summary:
                       result.entities.length > 0
-                        ? `Found ${result.entities.length} entities: ${[...new Set(result.entities.map((e) => e.label))].join(", ")}`
+                        ? `Found ${result.entities.length} entities: ${[...new Set(result.entities.map((entity) => entity.label))].join(", ")}`
                         : "No entities detected",
                   },
                   null,
@@ -151,6 +218,88 @@ const fogclaw = {
       }
     );
 
+    // --- TOOL: Policy preview ---
+    api.registerTool(
+      {
+        name: "fogclaw_preview",
+        id: "fogclaw_preview",
+        description:
+          "Preview which entities will be blocked, warned, or redacted and the redacted message, without changing runtime behavior.",
+        schema: {
+          type: "object",
+          properties: {
+            text: {
+              type: "string",
+              description: "Text to run through FogClaw policy preview",
+            },
+            strategy: {
+              type: "string",
+              description:
+                'Override redaction strategy for the preview: "token" ([EMAIL_1]), "mask" (****), or "hash" ([EMAIL_a1b2c3...]).',
+              enum: ["token", "mask", "hash"],
+            },
+            custom_labels: {
+              type: "array",
+              items: { type: "string" },
+              description: "Additional entity labels for zero-shot detection",
+            },
+          },
+          required: ["text"],
+        },
+        handler: async ({
+          text,
+          strategy,
+          custom_labels,
+        }: {
+          text: string;
+          strategy?: "token" | "mask" | "hash";
+          custom_labels?: string[];
+        }) => {
+          const result = await scanner.scan(text, custom_labels);
+          const plan = buildGuardrailPlan(result.entities, config);
+          const summary = planToSummary(plan);
+          const redacted = redact(
+            text,
+            plan.redacted,
+            strategy ?? config.redactStrategy,
+          );
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    entities: result.entities,
+                    totalEntities: summary.total,
+                    actionPlan: {
+                      blocked: {
+                        count: summary.blocked,
+                        labels: summary.labels.blocked,
+                      },
+                      warned: {
+                        count: summary.warned,
+                        labels: summary.labels.warned,
+                      },
+                      redacted: {
+                        count: summary.redacted,
+                        labels: summary.labels.redacted,
+                      },
+                    },
+                    redactedText: redacted.redacted_text,
+                    redactionStrategy: strategy ?? config.redactStrategy,
+                    mapping: redacted.mapping,
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          };
+        },
+      }
+    );
+
     // --- TOOL: On-demand redact ---
     api.registerTool(
       {
@@ -215,7 +364,7 @@ const fogclaw = {
     );
 
     api.logger?.info(
-      `[fogclaw] Plugin registered — guardrail: ${config.guardrail_mode}, model: ${config.model}, custom entities: ${config.custom_entities.length}`,
+      `[fogclaw] Plugin registered — guardrail: ${config.guardrail_mode}, model: ${config.model}, custom entities: ${config.custom_entities.length}, audit: ${config.auditEnabled}`,
     );
   },
 };

package/src/scanner.ts

@@ -1,23 +1,44 @@
-import type { Entity, FogClawConfig, ScanResult } from "./types.js";
+import type { Entity, FogClawConfig } from "./types.js";
+import { canonicalType } from "./types.js";
 import { RegexEngine } from "./engines/regex.js";
 import { GlinerEngine } from "./engines/gliner.js";
 
+type AllowlistPatternCache = {
+  values: Set<string>;
+  patterns: RegExp[];
+  entityValues: Map<string, Set<string>>;
+};
+
+function normalizeAllowlistValue(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function buildPatternMaps(value: string[] | undefined): RegExp[] {
+  if (!value || value.length === 0) {
+    return [];
+  }
+
+  return value.map((pattern) => new RegExp(pattern, "i"));
+}
+
 export class Scanner {
   private regexEngine: RegexEngine;
   private glinerEngine: GlinerEngine;
   private glinerAvailable = false;
   private config: FogClawConfig;
+  private allowlist: AllowlistPatternCache;
 
   constructor(config: FogClawConfig) {
     this.config = config;
     this.regexEngine = new RegexEngine();
-    this.glinerEngine = new GlinerEngine(
-      config.model,
-      config.confidence_threshold,
-    );
+
+    const glinerThreshold = this.computeGlinerThreshold(config);
+    this.glinerEngine = new GlinerEngine(config.model, glinerThreshold);
     if (config.custom_entities.length > 0) {
       this.glinerEngine.setCustomLabels(config.custom_entities);
     }
+
+    this.allowlist = this.buildAllowlistCache(config.allowlist);
   }
 
   async initialize(): Promise<void> {
@@ -32,19 +53,25 @@ export class Scanner {
     }
   }
 
-  async scan(text: string, extraLabels?: string[]): Promise<ScanResult> {
+  async scan(text: string, extraLabels?: string[]): Promise<{ entities: Entity[]; text: string }> {
     if (!text) return { entities: [], text };
 
     // Step 1: Regex pass (always runs, synchronous)
-    const regexEntities = this.regexEngine.scan(text);
+    const regexEntities = this.filterByPolicy(this.regexEngine.scan(text));
 
     // Step 2: GLiNER pass (if available)
     let glinerEntities: Entity[] = [];
     if (this.glinerAvailable) {
       try {
         glinerEntities = await this.glinerEngine.scan(text, extraLabels);
+        glinerEntities = this.filterByConfidence(glinerEntities);
+        glinerEntities = this.filterByPolicy(glinerEntities);
       } catch (err) {
-        console.warn(`[fogclaw] GLiNER scan failed, using regex results only: ${err instanceof Error ? err.message : String(err)}`);
+        console.warn(
+          `[fogclaw] GLiNER scan failed, using regex results only: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
       }
     }
 
@@ -53,6 +80,85 @@ export class Scanner {
 
     return { entities: merged, text };
   }
+
+  private filterByConfidence(entities: Entity[]): Entity[] {
+    return entities.filter((entity) => {
+      const threshold = this.getThresholdForLabel(entity.label);
+      return entity.confidence >= threshold;
+    });
+  }
+
+  private filterByPolicy(entities: Entity[]): Entity[] {
+    if (
+      this.allowlist.values.size === 0 &&
+      this.allowlist.patterns.length === 0 &&
+      this.allowlist.entityValues.size === 0
+    ) {
+      return entities;
+    }
+
+    return entities.filter((entity) => !this.shouldAllowlistEntity(entity));
+  }
+
+  private shouldAllowlistEntity(entity: Entity): boolean {
+    const normalizedText = normalizeAllowlistValue(entity.text);
+
+    if (this.allowlist.values.has(normalizedText)) {
+      return true;
+    }
+
+    if (this.allowlist.patterns.some((pattern) => pattern.test(entity.text))) {
+      return true;
+    }
+
+    const entityValues = this.allowlist.entityValues.get(entity.label);
+    if (entityValues && entityValues.has(normalizedText)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  private getThresholdForLabel(label: string): number {
+    const canonicalLabel = canonicalType(label);
+    return this.config.entityConfidenceThresholds[canonicalLabel] ?? this.config.confidence_threshold;
+  }
+
+  private computeGlinerThreshold(config: FogClawConfig): number {
+    const thresholds = Object.values(config.entityConfidenceThresholds);
+    if (thresholds.length === 0) {
+      return config.confidence_threshold;
+    }
+
+    return Math.min(config.confidence_threshold, ...thresholds);
+  }
+
+  private buildAllowlistCache(allowlist: FogClawConfig["allowlist"]): AllowlistPatternCache {
+    const globalValues = new Set(
+      allowlist.values.map((value) => normalizeAllowlistValue(value)),
+    );
+
+    const globalPatterns = buildPatternMaps(allowlist.patterns);
+
+    const entityValues = new Map<string, Set<string>>();
+    for (const [entityType, values] of Object.entries(allowlist.entities)) {
+      const canonical = canonicalType(entityType);
+      const uniqueValues = values
+        .map((value) => normalizeAllowlistValue(value))
+        .filter((value) => value.length > 0);
+      entityValues.set(canonical, new Set(uniqueValues));
+    }
+
+    return {
+      values: globalValues,
+      patterns: globalPatterns,
+      entityValues,
+    };
+  }
+
+  get isGlinerAvailable(): boolean {
+    return this.glinerAvailable;
+  }
 }
 
 /**

package/src/types.ts

@@ -11,6 +11,16 @@ export type RedactStrategy = "token" | "mask" | "hash";
 
 export type GuardrailAction = "redact" | "block" | "warn";
 
+export interface EntityConfidenceThresholds {
+  [entityType: string]: number;
+}
+
+export interface EntityAllowlist {
+  values: string[];
+  patterns: string[];
+  entities: Record<string, string[]>;
+}
+
 export interface FogClawConfig {
   enabled: boolean;
   guardrail_mode: GuardrailAction;
@@ -19,6 +29,9 @@ export interface FogClawConfig {
   confidence_threshold: number;
   custom_entities: string[];
   entityActions: Record<string, GuardrailAction>;
+  entityConfidenceThresholds: EntityConfidenceThresholds;
+  allowlist: EntityAllowlist;
+  auditEnabled: boolean;
 }
 
 export interface ScanResult {
@@ -32,6 +45,12 @@ export interface RedactResult {
   entities: Entity[];
 }
 
+export interface GuardrailPlan {
+  blocked: Entity[];
+  warned: Entity[];
+  redacted: Entity[];
+}
+
 export const CANONICAL_TYPE_MAP: Record<string, string> = {
   DOB: "DATE",
   ZIP: "ZIP_CODE",

package/tests/config.test.ts

@@ -1,104 +1,78 @@
 import { describe, it, expect } from "vitest";
-import { loadConfig, DEFAULT_CONFIG } from "../src/config.js";
 
-describe("loadConfig", () => {
-  it("returns defaults when no overrides are provided", () => {
-    const config = loadConfig({});
-    expect(config).toEqual(DEFAULT_CONFIG);
-  });
-
-  it("merges partial overrides with defaults", () => {
-    const config = loadConfig({ guardrail_mode: "block", confidence_threshold: 0.8 });
-
-    expect(config.guardrail_mode).toBe("block");
-    expect(config.confidence_threshold).toBe(0.8);
-    // Unset defaults are preserved
-    expect(config.enabled).toBe(true);
-    expect(config.redactStrategy).toBe("token");
-    expect(config.model).toBe("onnx-community/gliner_large-v2.1");
-    expect(config.custom_entities).toEqual([]);
-    expect(config.entityActions).toEqual({});
-  });
+import { loadConfig } from "../src/config.js";
 
-  it("accepts all valid guardrail_mode values", () => {
-    expect(() => loadConfig({ guardrail_mode: "redact" })).not.toThrow();
-    expect(() => loadConfig({ guardrail_mode: "block" })).not.toThrow();
-    expect(() => loadConfig({ guardrail_mode: "warn" })).not.toThrow();
-  });
-
-  it("rejects invalid guardrail_mode", () => {
-    expect(() =>
-      loadConfig({ guardrail_mode: "invalid" as never }),
-    ).toThrowError(
-      'Invalid guardrail_mode "invalid". Must be one of: redact, block, warn',
-    );
-  });
+describe("FogClaw config", () => {
+  it("loads defaults for new policy fields", () => {
+    const config = loadConfig({});
 
-  it("accepts all valid redactStrategy values", () => {
-    expect(() => loadConfig({ redactStrategy: "token" })).not.toThrow();
-    expect(() => loadConfig({ redactStrategy: "mask" })).not.toThrow();
-    expect(() => loadConfig({ redactStrategy: "hash" })).not.toThrow();
+    expect(config.entityConfidenceThresholds).toEqual({});
+    expect(config.allowlist).toMatchObject({
+      values: [],
+      patterns: [],
+      entities: {},
+    });
   });
 
-  it("rejects invalid redactStrategy", () => {
-    expect(() =>
-      loadConfig({ redactStrategy: "plaintext" as never }),
-    ).toThrowError(
-      'Invalid redactStrategy "plaintext". Must be one of: token, mask, hash',
-    );
-  });
+  it("canonicalizes per-entity confidence threshold keys", () => {
+    const config = loadConfig({
+      entityConfidenceThresholds: {
+        person: 0.7,
+      },
+    });
 
-  it("accepts confidence_threshold at boundaries (0 and 1)", () => {
-    expect(() => loadConfig({ confidence_threshold: 0 })).not.toThrow();
-    expect(() => loadConfig({ confidence_threshold: 1 })).not.toThrow();
-    expect(() => loadConfig({ confidence_threshold: 0.5 })).not.toThrow();
+    expect(config.entityConfidenceThresholds).toEqual({
+      PERSON: 0.7,
+    });
   });
 
-  it("rejects confidence_threshold below 0", () => {
+  it("rejects invalid per-entity confidence thresholds", () => {
     expect(() =>
-      loadConfig({ confidence_threshold: -0.1 }),
-    ).toThrowError("confidence_threshold must be between 0 and 1, got -0.1");
+      loadConfig({
+        entityConfidenceThresholds: {
+          PERSON: 1.2,
+        },
+      }),
+    ).toThrow('entityConfidenceThresholds["PERSON"] must be between 0 and 1, got 1.2');
   });
 
-  it("rejects confidence_threshold above 1", () => {
+  it("validates allowlist regex patterns", () => {
     expect(() =>
-      loadConfig({ confidence_threshold: 1.5 }),
-    ).toThrowError("confidence_threshold must be between 0 and 1, got 1.5");
+      loadConfig({
+        allowlist: {
+          values: ["ok@example.com"],
+          patterns: ["["],
+          entities: {
+            PERSON: ["John"],
+          },
+        },
+      }),
+    ).toThrow(/invalid regex pattern/);
   });
 
-  it("accepts valid entityActions values", () => {
+  it("canonicalizes allowlist entity keys", () => {
     const config = loadConfig({
-      entityActions: { PERSON: "redact", EMAIL: "block", SSN: "warn" },
-    });
-    expect(config.entityActions).toEqual({
-      PERSON: "redact",
-      EMAIL: "block",
-      SSN: "warn",
+      allowlist: {
+        entities: {
+          person: ["John"],
+        },
+      },
     });
-  });
 
-  it("rejects invalid entityActions values", () => {
-    expect(() =>
-      loadConfig({
-        entityActions: { EMAIL: "delete" as never },
-      }),
-    ).toThrowError(
-      'Invalid action "delete" for entity type "EMAIL". Must be one of: redact, block, warn',
-    );
-  });
-
-  it("preserves custom_entities from overrides", () => {
-    const config = loadConfig({ custom_entities: ["EMPLOYEE_ID", "PROJECT_CODE"] });
-    expect(config.custom_entities).toEqual(["EMPLOYEE_ID", "PROJECT_CODE"]);
+    expect(config.allowlist.entities).toEqual({
+      PERSON: ["John"],
+    });
   });
 
-  it("preserves model from overrides", () => {
-    const config = loadConfig({ model: "custom/my-model" });
-    expect(config.model).toBe("custom/my-model");
-  });
+  it("canonicalizes entity action labels", () => {
+    const config = loadConfig({
+      entityActions: {
+        person: "block",
+      },
+    });
 
-  it("allows disabling via enabled: false", () => {
-    const config = loadConfig({ enabled: false });
-    expect(config.enabled).toBe(false);
+    expect(config.entityActions).toEqual({
+      PERSON: "block",
+    });
   });
 });