@datafog/fogclaw 0.1.0

package/src/index.ts

@@ -0,0 +1,223 @@
+import { Scanner } from "./scanner.js";
+import { redact } from "./redactor.js";
+import { loadConfig } from "./config.js";
+import type { GuardrailAction } from "./types.js";
+
+export { Scanner } from "./scanner.js";
+export { redact } from "./redactor.js";
+export { loadConfig, DEFAULT_CONFIG } from "./config.js";
+export type {
+  Entity,
+  FogClawConfig,
+  ScanResult,
+  RedactResult,
+  RedactStrategy,
+  GuardrailAction,
+} from "./types.js";
+
+/**
+ * OpenClaw plugin definition.
+ *
+ * Registers:
+ * - `before_agent_start` hook for automatic PII guardrail
+ * - `fogclaw_scan` tool for on-demand entity detection
+ * - `fogclaw_redact` tool for on-demand redaction
+ */
+const fogclaw = {
+  id: "fogclaw",
+  name: "FogClaw",
+
+  register(api: any) {
+    const rawConfig = api.pluginConfig ?? api.getConfig?.() ?? {};
+    const config = loadConfig(rawConfig);
+
+    if (!config.enabled) {
+      api.logger?.info("[fogclaw] Plugin disabled via config");
+      return;
+    }
+
+    const scanner = new Scanner(config);
+    // Initialize GLiNER in the background — regex works immediately,
+    // GLiNER becomes available once the model loads.
+    scanner.initialize().catch((err: unknown) => {
+      api.logger?.warn(`[fogclaw] GLiNER background init failed: ${String(err)}`);
+    });
+
+    // --- HOOK: Guardrail on incoming messages ---
+    api.on("before_agent_start", async (event: any) => {
+      const message = event.prompt ?? "";
+      if (!message) return;
+
+      const result = 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[] = [];
+
+      // "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.`,
+        );
+      }
+
+      // "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.`,
+        );
+      }
+
+      // "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}`,
+        );
+      }
+
+      if (contextParts.length > 0) {
+        return { prependContext: contextParts.join("\n\n") };
+      }
+    });
+
+    // --- TOOL: On-demand scan ---
+    api.registerTool(
+      {
+        name: "fogclaw_scan",
+        id: "fogclaw_scan",
+        description:
+          "Scan text for PII and custom entities. Returns detected entities with types, positions, and confidence scores.",
+        schema: {
+          type: "object",
+          properties: {
+            text: {
+              type: "string",
+              description: "Text to scan for entities",
+            },
+            custom_labels: {
+              type: "array",
+              items: { type: "string" },
+              description:
+                "Additional entity labels for zero-shot detection (e.g., ['competitor name', 'project codename'])",
+            },
+          },
+          required: ["text"],
+        },
+        handler: async ({
+          text,
+          custom_labels,
+        }: {
+          text: string;
+          custom_labels?: string[];
+        }) => {
+          const result = await scanner.scan(text, custom_labels);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    entities: result.entities,
+                    count: result.entities.length,
+                    summary:
+                      result.entities.length > 0
+                        ? `Found ${result.entities.length} entities: ${[...new Set(result.entities.map((e) => e.label))].join(", ")}`
+                        : "No entities detected",
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          };
+        },
+      }
+    );
+
+    // --- TOOL: On-demand redact ---
+    api.registerTool(
+      {
+        name: "fogclaw_redact",
+        id: "fogclaw_redact",
+        description:
+          "Scan and redact PII/custom entities from text. Returns sanitized text with entities replaced.",
+        schema: {
+          type: "object",
+          properties: {
+            text: {
+              type: "string",
+              description: "Text to scan and redact",
+            },
+            strategy: {
+              type: "string",
+              description:
+                'Redaction strategy: "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 redacted = redact(
+            text,
+            result.entities,
+            strategy ?? config.redactStrategy,
+          );
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    redacted_text: redacted.redacted_text,
+                    entities_found: result.entities.length,
+                    mapping: redacted.mapping,
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          };
+        },
+      }
+    );
+
+    api.logger?.info(
+      `[fogclaw] Plugin registered — guardrail: ${config.guardrail_mode}, model: ${config.model}, custom entities: ${config.custom_entities.length}`,
+    );
+  },
+};
+
+export default fogclaw;

package/src/redactor.ts

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+import type { Entity, RedactResult, RedactStrategy } from "./types.js";
+
+export function redact(
+  text: string,
+  entities: Entity[],
+  strategy: RedactStrategy = "token",
+): RedactResult {
+  if (entities.length === 0) {
+    return { redacted_text: text, mapping: {}, entities: [] };
+  }
+
+  // Sort by start position descending so we replace from end to start
+  // without corrupting earlier offsets
+  const sorted = [...entities].sort((a, b) => b.start - a.start);
+
+  const counters: Record<string, number> = {};
+  const mapping: Record<string, string> = {};
+  let result = text;
+
+  for (const entity of sorted) {
+    const replacement = makeReplacement(entity, strategy, counters);
+    mapping[replacement] = entity.text;
+    result = result.slice(0, entity.start) + replacement + result.slice(entity.end);
+  }
+
+  return { redacted_text: result, mapping, entities };
+}
+
+function makeReplacement(
+  entity: Entity,
+  strategy: RedactStrategy,
+  counters: Record<string, number>,
+): string {
+  switch (strategy) {
+    case "token": {
+      counters[entity.label] = (counters[entity.label] ?? 0) + 1;
+      return `[${entity.label}_${counters[entity.label]}]`;
+    }
+    case "mask": {
+      return "*".repeat(Math.max(entity.text.length, 1));
+    }
+    case "hash": {
+      const digest = createHash("sha256")
+        .update(entity.text)
+        .digest("hex")
+        .slice(0, 12);
+      return `[${entity.label}_${digest}]`;
+    }
+  }
+}

package/src/scanner.ts

@@ -0,0 +1,90 @@
+import type { Entity, FogClawConfig, ScanResult } from "./types.js";
+import { RegexEngine } from "./engines/regex.js";
+import { GlinerEngine } from "./engines/gliner.js";
+
+export class Scanner {
+  private regexEngine: RegexEngine;
+  private glinerEngine: GlinerEngine;
+  private glinerAvailable = false;
+  private config: FogClawConfig;
+
+  constructor(config: FogClawConfig) {
+    this.config = config;
+    this.regexEngine = new RegexEngine();
+    this.glinerEngine = new GlinerEngine(
+      config.model,
+      config.confidence_threshold,
+    );
+    if (config.custom_entities.length > 0) {
+      this.glinerEngine.setCustomLabels(config.custom_entities);
+    }
+  }
+
+  async initialize(): Promise<void> {
+    try {
+      await this.glinerEngine.initialize();
+      this.glinerAvailable = true;
+    } catch (err) {
+      console.warn(
+        `[fogclaw] GLiNER failed to initialize, falling back to regex-only mode: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      this.glinerAvailable = false;
+    }
+  }
+
+  async scan(text: string, extraLabels?: string[]): Promise<ScanResult> {
+    if (!text) return { entities: [], text };
+
+    // Step 1: Regex pass (always runs, synchronous)
+    const regexEntities = this.regexEngine.scan(text);
+
+    // Step 2: GLiNER pass (if available)
+    let glinerEntities: Entity[] = [];
+    if (this.glinerAvailable) {
+      try {
+        glinerEntities = await this.glinerEngine.scan(text, extraLabels);
+      } catch (err) {
+        console.warn(`[fogclaw] GLiNER scan failed, using regex results only: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
+    // Step 3: Merge and deduplicate
+    const merged = deduplicateEntities([...regexEntities, ...glinerEntities]);
+
+    return { entities: merged, text };
+  }
+}
+
+/**
+ * Remove overlapping entity spans. When two entities overlap,
+ * keep the one with higher confidence. If equal, prefer regex.
+ */
+function deduplicateEntities(entities: Entity[]): Entity[] {
+  if (entities.length <= 1) return entities;
+
+  // Sort by start position, then by confidence descending
+  const sorted = [...entities].sort((a, b) => {
+    if (a.start !== b.start) return a.start - b.start;
+    return b.confidence - a.confidence;
+  });
+
+  const result: Entity[] = [sorted[0]];
+
+  for (let i = 1; i < sorted.length; i++) {
+    const current = sorted[i];
+    const last = result[result.length - 1];
+
+    // Check for overlap
+    if (current.start < last.end) {
+      // Overlapping: keep higher confidence (already in result if first)
+      if (current.confidence > last.confidence) {
+        result[result.length - 1] = current;
+      }
+      // Otherwise keep what's already in result
+    } else {
+      result.push(current);
+    }
+  }
+
+  return result;
+}

package/src/types.ts

@@ -0,0 +1,52 @@
+export interface Entity {
+  text: string;
+  label: string;
+  start: number;
+  end: number;
+  confidence: number;
+  source: "regex" | "gliner";
+}
+
+export type RedactStrategy = "token" | "mask" | "hash";
+
+export type GuardrailAction = "redact" | "block" | "warn";
+
+export interface FogClawConfig {
+  enabled: boolean;
+  guardrail_mode: GuardrailAction;
+  redactStrategy: RedactStrategy;
+  model: string;
+  confidence_threshold: number;
+  custom_entities: string[];
+  entityActions: Record<string, GuardrailAction>;
+}
+
+export interface ScanResult {
+  entities: Entity[];
+  text: string;
+}
+
+export interface RedactResult {
+  redacted_text: string;
+  mapping: Record<string, string>;
+  entities: Entity[];
+}
+
+export const CANONICAL_TYPE_MAP: Record<string, string> = {
+  DOB: "DATE",
+  ZIP: "ZIP_CODE",
+  PER: "PERSON",
+  ORG: "ORGANIZATION",
+  GPE: "LOCATION",
+  LOC: "LOCATION",
+  FAC: "ADDRESS",
+  PHONE_NUMBER: "PHONE",
+  SOCIAL_SECURITY_NUMBER: "SSN",
+  CREDIT_CARD_NUMBER: "CREDIT_CARD",
+  DATE_OF_BIRTH: "DATE",
+};
+
+export function canonicalType(entityType: string): string {
+  const normalized = entityType.toUpperCase().trim();
+  return CANONICAL_TYPE_MAP[normalized] ?? normalized;
+}

package/tests/config.test.ts

@@ -0,0 +1,104 @@
+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({});
+  });
+
+  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',
+    );
+  });
+
+  it("accepts all valid redactStrategy values", () => {
+    expect(() => loadConfig({ redactStrategy: "token" })).not.toThrow();
+    expect(() => loadConfig({ redactStrategy: "mask" })).not.toThrow();
+    expect(() => loadConfig({ redactStrategy: "hash" })).not.toThrow();
+  });
+
+  it("rejects invalid redactStrategy", () => {
+    expect(() =>
+      loadConfig({ redactStrategy: "plaintext" as never }),
+    ).toThrowError(
+      'Invalid redactStrategy "plaintext". Must be one of: token, mask, hash',
+    );
+  });
+
+  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();
+  });
+
+  it("rejects confidence_threshold below 0", () => {
+    expect(() =>
+      loadConfig({ confidence_threshold: -0.1 }),
+    ).toThrowError("confidence_threshold must be between 0 and 1, got -0.1");
+  });
+
+  it("rejects confidence_threshold above 1", () => {
+    expect(() =>
+      loadConfig({ confidence_threshold: 1.5 }),
+    ).toThrowError("confidence_threshold must be between 0 and 1, got 1.5");
+  });
+
+  it("accepts valid entityActions values", () => {
+    const config = loadConfig({
+      entityActions: { PERSON: "redact", EMAIL: "block", SSN: "warn" },
+    });
+    expect(config.entityActions).toEqual({
+      PERSON: "redact",
+      EMAIL: "block",
+      SSN: "warn",
+    });
+  });
+
+  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"]);
+  });
+
+  it("preserves model from overrides", () => {
+    const config = loadConfig({ model: "custom/my-model" });
+    expect(config.model).toBe("custom/my-model");
+  });
+
+  it("allows disabling via enabled: false", () => {
+    const config = loadConfig({ enabled: false });
+    expect(config.enabled).toBe(false);
+  });
+});

package/tests/gliner.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Mock the gliner npm package so we don't need the actual 1.4GB model
+vi.mock("gliner", () => {
+  class MockGliner {
+    private config: any;
+
+    constructor(config: any) {
+      this.config = config;
+    }
+
+    async initialize(): Promise<void> {
+      // No-op in mock
+    }
+
+    async inference(
+      text: string,
+      labels: string[],
+      options: { threshold: number },
+    ): Promise<Array<{ text: string; label: string; score: number; start: number; end: number }>> {
+      const results: Array<{ text: string; label: string; score: number; start: number; end: number }> = [];
+
+      // Simulate entity detection for "John Smith"
+      const johnIndex = text.indexOf("John Smith");
+      if (johnIndex !== -1 && labels.includes("person")) {
+        results.push({
+          text: "John Smith",
+          label: "person",
+          score: 0.95,
+          start: johnIndex,
+          end: johnIndex + "John Smith".length,
+        });
+      }
+
+      // Simulate entity detection for "Acme Corp"
+      const acmeIndex = text.indexOf("Acme Corp");
+      if (acmeIndex !== -1 && labels.includes("organization")) {
+        results.push({
+          text: "Acme Corp",
+          label: "organization",
+          score: 0.88,
+          start: acmeIndex,
+          end: acmeIndex + "Acme Corp".length,
+        });
+      }
+
+      // Simulate entity detection for "New York"
+      const nyIndex = text.indexOf("New York");
+      if (nyIndex !== -1 && labels.includes("location")) {
+        results.push({
+          text: "New York",
+          label: "location",
+          score: 0.91,
+          start: nyIndex,
+          end: nyIndex + "New York".length,
+        });
+      }
+
+      return results;
+    }
+  }
+
+  return { Gliner: MockGliner };
+});
+
+import { GlinerEngine } from "../src/engines/gliner.js";
+
+describe("GlinerEngine", () => {
+  let engine: GlinerEngine;
+
+  beforeEach(async () => {
+    engine = new GlinerEngine("onnx-community/gliner_small-v2.5", 0.5);
+    await engine.initialize();
+  });
+
+  it("detects person entities with canonical PERSON label", async () => {
+    const entities = await engine.scan("My name is John Smith and I live here.");
+
+    expect(entities).toHaveLength(1);
+    expect(entities[0].text).toBe("John Smith");
+    expect(entities[0].label).toBe("PERSON");
+  });
+
+  it("detects organization entities with canonical ORGANIZATION label", async () => {
+    const entities = await engine.scan("I work at Acme Corp downtown.");
+
+    expect(entities).toHaveLength(1);
+    expect(entities[0].text).toBe("Acme Corp");
+    expect(entities[0].label).toBe("ORGANIZATION");
+  });
+
+  it("detects multiple entity types in the same text", async () => {
+    const entities = await engine.scan(
+      "John Smith works at Acme Corp in New York.",
+    );
+
+    expect(entities).toHaveLength(3);
+
+    const labels = entities.map((e) => e.label);
+    expect(labels).toContain("PERSON");
+    expect(labels).toContain("ORGANIZATION");
+    expect(labels).toContain("LOCATION");
+  });
+
+  it("returns empty array for text with no entities", async () => {
+    const entities = await engine.scan("Hello world, this is a test.");
+
+    expect(entities).toEqual([]);
+  });
+
+  it("returns empty array for empty string input", async () => {
+    const entities = await engine.scan("");
+
+    expect(entities).toEqual([]);
+  });
+
+  it("allows setting custom labels without crashing", async () => {
+    expect(() => engine.setCustomLabels(["product", "event"])).not.toThrow();
+
+    // Scan still works after setting custom labels
+    const entities = await engine.scan("John Smith attended the event.");
+    expect(entities).toHaveLength(1);
+    expect(entities[0].label).toBe("PERSON");
+  });
+
+  it("applies canonical type mapping (lowercase person -> PERSON)", async () => {
+    // The mock returns lowercase "person" as label; canonicalType should map it to "PERSON"
+    const entities = await engine.scan("John Smith is here.");
+
+    expect(entities[0].label).toBe("PERSON");
+    // Verify it's not lowercase
+    expect(entities[0].label).not.toBe("person");
+  });
+
+  it("sets source to gliner for all detected entities", async () => {
+    const entities = await engine.scan(
+      "John Smith works at Acme Corp in New York.",
+    );
+
+    for (const entity of entities) {
+      expect(entity.source).toBe("gliner");
+    }
+  });
+
+  it("confidence comes from model score", async () => {
+    const entities = await engine.scan(
+      "John Smith works at Acme Corp in New York.",
+    );
+
+    const person = entities.find((e) => e.label === "PERSON");
+    const org = entities.find((e) => e.label === "ORGANIZATION");
+    const loc = entities.find((e) => e.label === "LOCATION");
+
+    // These match the scores set in our mock
+    expect(person?.confidence).toBe(0.95);
+    expect(org?.confidence).toBe(0.88);
+    expect(loc?.confidence).toBe(0.91);
+  });
+
+  it("throws if scan is called before initialize", async () => {
+    const uninitializedEngine = new GlinerEngine("some-model", 0.5);
+
+    await expect(uninitializedEngine.scan("test")).rejects.toThrow(
+      "GLiNER engine not initialized. Call initialize() first.",
+    );
+  });
+
+  it("reports isInitialized correctly", async () => {
+    const freshEngine = new GlinerEngine("some-model", 0.5);
+    expect(freshEngine.isInitialized).toBe(false);
+
+    await freshEngine.initialize();
+    expect(freshEngine.isInitialized).toBe(true);
+  });
+
+  it("includes correct start and end offsets", async () => {
+    const text = "Contact John Smith for details.";
+    const entities = await engine.scan(text);
+
+    expect(entities).toHaveLength(1);
+    expect(entities[0].start).toBe(8); // "Contact " is 8 chars
+    expect(entities[0].end).toBe(18); // 8 + "John Smith".length = 18
+  });
+});