clawmoat 0.7.0 → 1.0.0

package/src/adapters/express.js

@@ -0,0 +1,161 @@
+/**
+ * Express/Fastify Middleware Adapter
+ * 
+ * One-line security for any Express/Fastify API that serves an AI agent.
+ * 
+ * Usage (Express):
+ *   const { clawmoatMiddleware } = require('clawmoat/adapters/express');
+ *   app.use(clawmoatMiddleware({ mode: 'enforce' }));
+ * 
+ * Usage (Fastify):
+ *   const { clawmoatPlugin } = require('clawmoat/adapters/express');
+ *   fastify.register(clawmoatPlugin, { mode: 'enforce' });
+ * 
+ * @module adapters/express
+ */
+
+'use strict';
+
+/**
+ * Express middleware factory
+ * @param {Object} [opts] - Options
+ * @param {string} [opts.mode='enforce'] - enforce | monitor
+ * @param {string[]} [opts.scanPaths=['/api/*','/chat/*','/agent/*']] - Paths to scan
+ * @param {string[]} [opts.skipPaths=['/health','/status']] - Paths to skip
+ * @param {Function} [opts.onBlock] - (req, findings) => void
+ * @param {Function} [opts.onFinding] - (req, finding) => void
+ * @returns {Function} Express middleware
+ */
+function clawmoatMiddleware(opts = {}) {
+  const {
+    mode = 'enforce',
+    scanPaths = null,
+    skipPaths = ['/health', '/status', '/ping', '/favicon.ico'],
+    onBlock = null,
+    onFinding = null,
+  } = opts;
+
+  // Lazy load
+  let moat = null;
+  let obfuscation = null;
+
+  function getMoat() {
+    if (!moat) {
+      const ClawMoat = require('../index');
+      moat = new ClawMoat();
+    }
+    return moat;
+  }
+
+  function getObfuscation() {
+    if (!obfuscation) obfuscation = require('../obfuscation-scanner');
+    return obfuscation;
+  }
+
+  return function clawmoat(req, res, next) {
+    // Skip non-matching paths
+    if (skipPaths.some(p => req.path === p || req.path.startsWith(p))) {
+      return next();
+    }
+
+    if (scanPaths && !scanPaths.some(p => {
+      if (p.endsWith('*')) return req.path.startsWith(p.slice(0, -1));
+      return req.path === p;
+    })) {
+      return next();
+    }
+
+    // Only scan requests with bodies
+    if (!req.body || (typeof req.body === 'object' && Object.keys(req.body).length === 0)) {
+      return next();
+    }
+
+    const text = typeof req.body === 'string' ? req.body : JSON.stringify(req.body);
+    const m = getMoat();
+    const o = getObfuscation();
+
+    // Scan inbound
+    const inbound = m.scanInbound(text);
+    const obfResult = o.scanObfuscation(text);
+
+    const findings = [...(inbound.findings || []), ...(obfResult.findings || [])];
+
+    if (findings.length > 0) {
+      // Attach findings to request for downstream use
+      req.clawmoat = { findings, blocked: false };
+
+      for (const f of findings) {
+        if (onFinding) onFinding(req, f);
+      }
+
+      if (mode === 'enforce' && (!inbound.safe || !obfResult.safe)) {
+        req.clawmoat.blocked = true;
+        if (onBlock) onBlock(req, findings);
+
+        return res.status(422).json({
+          error: 'Request blocked by ClawMoat',
+          code: 'CLAWMOAT_BLOCKED',
+          findings: findings.map(f => ({
+            type: f.type,
+            subtype: f.subtype,
+            severity: f.severity,
+            evidence: f.evidence,
+          })),
+        });
+      }
+    }
+
+    // Wrap res.json to scan outbound
+    const originalJson = res.json.bind(res);
+    res.json = function(data) {
+      const outText = typeof data === 'string' ? data : JSON.stringify(data);
+      const outbound = m.scanOutbound(outText);
+
+      if (outbound.findings && outbound.findings.length > 0) {
+        if (!req.clawmoat) req.clawmoat = { findings: [], blocked: false };
+        req.clawmoat.findings.push(...outbound.findings);
+
+        if (mode === 'enforce' && !outbound.safe) {
+          return originalJson({
+            error: 'Response blocked by ClawMoat — potential data leak',
+            code: 'CLAWMOAT_OUTPUT_BLOCKED',
+          });
+        }
+      }
+
+      return originalJson(data);
+    };
+
+    next();
+  };
+}
+
+/**
+ * Fastify plugin
+ */
+async function clawmoatPlugin(fastify, opts = {}) {
+  const middleware = clawmoatMiddleware(opts);
+  
+  fastify.addHook('preHandler', (request, reply, done) => {
+    // Adapt Fastify request/reply to Express-like interface
+    const req = {
+      path: request.url,
+      body: request.body,
+      clawmoat: null,
+    };
+    const res = {
+      status: (code) => ({ json: (data) => reply.code(code).send(data) }),
+      json: (data) => reply.send(data),
+    };
+
+    middleware(req, res, () => {
+      if (req.clawmoat) request.clawmoat = req.clawmoat;
+      done();
+    });
+  });
+}
+
+module.exports = {
+  clawmoatMiddleware,
+  clawmoatPlugin,
+};

package/src/adapters/index.js

@@ -0,0 +1,92 @@
+/**
+ * ClawMoat Framework Adapters
+ * 
+ * Drop-in integrations for popular AI/web frameworks.
+ * 
+ * Usage:
+ *   // LangChain
+ *   const { ClawMoatCallbackHandler } = require('clawmoat/adapters/langchain');
+ * 
+ *   // Express
+ *   const { clawmoatMiddleware } = require('clawmoat/adapters/express');
+ * 
+ *   // Generic (any framework)
+ *   const { createGuard } = require('clawmoat/adapters');
+ */
+
+'use strict';
+
+const { ClawMoatCallbackHandler, wrapChain } = require('./langchain');
+const { clawmoatMiddleware, clawmoatPlugin } = require('./express');
+
+/**
+ * Generic guard factory — works with any framework
+ * @param {Object} [opts] - Options
+ * @returns {Object} Guard with scanInput/scanOutput/scanTool methods
+ */
+function createGuard(opts = {}) {
+  const { mode = 'enforce' } = opts;
+  
+  // Lazy load all scanners
+  let moat, obf, code;
+  const getMoat = () => { if (!moat) { const C = require('../index'); moat = new C(); } return moat; };
+  const getObf = () => { if (!obf) obf = require('../obfuscation-scanner'); return obf; };
+  const getCode = () => { if (!code) code = require('../code-scanner'); return code; };
+
+  function _check(findings) {
+    if (findings.length === 0) return { safe: true, findings: [] };
+    if (mode === 'monitor') return { safe: true, findings, warning: true };
+    const hasCritical = findings.some(f => f.severity === 'critical' || f.severity === 'high');
+    return { safe: !hasCritical, findings };
+  }
+
+  return {
+    /**
+     * Scan user/external input before processing
+     */
+    scanInput(text) {
+      const inbound = getMoat().scanInbound(text);
+      const obfResult = getObf().scanObfuscation(text);
+      return _check([...(inbound.findings || []), ...(obfResult.findings || [])]);
+    },
+
+    /**
+     * Scan agent output before sending
+     */
+    scanOutput(text) {
+      const outbound = getMoat().scanOutbound(text);
+      return _check(outbound.findings || []);
+    },
+
+    /**
+     * Scan tool call before execution
+     */
+    scanTool(toolName, args) {
+      const text = typeof args === 'string' ? args : JSON.stringify(args);
+      const result = getCode().scanCode(text, { tool: toolName });
+      return _check(result.findings || []);
+    },
+
+    /**
+     * Scan tool result before returning to model
+     */
+    scanToolResult(text) {
+      const inbound = getMoat().scanInbound(text);
+      return _check(inbound.findings || []);
+    },
+
+    /** Get mode */
+    get mode() { return mode; },
+  };
+}
+
+module.exports = {
+  // LangChain
+  ClawMoatCallbackHandler,
+  wrapChain,
+  // Express/Fastify
+  clawmoatMiddleware,
+  clawmoatPlugin,
+  // Generic
+  createGuard,
+};

package/src/adapters/langchain.js

@@ -0,0 +1,185 @@
+/**
+ * LangChain Adapter for ClawMoat
+ * 
+ * Drop-in middleware for LangChain applications.
+ * Wraps chains, agents, and tools with ClawMoat security scanning.
+ * 
+ * Usage:
+ *   const { ClawMoatCallbackHandler } = require('clawmoat/adapters/langchain');
+ *   const handler = new ClawMoatCallbackHandler({ mode: 'enforce' });
+ *   const chain = new LLMChain({ llm, prompt, callbacks: [handler] });
+ * 
+ * @module adapters/langchain
+ */
+
+'use strict';
+
+/**
+ * LangChain callback handler that scans inputs/outputs
+ */
+class ClawMoatCallbackHandler {
+  constructor(opts = {}) {
+    this.name = 'ClawMoatCallbackHandler';
+    this.mode = opts.mode || 'enforce';
+    this.onBlock = opts.onBlock || null;
+    this.onFinding = opts.onFinding || null;
+    this.findings = [];
+
+    // Lazy load to avoid circular deps
+    this._moat = null;
+    this._obfuscation = null;
+    this._codeScanner = null;
+  }
+
+  _getMoat() {
+    if (!this._moat) {
+      const ClawMoat = require('../index');
+      this._moat = new ClawMoat();
+    }
+    return this._moat;
+  }
+
+  _getObfuscation() {
+    if (!this._obfuscation) this._obfuscation = require('../obfuscation-scanner');
+    return this._obfuscation;
+  }
+
+  _getCodeScanner() {
+    if (!this._codeScanner) this._codeScanner = require('../code-scanner');
+    return this._codeScanner;
+  }
+
+  /**
+   * Called when chain starts — scan input
+   */
+  async handleChainStart(chain, inputs) {
+    const text = typeof inputs === 'string' ? inputs : JSON.stringify(inputs);
+    
+    // Scan for prompt injection + obfuscation
+    const moat = this._getMoat();
+    const inbound = moat.scanInbound(text);
+    const obfResult = this._getObfuscation().scanObfuscation(text);
+    
+    const allFindings = [...(inbound.findings || []), ...(obfResult.findings || [])];
+    this.findings.push(...allFindings);
+
+    for (const f of allFindings) {
+      if (this.onFinding) this.onFinding(f, 'chain_input');
+    }
+
+    if (!inbound.safe || !obfResult.safe) {
+      if (this.mode === 'enforce') {
+        const err = new Error(`[ClawMoat] Blocked: ${allFindings[0]?.evidence || 'threat detected'}`);
+        err.code = 'CLAWMOAT_BLOCKED';
+        err.findings = allFindings;
+        if (this.onBlock) this.onBlock(allFindings, 'chain_input');
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * Called when chain ends — scan output for leaks
+   */
+  async handleChainEnd(outputs) {
+    const text = typeof outputs === 'string' ? outputs : JSON.stringify(outputs);
+    
+    const moat = this._getMoat();
+    const outbound = moat.scanOutbound(text);
+    
+    if (outbound.findings) {
+      this.findings.push(...outbound.findings);
+      for (const f of outbound.findings) {
+        if (this.onFinding) this.onFinding(f, 'chain_output');
+      }
+    }
+
+    if (!outbound.safe && this.mode === 'enforce') {
+      const err = new Error(`[ClawMoat] Output blocked: ${outbound.findings[0]?.evidence || 'leak detected'}`);
+      err.code = 'CLAWMOAT_BLOCKED';
+      err.findings = outbound.findings;
+      if (this.onBlock) this.onBlock(outbound.findings, 'chain_output');
+      throw err;
+    }
+  }
+
+  /**
+   * Called when tool starts — scan tool call
+   */
+  async handleToolStart(tool, input) {
+    const cs = this._getCodeScanner();
+    const text = typeof input === 'string' ? input : JSON.stringify(input);
+    const result = cs.scanCode(text, { tool: tool?.name });
+
+    if (result.findings.length > 0) {
+      this.findings.push(...result.findings);
+      for (const f of result.findings) {
+        if (this.onFinding) this.onFinding(f, 'tool_call');
+      }
+    }
+
+    if (!result.safe && this.mode === 'enforce') {
+      const err = new Error(`[ClawMoat] Tool call blocked: ${result.findings[0]?.evidence || 'dangerous code'}`);
+      err.code = 'CLAWMOAT_BLOCKED';
+      err.findings = result.findings;
+      if (this.onBlock) this.onBlock(result.findings, 'tool_call');
+      throw err;
+    }
+  }
+
+  /**
+   * Called when tool ends — scan result for injection
+   */
+  async handleToolEnd(output) {
+    const moat = this._getMoat();
+    const text = typeof output === 'string' ? output : JSON.stringify(output);
+    const result = moat.scanInbound(text);
+
+    if (result.findings) {
+      this.findings.push(...result.findings);
+    }
+
+    // Don't block tool results in most cases — just log
+    // The model needs to see the result to understand what happened
+  }
+
+  /**
+   * Get all findings collected during execution
+   */
+  getFindings() {
+    return [...this.findings];
+  }
+
+  /**
+   * Clear collected findings
+   */
+  clearFindings() {
+    this.findings = [];
+  }
+}
+
+/**
+ * Wrap a LangChain chain/agent with ClawMoat protection
+ * Convenience function for simple usage
+ * @param {Object} chain - LangChain chain or agent
+ * @param {Object} [opts] - ClawMoat options
+ * @returns {Object} Wrapped chain with security scanning
+ */
+function wrapChain(chain, opts = {}) {
+  const handler = new ClawMoatCallbackHandler(opts);
+  
+  // Add our handler to the chain's callbacks
+  if (!chain.callbacks) chain.callbacks = [];
+  chain.callbacks.push(handler);
+  
+  // Attach findings accessor
+  chain._clawmoat = handler;
+  chain.getSecurityFindings = () => handler.getFindings();
+  
+  return chain;
+}
+
+module.exports = {
+  ClawMoatCallbackHandler,
+  wrapChain,
+};