@datafog/fogclaw 0.1.6 → 0.3.0

package/src/engines/gliner.ts

@@ -1,240 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { env } from "@xenova/transformers";
-
-import type { Entity } from "../types.js";
-import { canonicalType } from "../types.js";
-
-const DEFAULT_NER_LABELS = [
-  "person",
-  "organization",
-  "location",
-  "address",
-  "date of birth",
-  "medical record number",
-  "account number",
-  "passport number",
-];
-
-const GLINER_MODEL_FILES = [
-  "onnx/model_q4f16.onnx",
-  "onnx/model_q4.onnx",
-  "onnx/model_bnb4.onnx",
-  "onnx/model_int8.onnx",
-  "onnx/model_uint8.onnx",
-  "onnx/model_quantized.onnx",
-  "onnx/model_fp16.onnx",
-  "onnx/model.onnx",
-];
-
-const MODEL_DOWNLOAD_TIMEOUT_MS = 120_000;
-
-function isLikelyLocalPath(modelPath: string): boolean {
-  const trimmed = modelPath.trim();
-  if (!trimmed) {
-    return false;
-  }
-
-  const lower = trimmed.toLowerCase();
-  const hasExtension = [".onnx", ".ort", ".bin"].some((ext) => lower.endsWith(ext));
-  if (hasExtension) {
-    return true;
-  }
-
-  if (trimmed.startsWith(".") || path.isAbsolute(trimmed)) {
-    return true;
-  }
-
-  return false;
-}
-
-function toAbsolutePath(value: string): string {
-  return path.isAbsolute(value) ? value : path.resolve(process.cwd(), value);
-}
-
-function getModelCacheDir(): string {
-  return env.localModelPath ?? path.join(process.cwd(), ".cache");
-}
-
-function sanitizeModelReference(modelPath: string): string {
-  return modelPath.trim();
-}
-
-async function fileExists(filePath: string): Promise<boolean> {
-  try {
-    await fs.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function downloadModelIfNeeded(modelRepo: string, filename: string): Promise<string> {
-  const cacheDir = getModelCacheDir();
-  const localPath = path.join(cacheDir, modelRepo, filename);
-
-  if (await fileExists(localPath)) {
-    return localPath;
-  }
-
-  const url = `https://huggingface.co/${modelRepo}/resolve/main/${filename}`;
-  const headers = new Headers();
-  const token = process.env.HF_TOKEN ?? process.env.HF_ACCESS_TOKEN;
-  if (token) {
-    headers.set("Authorization", `Bearer ${token}`);
-  }
-
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), MODEL_DOWNLOAD_TIMEOUT_MS);
-
-  try {
-    const response = await fetch(url, { headers, signal: controller.signal });
-    if (!response.ok) {
-      throw new Error(`Unable to download model artifact: ${response.status}`);
-    }
-
-    const bytes = new Uint8Array(await response.arrayBuffer());
-    await fs.mkdir(path.dirname(localPath), { recursive: true });
-    await fs.writeFile(localPath, bytes);
-
-    return localPath;
-  } catch (err) {
-    if (err instanceof Error && err.name === "AbortError") {
-      throw new Error(`Model download timed out after ${MODEL_DOWNLOAD_TIMEOUT_MS}ms`);
-    }
-
-    throw err;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-async function resolveModelPath(modelPath: string): Promise<string> {
-  const sanitized = sanitizeModelReference(modelPath);
-  if (!sanitized) {
-    throw new Error("Model path is empty");
-  }
-
-  if (isLikelyLocalPath(sanitized)) {
-    const absolutePath = toAbsolutePath(sanitized);
-    if (!(await fileExists(absolutePath))) {
-      throw new Error(`Local GLiNER model file not found at: ${absolutePath}`);
-    }
-
-    return absolutePath;
-  }
-
-  const candidates = GLINER_MODEL_FILES;
-  let lastError: Error | undefined;
-
-  for (const filename of candidates) {
-    const localPath = path.join(getModelCacheDir(), sanitized, filename);
-    if (await fileExists(localPath)) {
-      return localPath;
-    }
-  }
-
-  for (const filename of candidates) {
-    try {
-      return await downloadModelIfNeeded(sanitized, filename);
-    } catch (err) {
-      lastError = err instanceof Error ? err : new Error(String(err));
-    }
-  }
-
-  throw new Error(
-    `Failed to resolve GLiNER model "${sanitized}". Tried ${candidates.join(", ")}: ${
-      lastError?.message ?? "unknown"
-    }`,
-  );
-}
-
-export class GlinerEngine {
-  private model: any = null;
-  private modelPath: string;
-  private threshold: number;
-  private customLabels: string[] = [];
-  private initialized = false;
-
-  constructor(modelPath: string, threshold: number = 0.5) {
-    this.modelPath = modelPath;
-    this.threshold = threshold;
-  }
-
-  async initialize(): Promise<void> {
-    if (this.initialized) return;
-
-    try {
-      const resolvedModelPath = await resolveModelPath(this.modelPath);
-      const glinerModule = await import("gliner/node").catch(async () => import("gliner"));
-      const { Gliner } = glinerModule;
-      this.model = new Gliner({
-        tokenizerPath: this.modelPath,
-        onnxSettings: {
-          modelPath: resolvedModelPath,
-          executionProvider: "cpu",
-        },
-        maxWidth: 12,
-        modelType: "span-level",
-      });
-      await this.model.initialize();
-      this.initialized = true;
-    } catch (err) {
-      throw new Error(
-        `Failed to initialize GLiNER model "${this.modelPath}": ${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
-  }
-
-  setCustomLabels(labels: string[]): void {
-    this.customLabels = labels;
-  }
-
-  async scan(text: string, extraLabels?: string[]): Promise<Entity[]> {
-    if (!text) return [];
-    if (!this.model) {
-      throw new Error("GLiNER engine not initialized. Call initialize() first.");
-    }
-
-    const labels = [
-      ...DEFAULT_NER_LABELS,
-      ...this.customLabels,
-      ...(extraLabels ?? []),
-    ];
-
-    // Deduplicate labels
-    const uniqueLabels = [...new Set(labels)];
-
-    const rawResults = await this.model.inference({
-      texts: [text],
-      entities: uniqueLabels,
-      flatNer: false,
-      threshold: this.threshold,
-    });
-    const flatResults = Array.isArray(rawResults) ? rawResults.flat() : [];
-
-    return flatResults.map(
-      (
-        r: {
-          spanText?: string;
-          text: string;
-          label: string;
-          score: number;
-          start: number;
-          end: number;
-        },
-      ) => ({
-        text: r.spanText ?? r.text,
-        label: canonicalType(r.label),
-        start: r.start,
-        end: r.end,
-        confidence: r.score,
-        source: "gliner" as const,
-      }),
-    );
-  }
-
-  get isInitialized(): boolean {
-    return this.initialized;
-  }
-}

package/src/engines/regex.ts

@@ -1,71 +0,0 @@
-import type { Entity } from "../types.js";
-
-interface PatternDef {
-  label: string;
-  pattern: RegExp;
-}
-
-const PATTERNS: PatternDef[] = [
-  {
-    label: "EMAIL",
-    pattern:
-      /(?<![A-Za-z0-9._%+\-@])(?![A-Za-z_]{2,20}=)[A-Za-z0-9!#$%&*+\-/=^_`{|}~][A-Za-z0-9!#$%&'*+\-/=?^_`{|}~.]*@(?:\.?[A-Za-z0-9-]+\.)+[A-Za-z]{2,}(?=$|[^A-Za-z])/gi,
-  },
-  {
-    label: "PHONE",
-    pattern:
-      /(?<![A-Za-z0-9])(?:(?:(?:\+?1)[-.\s]?)?(?:\(\d{3}\)|\d{3})[-.\s]?\d{3}[-.\s]?\d{4}|\+\d{1,3}[\s\-.]?\d{1,4}(?:[\s\-.]?\d{2,4}){2,3})(?![-A-Za-z0-9])/gi,
-  },
-  {
-    label: "SSN",
-    pattern:
-      /(?<!\d)(?:(?!000|666)\d{3}-(?!00)\d{2}-(?!0000)\d{4}|(?!000|666)\d{3}(?!00)\d{2}(?!0000)\d{4})(?!\d)/g,
-  },
-  {
-    label: "CREDIT_CARD",
-    pattern:
-      /\b(?:4\d{12}(?:\d{3})?|5[1-5]\d{14}|3[47]\d{13}|(?:(?:4\d{3}|5[1-5]\d{2}|3[47]\d{2})[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4})|(?:3[47]\d{2}[-\s]?\d{6}[-\s]?\d{5}))\b/g,
-  },
-  {
-    label: "IP_ADDRESS",
-    pattern:
-      /\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.(?:25[0-5]|2[0-4]\d|1?\d?\d)\.(?:25[0-5]|2[0-4]\d|1?\d?\d)\.(?:25[0-5]|2[0-4]\d|1?\d?\d))\b/g,
-  },
-  {
-    label: "DATE",
-    pattern:
-      /\b(?:(?:0?[1-9]|1[0-2])[/-](?:0?[1-9]|[12]\d|3[01])[/-](?:\d{2}|\d{4})|(?:\d{4})-(?:0?[1-9]|1[0-2])-(?:0?[1-9]|[12]\d|3[01])|(?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|Jun(?:e)?|Jul(?:y)?|Aug(?:ust)?|Sep(?:t(?:ember)?)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?)\s+(?:0?[1-9]|[12]\d|3[01]),\s+(?:19|20)\d{2})\b/gi,
-  },
-  {
-    label: "ZIP_CODE",
-    pattern: /\b\d{5}(?:-\d{4})?\b/g,
-  },
-];
-
-export class RegexEngine {
-  scan(text: string): Entity[] {
-    const entities: Entity[] = [];
-
-    for (const { label, pattern } of PATTERNS) {
-      // Reset lastIndex to avoid stale state from previous calls
-      pattern.lastIndex = 0;
-
-      let match: RegExpExecArray | null;
-      while ((match = pattern.exec(text)) !== null) {
-        entities.push({
-          text: match[0],
-          label,
-          start: match.index,
-          end: match.index + match[0].length,
-          confidence: 1.0,
-          source: "regex",
-        });
-      }
-    }
-
-    // Sort by start position for deterministic output
-    entities.sort((a, b) => a.start - b.start || a.end - b.end);
-
-    return entities;
-  }
-}

package/src/index.ts

@@ -1,372 +0,0 @@
-import { Scanner } from "./scanner.js";
-import { redact } from "./redactor.js";
-import { loadConfig } from "./config.js";
-import type {
-  Entity,
-  FogClawConfig,
-  GuardrailAction,
-  RedactResult,
-  RedactStrategy,
-  ScanResult,
-} 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";
-
-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 = {
-  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: ScanResult = await scanner.scan(message);
-      if (result.entities.length === 0) return;
-
-      const plan = buildGuardrailPlan(result.entities, config);
-      const contextParts = buildGuardrailContext(plan, config);
-
-      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,
-          })}`,
-        );
-      }
-
-      if (plan.redacted.length > 0) {
-        const redactedResult: RedactResult = redact(
-          message,
-          plan.redacted,
-          config.redactStrategy,
-        );
-        contextParts.push(
-          `[FOGCLAW REDACTED] The following is the user's message with PII redacted:\n${redactedResult.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((entity) => entity.label))].join(", ")}`
-                        : "No entities detected",
-                  },
-                  null,
-                  2,
-                ),
-              },
-            ],
-          };
-        },
-      }
-    );
-
-    // --- 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(
-      {
-        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}, audit: ${config.auditEnabled}`,
-    );
-  },
-};
-
-export default fogclaw;