@datafog/fogclaw 0.1.5 → 0.2.0

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",
@@ -50,3 +69,7 @@ export function canonicalType(entityType: string): string {
   const normalized = entityType.toUpperCase().trim();
   return CANONICAL_TYPE_MAP[normalized] ?? normalized;
 }
+
+export function resolveAction(entity: Entity, config: FogClawConfig): GuardrailAction {
+  return config.entityActions[entity.label] ?? config.guardrail_mode;
+}

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",
+    });
   });
 });

package/tests/extract.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from "vitest";
+import { extractText, replaceText } from "../src/extract.js";
+
+describe("extractText", () => {
+  it("extracts from a plain string", () => {
+    expect(extractText("hello world")).toBe("hello world");
+  });
+
+  it("extracts from an object with content as string", () => {
+    expect(extractText({ role: "toolResult", content: "file contents here" })).toBe(
+      "file contents here",
+    );
+  });
+
+  it("extracts from content block array with single text block", () => {
+    const msg = {
+      role: "toolResult",
+      content: [{ type: "text", text: "block one" }],
+    };
+    expect(extractText(msg)).toBe("block one");
+  });
+
+  it("extracts from content block array with multiple text blocks", () => {
+    const msg = {
+      content: [
+        { type: "text", text: "first" },
+        { type: "text", text: "second" },
+      ],
+    };
+    expect(extractText(msg)).toBe("first\0second");
+  });
+
+  it("skips non-text blocks in content array", () => {
+    const msg = {
+      content: [
+        { type: "text", text: "visible" },
+        { type: "image", source: { data: "base64..." } },
+        { type: "text", text: "also visible" },
+      ],
+    };
+    expect(extractText(msg)).toBe("visible\0also visible");
+  });
+
+  it("returns empty string for null", () => {
+    expect(extractText(null)).toBe("");
+  });
+
+  it("returns empty string for undefined", () => {
+    expect(extractText(undefined)).toBe("");
+  });
+
+  it("returns empty string for a number", () => {
+    expect(extractText(42)).toBe("");
+  });
+
+  it("returns empty string for object with no content", () => {
+    expect(extractText({ role: "toolResult" })).toBe("");
+  });
+
+  it("returns empty string for object with null content", () => {
+    expect(extractText({ content: null })).toBe("");
+  });
+
+  it("returns empty string for empty content array", () => {
+    expect(extractText({ content: [] })).toBe("");
+  });
+
+  it("returns empty string for content array with only image blocks", () => {
+    const msg = {
+      content: [
+        { type: "image", source: { data: "..." } },
+        { type: "image", source: { data: "..." } },
+      ],
+    };
+    expect(extractText(msg)).toBe("");
+  });
+
+  it("handles empty string content", () => {
+    expect(extractText({ content: "" })).toBe("");
+  });
+
+  it("handles text block with empty text", () => {
+    const msg = { content: [{ type: "text", text: "" }] };
+    expect(extractText(msg)).toBe("");
+  });
+
+  it("handles content array with mixed valid and invalid blocks", () => {
+    const msg = {
+      content: [
+        { type: "text", text: "valid" },
+        { type: "text" }, // missing text property
+        null,
+        { type: "text", text: "also valid" },
+      ],
+    };
+    expect(extractText(msg)).toBe("valid\0also valid");
+  });
+});
+
+describe("replaceText", () => {
+  it("replaces plain string message", () => {
+    expect(replaceText("original", "redacted")).toBe("redacted");
+  });
+
+  it("replaces content string in object", () => {
+    const msg = { role: "toolResult", content: "original text" };
+    const result = replaceText(msg, "redacted text") as Record<string, unknown>;
+    expect(result.content).toBe("redacted text");
+    expect(result.role).toBe("toolResult");
+  });
+
+  it("does not mutate the original message object", () => {
+    const msg = { role: "toolResult", content: "original" };
+    replaceText(msg, "redacted");
+    expect(msg.content).toBe("original");
+  });
+
+  it("replaces single text block in content array", () => {
+    const msg = {
+      content: [{ type: "text", text: "original" }],
+    };
+    const result = replaceText(msg, "redacted") as Record<string, unknown>;
+    const content = result.content as Array<Record<string, unknown>>;
+    expect(content[0].text).toBe("redacted");
+    expect(content[0].type).toBe("text");
+  });
+
+  it("replaces multiple text blocks using segment separator", () => {
+    const msg = {
+      content: [
+        { type: "text", text: "first original" },
+        { type: "text", text: "second original" },
+      ],
+    };
+    const result = replaceText(msg, "first redacted\0second redacted") as Record<string, unknown>;
+    const content = result.content as Array<Record<string, unknown>>;
+    expect(content[0].text).toBe("first redacted");
+    expect(content[1].text).toBe("second redacted");
+  });
+
+  it("preserves non-text blocks in content array", () => {
+    const msg = {
+      content: [
+        { type: "text", text: "original" },
+        { type: "image", source: { data: "base64" } },
+        { type: "text", text: "also original" },
+      ],
+    };
+    const result = replaceText(msg, "redacted\0also redacted") as Record<string, unknown>;
+    const content = result.content as Array<Record<string, unknown>>;
+    expect(content[0].text).toBe("redacted");
+    expect((content[1] as any).type).toBe("image");
+    expect((content[1] as any).source.data).toBe("base64");
+    expect(content[2].text).toBe("also redacted");
+  });
+
+  it("returns null unchanged", () => {
+    expect(replaceText(null, "x")).toBe(null);
+  });
+
+  it("returns undefined unchanged", () => {
+    expect(replaceText(undefined, "x")).toBe(undefined);
+  });
+
+  it("returns number unchanged", () => {
+    expect(replaceText(42, "x")).toBe(42);
+  });
+
+  it("returns message unchanged if content is null", () => {
+    const msg = { content: null };
+    expect(replaceText(msg, "x")).toBe(msg);
+  });
+
+  it("returns message unchanged if content is not string or array", () => {
+    const msg = { content: 123 };
+    expect(replaceText(msg, "x")).toBe(msg);
+  });
+
+  it("preserves extra properties on the message", () => {
+    const msg = { role: "toolResult", content: "original", toolCallId: "abc123" };
+    const result = replaceText(msg, "redacted") as Record<string, unknown>;
+    expect(result.toolCallId).toBe("abc123");
+    expect(result.role).toBe("toolResult");
+  });
+});

package/tests/message-sending-handler.test.ts

@@ -0,0 +1,244 @@
+import { describe, it, expect, vi, beforeAll, afterAll } from "vitest";
+import { createMessageSendingHandler } from "../src/message-sending-handler.js";
+import { Scanner } from "../src/scanner.js";
+import type { FogClawConfig } from "../src/types.js";
+
+function makeConfig(overrides: Partial<FogClawConfig> = {}): FogClawConfig {
+  return {
+    enabled: true,
+    guardrail_mode: "redact",
+    redactStrategy: "token",
+    model: "invalid:/not/real/model",
+    confidence_threshold: 0.5,
+    custom_entities: [],
+    entityActions: {},
+    entityConfidenceThresholds: {},
+    allowlist: { values: [], patterns: [], entities: {} },
+    auditEnabled: false,
+    ...overrides,
+  };
+}
+
+function makeLogger() {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+  };
+}
+
+function makeCtx(channelId = "telegram") {
+  return { channelId };
+}
+
+describe("createMessageSendingHandler", () => {
+  // Suppress GLiNER init warnings
+  beforeAll(() => {
+    vi.spyOn(console, "warn").mockImplementation(() => undefined);
+  });
+  afterAll(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns an async function", () => {
+    const config = makeConfig();
+    const scanner = new Scanner(config);
+    const handler = createMessageSendingHandler(config, scanner);
+    expect(typeof handler).toBe("function");
+  });
+
+  it("redacts SSN in outbound message", async () => {
+    const config = makeConfig();
+    const scanner = new Scanner(config);
+    const handler = createMessageSendingHandler(config, scanner);
+
+    const result = await handler(
+      { to: "user123", content: "Your SSN is 123-45-6789." },
+      makeCtx(),
+    );
+
+    expect(result).toBeDefined();
+    expect(result!.content).toContain("[SSN_1]");
+    expect(result!.content).not.toContain("123-45-6789");
+    expect(result!.cancel).toBeUndefined();
+  });
+
+  it("redacts email and phone in outbound message", async () => {
+    const config = makeConfig();
+    const scanner = new Scanner(config);
+    const handler = createMessageSendingHandler(config, scanner);
+
+    const result = await handler(
+      { to: "user", content: "Call 555-123-4567 or email john@example.com" },
+      makeCtx(),
+    );
+
+    expect(result).toBeDefined();
+    expect(result!.content).toContain("[PHONE_1]");
+    expect(result!.content).toContain("[EMAIL_1]");
+    expect(result!.content).not.toContain("555-123-4567");
+    expect(result!.content).not.toContain("john@example.com");
+  });
+
+  it("returns void when no PII found", async () => {
+    const config = makeConfig();
+    const scanner = new Scanner(config);
+    const handler = createMessageSendingHandler(config, scanner);
+
+    const result = await handler(
+      { to: "user", content: "Hello, how can I help you today?" },
+      makeCtx(),
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it("returns void for empty content", async () => {
+    const config = makeConfig();
+    const scanner = new Scanner(config);
+    const handler = createMessageSendingHandler(config, scanner);
+
+    const result = await handler(
+      { to: "user", content: "" },
+      makeCtx(),
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it("never returns cancel: true", async () => {
+    const config = makeConfig({
+      entityActions: { SSN: "block" },
+    });
+    const scanner = new Scanner(config);
+    const handler = createMessageSendingHandler(config, scanner);
+
+    const result = await handler(
+      { to: "user", content: "SSN 123-45-6789" },
+      makeCtx(),
+    );
+
+    expect(result).toBeDefined();
+    expect(result!.cancel).toBeUndefined();
+    expect(result!.content).toContain("[SSN_1]");
+  });
+
+  it("all guardrail modes produce span-level redaction", async () => {
+    const config = makeConfig({
+      entityActions: { SSN: "block", EMAIL: "warn", PHONE: "redact" },
+    });
+    const scanner = new Scanner(config);
+    const handler = createMessageSendingHandler(config, scanner);
+
+    const result = await handler(
+      {
+        to: "user",
+        content: "SSN 123-45-6789, email john@example.com, call 555-123-4567",
+      },
+      makeCtx(),
+    );
+
+    expect(result).toBeDefined();
+    expect(result!.content).toContain("[SSN_1]");
+    expect(result!.content).toContain("[EMAIL_1]");
+    expect(result!.content).toContain("[PHONE_1]");
+  });
+
+  it("respects allowlist — global values", async () => {
+    const config = makeConfig({
+      allowlist: {
+        values: ["noreply@example.com"],
+        patterns: [],
+        entities: {},
+      },
+    });
+    const scanner = new Scanner(config);
+    const handler = createMessageSendingHandler(config, scanner);
+
+    const result = await handler(
+      { to: "user", content: "Contact noreply@example.com for help" },
+      makeCtx(),
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  it("uses mask redaction strategy", async () => {
+    const config = makeConfig({ redactStrategy: "mask" });
+    const scanner = new Scanner(config);
+    const handler = createMessageSendingHandler(config, scanner);
+
+    const result = await handler(
+      { to: "user", content: "SSN is 123-45-6789" },
+      makeCtx(),
+    );
+
+    expect(result).toBeDefined();
+    expect(result!.content).toContain("***********");
+    expect(result!.content).not.toContain("123-45-6789");
+  });
+
+  it("uses hash redaction strategy", async () => {
+    const config = makeConfig({ redactStrategy: "hash" });
+    const scanner = new Scanner(config);
+    const handler = createMessageSendingHandler(config, scanner);
+
+    const result = await handler(
+      { to: "user", content: "SSN is 123-45-6789" },
+      makeCtx(),
+    );
+
+    expect(result).toBeDefined();
+    expect(result!.content).toMatch(/\[SSN_[a-f0-9]{12}\]/);
+  });
+
+  describe("audit logging", () => {
+    it("emits audit log with source outbound when PII found", async () => {
+      const config = makeConfig({ auditEnabled: true });
+      const scanner = new Scanner(config);
+      const logger = makeLogger();
+      const handler = createMessageSendingHandler(config, scanner, logger);
+
+      await handler(
+        { to: "user", content: "SSN 123-45-6789" },
+        makeCtx("discord"),
+      );
+
+      expect(logger.info).toHaveBeenCalledOnce();
+      const logCall = logger.info.mock.calls[0][0] as string;
+      expect(logCall).toContain("[FOGCLAW AUDIT]");
+      expect(logCall).toContain("outbound_scan");
+      expect(logCall).toContain('"source":"outbound"');
+      expect(logCall).toContain('"channelId":"discord"');
+      expect(logCall).toContain('"SSN"');
+      expect(logCall).not.toContain("123-45-6789");
+    });
+
+    it("does not emit audit log when auditEnabled is false", async () => {
+      const config = makeConfig({ auditEnabled: false });
+      const scanner = new Scanner(config);
+      const logger = makeLogger();
+      const handler = createMessageSendingHandler(config, scanner, logger);
+
+      await handler(
+        { to: "user", content: "SSN 123-45-6789" },
+        makeCtx(),
+      );
+
+      expect(logger.info).not.toHaveBeenCalled();
+    });
+
+    it("does not emit audit log when no PII found", async () => {
+      const config = makeConfig({ auditEnabled: true });
+      const scanner = new Scanner(config);
+      const logger = makeLogger();
+      const handler = createMessageSendingHandler(config, scanner, logger);
+
+      await handler(
+        { to: "user", content: "Clean message" },
+        makeCtx(),
+      );
+
+      expect(logger.info).not.toHaveBeenCalled();
+    });
+  });
+});