thumbgate 1.27.17 → 1.27.19

package/adapters/gcp/dfcx-webhook-gate.js

@@ -1,295 +0,0 @@
-'use strict';
-
-// adapters/gcp/dfcx-webhook-gate.js
-// -----------------------------------------------------------------------------
-// ThumbGate Enterprise — Dialogflow CX fulfillment webhook guardrail.
-//
-// Routes a Dialogflow CX (DFCX) fulfillment request through ThumbGate's
-// pre-action gate engine BEFORE the real fulfillment side-effect runs (DB/CRM/
-// billing write). If a configured policy gate denies the action, or the action
-// is a known same-session repeat, the side-effect is blocked and a safe DFCX
-// WebhookResponse is returned instead of executing it.
-//
-// Design: ThumbGate is a *guard in front of* the customer's existing fulfillment
-// function — it decides whether that function is allowed to run. It does not
-// replace it, mutate Playbooks, or call any Google API itself.
-//
-// This enterprise adapter is also listed in package.json "files" because
-// src/api/server.js loads it for the local enterprise Dialogflow dashboard routes.
-// The same module can still be deployed as Cloud Run / Cloud Functions middleware.
-// -----------------------------------------------------------------------------
-
-const path = require('path');
-
-const REPO_ROOT = path.join(__dirname, '..', '..');
-const gates = require(path.join(REPO_ROOT, 'scripts', 'gates-engine'));
-
-// Risk scorer is optional: it needs a trained model on disk. Degrade to null.
-let riskScorer = null;
-try {
-  riskScorer = require(path.join(REPO_ROOT, 'scripts', 'risk-scorer'));
-} catch (_) {
-  riskScorer = null;
-}
-
-// Deterministic stringify so the same parameter object always yields the same
-// action id (used for same-session repeat detection).
-function stableStringify(value) {
-  if (value === null || typeof value !== 'object') return JSON.stringify(value);
-  if (Array.isArray(value)) return '[' + value.map(stableStringify).join(',') + ']';
-  const keys = Object.keys(value).sort();
-  return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(value[k])).join(',') + '}';
-}
-
-// Map a DFCX WebhookRequest into a ThumbGate (toolName, toolInput) action.
-// DFCX fulfillment tag -> toolName ("dfcx:<tag>"); session parameters -> toolInput.
-// Supports both camelCase (standard DFCX) and snake_case (legacy/internal) formatting.
-function mapDfcxToAction(reqBody) {
-  const body = reqBody || {};
-  const fulfillmentInfo = body.fulfillmentInfo || body.fulfillment_info || {};
-  const tag = fulfillmentInfo.tag || 'unknown';
-  const sessionInfo = body.sessionInfo || body.session_info || {};
-  const params = sessionInfo.parameters || {};
-  const sessionId = sessionInfo.session || '';
-  return {
-    tag,
-    toolName: 'dfcx:' + tag,
-    toolInput: params,
-    sessionId,
-  };
-}
-
-// A DFCX webhook is fully untrusted (internet-facing), unlike a local coding
-// agent. These allowlists reject anything that could carry shell/path
-// metacharacters before the action ever reaches the gate engine.
-const SAFE_TOKEN = /^[A-Za-z0-9._\s-]{1,64}$/; // fulfillment tags, parameter names
-const SAFE_VALUE = /^[^`\;|&<>]{0,2048}$/;    // parameter string values (allow standard punctuation, block command injection)
-
-// Evaluate whether a DFCX fulfillment should be allowed to execute.
-// Returns { allowed, decision, gate, message, severity, repeat, risk, action }.
-function evaluateDfcxFulfillment(reqBody, opts = {}) {
-  const raw = mapDfcxToAction(reqBody);
-
-  // 0) Validate the untrusted webhook input and rebuild a SAFE action inline,
-  //    before any value reaches the gate engine. Block on any unsafe token/value
-  //    so attacker-controlled input cannot reach a path/command sink downstream.
-  const blockedUnsafe = (reason) => ({
-    allowed: false,
-    decision: 'deny',
-    gate: 'dfcx-unsafe-input',
-    message: 'The request contained unsafe input and was blocked.',
-    severity: 'critical',
-    repeat: false,
-    risk: null,
-    action: { tag: String(raw.tag), toolName: 'dfcx:unsafe', toolInput: {}, sessionId: raw.sessionId },
-    reason,
-  });
-  const tag = String(raw.tag);
-  if (!SAFE_TOKEN.test(tag)) return blockedUnsafe('unsafe fulfillment tag');
-  const toolName = 'dfcx:' + tag;
-  const toolInput = {};
-  const rawParams = raw.toolInput && typeof raw.toolInput === 'object' ? raw.toolInput : {};
-  for (const key of Object.keys(rawParams)) {
-    if (!SAFE_TOKEN.test(key)) return blockedUnsafe('unsafe parameter name');
-    const value = rawParams[key];
-    if (typeof value === 'string') {
-      if (!SAFE_VALUE.test(value)) return blockedUnsafe('unsafe parameter value');
-      toolInput[key] = value;
-    } else if (typeof value === 'number' || typeof value === 'boolean' || value === null) {
-      toolInput[key] = value;
-    }
-    // non-scalar values are intentionally dropped (never forwarded downstream).
-  }
-  const action = { tag, toolName, toolInput, sessionId: raw.sessionId };
-
-  // 1) Configured policy gates. The pilot configures DFCX-relevant gates (e.g.
-  //    "block dfcx:process-refund when amount > limit and not approved"). With no
-  //    custom config this is simply a no-op (allow).
-  let gateResult = null;
-  try {
-    gateResult = gates.evaluateGates(toolName, toolInput, opts.configPath);
-  } catch (_) {
-    gateResult = null;
-  }
-  const denied = Boolean(gateResult && gateResult.decision === 'deny');
-
-  // 2) Same-session repeat detection — works with zero custom config.
-  const actionId = action.toolName + ':' + stableStringify(action.toolInput);
-  let repeat = false;
-  if (typeof gates.hasAction === 'function') {
-    try { repeat = Boolean(gates.hasAction(actionId)); } catch (_) { repeat = false; }
-  }
-  if (typeof gates.trackAction === 'function') {
-    try { gates.trackAction(actionId, { source: 'dfcx', tag: action.tag }); } catch (_) { /* non-fatal */ }
-  }
-
-  // 3) Optional risk score (best-effort; null when no model is trained).
-  let risk = null;
-  if (riskScorer && typeof riskScorer.predictRisk === 'function') {
-    try {
-      const candidate = typeof riskScorer.buildRiskCandidate === 'function'
-        ? riskScorer.buildRiskCandidate({ toolName: action.toolName, toolInput: action.toolInput })
-        : { toolName: action.toolName, toolInput: action.toolInput };
-      const r = riskScorer.predictRisk(candidate);
-      risk = typeof r === 'number' ? r : (r && typeof r.risk === 'number' ? r.risk : null);
-    } catch (_) {
-      risk = null;
-    }
-  }
-
-  const blockOnRepeat = opts.blockOnRepeat !== false && repeat;
-  const allowed = !denied && !blockOnRepeat;
-
-  return {
-    allowed,
-    decision: allowed ? 'allow' : 'deny',
-    gate: denied ? gateResult.gate : (blockOnRepeat ? 'dfcx-repeat-action' : null),
-    message: denied
-      ? gateResult.message
-      : (blockOnRepeat ? 'This action was already attempted in this session and is blocked as a repeat.' : null),
-    severity: denied ? gateResult.severity : (blockOnRepeat ? 'high' : null),
-    repeat,
-    risk,
-    action,
-  };
-}
-
-// Build a DFCX WebhookResponse that safely halts the turn without side-effects.
-// Supports both camelCase (standard DFCX) and snake_case (legacy/internal) formatting.
-function buildBlockResponse(evaluation, opts = {}) {
-  const message = opts.blockedMessage
-    || 'This request was held by a safety policy and was not completed. A team member may follow up.';
-  const payload = {
-    fulfillment_response: { messages: [{ text: { text: [message] } }] },
-    fulfillmentResponse: { messages: [{ text: { text: [message] } }] },
-    session_info: {
-      parameters: {
-        thumbgate_blocked: true,
-        thumbgate_gate: evaluation.gate || null,
-        thumbgate_severity: evaluation.severity || null,
-      },
-    },
-    sessionInfo: {
-      parameters: {
-        thumbgate_blocked: true,
-        thumbgate_gate: evaluation.gate || null,
-        thumbgate_severity: evaluation.severity || null,
-      },
-    },
-  };
-  return payload;
-}
-
-// Annotate an allowed (passed-through) response so downstream flows can observe
-// that ThumbGate evaluated and permitted the turn. Never throws on odd shapes.
-// Populates both camelCase and snake_case variants to ensure compatibility.
-function annotateAllowed(response, evaluation) {
-  const base = response && typeof response === 'object' ? response : {};
-  
-  const sessionInfo = base.sessionInfo || base.session_info || {};
-  const params = sessionInfo.parameters && typeof sessionInfo.parameters === 'object' ? sessionInfo.parameters : {};
-  
-  const updatedParams = Object.assign({}, params, {
-    thumbgate_blocked: false,
-    thumbgate_risk: evaluation.risk,
-  });
-  
-  const updatedSessionInfo = Object.assign({}, sessionInfo, {
-    parameters: updatedParams,
-  });
-  
-  const updated = Object.assign({}, base, {
-    session_info: updatedSessionInfo,
-    sessionInfo: updatedSessionInfo,
-  });
-  
-  if (base.fulfillment_response) {
-    updated.fulfillmentResponse = base.fulfillment_response;
-  } else if (base.fulfillmentResponse) {
-    updated.fulfillment_response = base.fulfillmentResponse;
-  }
-  
-  return updated;
-}
-
-// Guard a DFCX webhook: run the gate; only invoke the real fulfillment when
-// allowed. `fulfill(reqBody) -> WebhookResponse` is the customer's existing
-// fulfillment function. Returns { blocked, response, evaluation }.
-async function guardDfcxWebhook(reqBody, fulfill, opts = {}) {
-  const evaluation = evaluateDfcxFulfillment(reqBody, opts);
-  if (!evaluation.allowed) {
-    return { blocked: true, response: buildBlockResponse(evaluation, opts), evaluation };
-  }
-  const fulfilled = typeof fulfill === 'function'
-    ? await fulfill(reqBody)
-    : { fulfillment_response: { messages: [] } };
-  return { blocked: false, response: annotateAllowed(fulfilled, evaluation), evaluation };
-}
-
-// Reject bodies larger than this. A DFCX WebhookRequest is small (a few KB); an
-// unbounded reader on an internet-facing endpoint is a memory-exhaustion vector.
-const MAX_BODY_BYTES = 1024 * 1024; // 1 MiB
-
-// Read a JSON request body from a Node IncomingMessage stream, with a hard size
-// cap so a malicious/misconfigured caller cannot exhaust memory.
-function readJsonBody(req) {
-  return new Promise((resolve, reject) => {
-    let raw = '';
-    let bytes = 0;
-    let aborted = false;
-    req.on('data', (chunk) => {
-      if (aborted) return;
-      bytes += chunk.length;
-      if (bytes > MAX_BODY_BYTES) {
-        aborted = true;
-        const err = new Error('request body exceeds ' + MAX_BODY_BYTES + ' bytes');
-        err.statusCode = 413;
-        try { req.destroy(); } catch (_) { /* ignore */ }
-        return reject(err);
-      }
-      raw += chunk;
-    });
-    req.on('end', () => {
-      if (aborted) return;
-      if (!raw) return resolve({});
-      try { resolve(JSON.parse(raw)); } catch (e) { reject(e); }
-    });
-    req.on('error', reject);
-  });
-}
-
-// Plain Node HTTP handler for Cloud Run / Cloud Functions (no framework dep).
-function createHttpHandler(fulfill, opts = {}) {
-  return async function handler(req, res) {
-    try {
-      const body = req && req.body && typeof req.body === 'object'
-        ? req.body
-        : await readJsonBody(req);
-      const { response, evaluation } = await guardDfcxWebhook(body, fulfill, opts);
-      if (typeof opts.onDecision === 'function') {
-        try { opts.onDecision(evaluation); } catch (_) { /* observability must not break the turn */ }
-      }
-      res.statusCode = 200;
-      res.setHeader('content-type', 'application/json');
-      res.end(JSON.stringify(response));
-    } catch (err) {
-      // Log internally for operators; never leak error/stack details to the
-      // external caller (Dialogflow CX / the open internet).
-      try { console.error('thumbgate-dfcx-gate error:', err); } catch (_) { /* ignore */ }
-      res.statusCode = 500;
-      res.setHeader('content-type', 'application/json');
-      res.end(JSON.stringify({ error: 'thumbgate-dfcx-gate-failure' }));
-    }
-  };
-}
-
-module.exports = {
-  mapDfcxToAction,
-  evaluateDfcxFulfillment,
-  buildBlockResponse,
-  annotateAllowed,
-  guardDfcxWebhook,
-  createHttpHandler,
-  // exposed for tests
-  stableStringify,
-};

package/adapters/letta/README.md

@@ -1,41 +0,0 @@
-# Letta Adapter
-
-Letta is a stateful-agent runtime with persistent memory, MCP tools, custom server tools, and client-side tool execution. ThumbGate should not compete with that memory surface. ThumbGate should sit underneath it as the deterministic local enforcement layer.
-
-## Integration Pattern
-
-Use `thumbgate-letta-adapter.js` to wrap Letta tool execution:
-
-1. Letta agent proposes a tool call.
-2. The wrapper normalizes the Letta event into ThumbGate's provider-action schema.
-3. Your app calls ThumbGate's local gate-check transport.
-4. If ThumbGate blocks or requires approval, the tool executor is never called.
-5. If allowed, the original Letta tool executes normally.
-
-This works for the two practical Letta surfaces:
-
-- **MCP tools**: Letta forwards the tool call through the Letta server to an MCP server. Wrap the forwarding boundary or expose the downstream tool through a ThumbGate-guarded MCP server.
-- **Client tools**: Letta asks your client application to execute a tool locally. Wrap the client tool handler with `createLettaToolGuard`.
-
-## Example
-
-```js
-const { createLettaToolGuard } = require('./thumbgate-letta-adapter');
-
-const guardedTool = createLettaToolGuard({
-  gateCheck: async (normalizedAction) => thumbgateGateCheck(normalizedAction),
-  executeTool: async (lettaEvent) => runOriginalTool(lettaEvent),
-});
-
-await guardedTool({
-  agentId: 'agent-123',
-  clientTool: {
-    name: 'shell',
-    input: { command: 'git push --force origin main' },
-  },
-});
-```
-
-## Positioning
-
-Letta helps agents remember and operate with state. ThumbGate helps teams decide what those agents are allowed to do next. The moat is adapter coverage: ThumbGate works under memory-first runtimes instead of asking buyers to replace them.

package/adapters/letta/thumbgate-letta-adapter.js

@@ -1,133 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-const { normalizeProviderAction } = require('../../scripts/provider-action-normalizer');
-
-function asObject(value) {
-  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
-}
-
-function firstString(...values) {
-  for (const value of values) {
-    const text = String(value || '').trim();
-    if (text) return text;
-  }
-  return '';
-}
-
-function extractLettaToolCall(input = {}) {
-  const event = asObject(input);
-  const toolCall = asObject(event.toolCall || event.tool_call || event.lettaToolCall);
-  const functionCall = asObject(toolCall.function || event.function);
-  const mcp = asObject(event.mcp || event.mcpToolCall);
-  const clientTool = asObject(event.clientTool || event.client_tool);
-  const params = asObject(event.params);
-
-  const name = firstString(
-    event.toolName,
-    event.name,
-    toolCall.name,
-    functionCall.name,
-    clientTool.name,
-    mcp.name,
-    params.name
-  );
-  const args = asObject(
-    event.arguments
-      || event.args
-      || event.input
-      || toolCall.arguments
-      || toolCall.input
-      || functionCall.arguments
-      || clientTool.arguments
-      || clientTool.input
-      || mcp.arguments
-      || params.arguments
-  );
-
-  return {
-    id: firstString(event.id, event.toolCallId, event.tool_call_id, toolCall.id, clientTool.id),
-    name,
-    arguments: args,
-    server: firstString(event.mcpServer, mcp.server, params.server),
-    surface: firstString(event.surface, event.executionSurface, clientTool.name ? 'client-tool' : mcp.name || params.name ? 'mcp-tool' : 'server-tool'),
-  };
-}
-
-function normalizeLettaAction(input = {}) {
-  const event = asObject(input);
-  const toolCall = extractLettaToolCall(event);
-
-  const normalized = normalizeProviderAction({
-    ...event,
-    provider: 'letta',
-    toolCall: {
-      id: toolCall.id,
-      name: toolCall.name,
-      input: toolCall.arguments,
-    },
-    toolName: toolCall.name,
-    input: toolCall.arguments,
-    mcpServer: toolCall.server,
-  });
-
-  return {
-    ...normalized,
-    provider: 'letta',
-    agentRuntime: 'letta',
-    letta: {
-      agentId: firstString(event.agentId, event.agent_id),
-      messageId: firstString(event.messageId, event.message_id),
-      surface: toolCall.surface,
-      toolCallId: toolCall.id,
-    },
-  };
-}
-
-function normalizeGateDecision(decision = {}) {
-  const value = asObject(decision);
-  const raw = firstString(value.decision, value.mode, value.action, value.status).toLowerCase();
-  const blocked = value.allowed === false
-    || value.accepted === false
-    || value.blocked === true
-    || ['block', 'deny', 'denied', 'reject', 'rejected'].includes(raw);
-  const approvalRequired = value.requiresApproval === true || raw === 'approve';
-  return {
-    allowed: !blocked && !approvalRequired,
-    blocked,
-    approvalRequired,
-    reason: firstString(value.reason, value.message, Array.isArray(value.reasons) ? value.reasons.join('; ') : ''),
-    raw: value,
-  };
-}
-
-function createLettaToolGuard({ gateCheck, executeTool, onDecision } = {}) {
-  if (typeof gateCheck !== 'function') {
-    throw new TypeError('createLettaToolGuard requires a gateCheck function');
-  }
-  if (typeof executeTool !== 'function') {
-    throw new TypeError('createLettaToolGuard requires an executeTool function');
-  }
-
-  return async function guardedLettaTool(input = {}) {
-    const normalizedAction = normalizeLettaAction(input);
-    const decision = normalizeGateDecision(await gateCheck(normalizedAction));
-    if (typeof onDecision === 'function') {
-      await onDecision({ normalizedAction, decision });
-    }
-    if (!decision.allowed) {
-      const error = new Error(decision.reason || 'ThumbGate blocked this Letta tool call before execution.');
-      error.code = decision.approvalRequired ? 'THUMBGATE_APPROVAL_REQUIRED' : 'THUMBGATE_BLOCKED';
-      error.thumbgate = { normalizedAction, decision };
-      throw error;
-    }
-    return executeTool(input, { normalizedAction, decision });
-  };
-}
-
-module.exports = {
-  createLettaToolGuard,
-  extractLettaToolCall,
-  normalizeGateDecision,
-  normalizeLettaAction,
-};

package/adapters/policy-engine/ethicore-guardian-client.js

@@ -1,68 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-const DEFAULT_ENDPOINT = 'https://api.oraclestechnologies.com/v1/guardian/analyze';
-
-function requireApiKey(env = process.env) {
-  const key = env.ETHICORE_API_KEY || env.GUARDIAN_API_KEY || env.ORACLES_GUARDIAN_API_KEY;
-  if (!key) {
-    throw new Error('ETHICORE_API_KEY env var is required');
-  }
-  return key;
-}
-
-async function analyzeText(text, options = {}) {
-  if (!String(text || '').trim()) {
-    throw new Error('analyzeText requires text');
-  }
-
-  const env = options.env || process.env;
-  const endpoint = options.endpoint || env.ETHICORE_GUARDIAN_ENDPOINT || DEFAULT_ENDPOINT;
-  const apiKey = options.apiKey || requireApiKey(env);
-  const fetchImpl = options.fetch || fetch;
-
-  const response = await fetchImpl(endpoint, {
-    method: 'POST',
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({ text }),
-  });
-
-  const bodyText = await response.text();
-  let body = bodyText;
-  try {
-    body = bodyText ? JSON.parse(bodyText) : {};
-  } catch {
-    // Keep non-JSON body for diagnostics.
-  }
-
-  if (!response.ok) {
-    throw new Error(`Ethicore Guardian API ${response.status}: ${typeof body === 'string' ? body : JSON.stringify(body)}`);
-  }
-
-  return body;
-}
-
-function createEthicorePolicyCheck(options = {}) {
-  return async function ethicorePolicyCheck(action = {}) {
-    const toolText = [
-      action.toolName,
-      action.actionType,
-      action.command,
-      action.path,
-      action.url,
-      action.input ? JSON.stringify(action.input) : '',
-    ].filter(Boolean).join('\n');
-
-    return analyzeText(toolText || JSON.stringify(action), options);
-  };
-}
-
-module.exports = {
-  DEFAULT_ENDPOINT,
-  analyzeText,
-  createEthicorePolicyCheck,
-  requireApiKey,
-};