@tangle-network/agent-integrations 0.2.1 → 0.3.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import { createHmac as createHmac3, randomUUID, timingSafeEqual as timingSafeEqual2 } from "crypto";
+import { createHmac as createHmac3, randomUUID as randomUUID2, timingSafeEqual as timingSafeEqual2 } from "crypto";
 
 // src/connectors/types.ts
 var ResourceContention = class extends Error {
@@ -2640,6 +2640,434 @@ var slackEventsConnector = {
   }
 };
 
+// src/catalog.ts
+var riskRank = {
+  read: 0,
+  write: 1,
+  destructive: 2
+};
+function integrationToolName(providerId, connectorId, actionId) {
+  return `int_${encodeToolPart(providerId)}_${encodeToolPart(connectorId)}_${encodeToolPart(actionId)}`;
+}
+function parseIntegrationToolName(name) {
+  const parts = name.split("_");
+  if (parts.length !== 4 || parts[0] !== "int") {
+    throw new Error(`Invalid integration tool name: ${name}`);
+  }
+  return {
+    providerId: decodeToolPart(parts[1]),
+    connectorId: decodeToolPart(parts[2]),
+    actionId: decodeToolPart(parts[3])
+  };
+}
+function buildIntegrationToolCatalog(connectors) {
+  const tools = [];
+  for (const connector of connectors) {
+    for (const action of connector.actions) {
+      const tags = unique([
+        connector.id,
+        connector.providerId,
+        connector.title,
+        connector.category,
+        action.id,
+        action.title,
+        action.risk,
+        action.dataClass,
+        ...connector.scopes ?? [],
+        ...action.requiredScopes ?? []
+      ].flatMap(tokenize));
+      tools.push({
+        name: integrationToolName(connector.providerId, connector.id, action.id),
+        title: `${connector.title}: ${action.title}`,
+        description: action.description ?? `${action.risk} action ${action.id} on ${connector.title}`,
+        providerId: connector.providerId,
+        connectorId: connector.id,
+        connectorTitle: connector.title,
+        category: connector.category,
+        action,
+        risk: action.risk,
+        dataClass: action.dataClass,
+        requiredScopes: action.requiredScopes,
+        inputSchema: action.inputSchema,
+        outputSchema: action.outputSchema,
+        tags
+      });
+    }
+  }
+  return tools;
+}
+function searchIntegrationTools(catalog, query, filters = {}) {
+  const terms = tokenize(query);
+  const filtered = catalog.filter((tool) => {
+    if (filters.providerId && tool.providerId !== filters.providerId) return false;
+    if (filters.connectorId && tool.connectorId !== filters.connectorId) return false;
+    if (filters.category && tool.category !== filters.category) return false;
+    if (filters.dataClass && tool.dataClass !== filters.dataClass) return false;
+    if (filters.maxRisk && riskRank[tool.risk] > riskRank[filters.maxRisk]) return false;
+    return true;
+  });
+  const scored = filtered.map((tool) => scoreTool(tool, terms));
+  return scored.filter((result) => terms.length === 0 || result.score > 0).sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name)).slice(0, filters.limit ?? 20);
+}
+function toMcpTools(tools) {
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: `${tool.title}. ${tool.description}`,
+    inputSchema: tool.inputSchema ?? {
+      type: "object",
+      additionalProperties: true,
+      properties: {}
+    }
+  }));
+}
+function scoreTool(tool, terms) {
+  if (terms.length === 0) return { tool, score: 1, matched: [] };
+  const haystack = new Set(tool.tags);
+  const matched = [];
+  let score = 0;
+  for (const term of terms) {
+    if (haystack.has(term)) {
+      matched.push(term);
+      score += 4;
+      continue;
+    }
+    if (tool.tags.some((tag) => tag.includes(term))) {
+      matched.push(term);
+      score += 1;
+    }
+  }
+  if (tool.risk === "read") score += 0.25;
+  return { tool, score, matched: unique(matched) };
+}
+function tokenize(value) {
+  return value.toLowerCase().split(/[^a-z0-9]+/g).map((part) => part.trim()).filter(Boolean);
+}
+function encodeToolPart(value) {
+  return Buffer.from(value, "utf8").toString("base64url");
+}
+function decodeToolPart(value) {
+  return Buffer.from(value, "base64url").toString("utf8");
+}
+function unique(values) {
+  return [...new Set(values)];
+}
+
+// src/policy.ts
+import { randomUUID } from "crypto";
+var StaticIntegrationPolicyEngine = class {
+  rules;
+  defaultReadEffect;
+  defaultWriteEffect;
+  defaultDestructiveEffect;
+  now;
+  constructor(options = {}) {
+    this.rules = options.rules ?? [];
+    this.defaultReadEffect = options.defaultReadEffect ?? "allow";
+    this.defaultWriteEffect = options.defaultWriteEffect ?? "require_approval";
+    this.defaultDestructiveEffect = options.defaultDestructiveEffect ?? "deny";
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  decide(ctx) {
+    const action = ctx.action;
+    if (!action) return { decision: "deny", reason: "Integration action is missing from connector catalog." };
+    const matched = this.rules.find((rule) => ruleMatches(rule, ctx));
+    const effect = matched?.effect ?? this.defaultEffect(action.risk);
+    const reason = matched?.reason ?? defaultReason(effect, action.risk);
+    if (effect === "allow") return { decision: "allow", reason, metadata: matched ? { ruleId: matched.id } : void 0 };
+    if (effect === "deny") return { decision: "deny", reason, metadata: matched ? { ruleId: matched.id } : void 0 };
+    return {
+      decision: "require_approval",
+      reason,
+      approval: buildApprovalRequest(ctx, reason, this.now()),
+      metadata: matched ? { ruleId: matched.id } : void 0
+    };
+  }
+  defaultEffect(risk) {
+    if (risk === "read") return this.defaultReadEffect;
+    if (risk === "write") return this.defaultWriteEffect;
+    return this.defaultDestructiveEffect;
+  }
+};
+function createDefaultIntegrationPolicyEngine(options = {}) {
+  return new StaticIntegrationPolicyEngine(options);
+}
+function buildApprovalRequest(ctx, reason, requestedAt) {
+  if (!ctx.action) {
+    throw new Error("Cannot build approval request without an action descriptor.");
+  }
+  return {
+    id: `approval_${randomUUID()}`,
+    connectionId: ctx.connection.id,
+    providerId: ctx.connection.providerId,
+    connectorId: ctx.connection.connectorId,
+    action: ctx.request.action,
+    actor: { type: ctx.subject.type, id: ctx.subject.id },
+    risk: ctx.action.risk,
+    dataClass: ctx.action.dataClass,
+    reason,
+    requestedAt: requestedAt.toISOString(),
+    inputPreview: previewInput(ctx.request.input)
+  };
+}
+function redactApprovalRequest(request) {
+  return {
+    ...request,
+    inputPreview: redactUnknown(request.inputPreview)
+  };
+}
+function ruleMatches(rule, ctx) {
+  if (!ctx.action) return false;
+  if (rule.providerId && rule.providerId !== ctx.connection.providerId) return false;
+  if (rule.connectorId && rule.connectorId !== ctx.connection.connectorId) return false;
+  if (rule.action && rule.action !== ctx.request.action) return false;
+  if (rule.risk && rule.risk !== ctx.action.risk) return false;
+  if (rule.maxRisk && riskRank2(ctx.action.risk) > riskRank2(rule.maxRisk)) return false;
+  if (rule.dataClass && rule.dataClass !== ctx.action.dataClass) return false;
+  return true;
+}
+function riskRank2(risk) {
+  if (risk === "read") return 0;
+  if (risk === "write") return 1;
+  return 2;
+}
+function defaultReason(effect, risk) {
+  if (effect === "allow") return `${risk} integration action allowed by default policy.`;
+  if (effect === "deny") return `${risk} integration action denied by default policy.`;
+  return `${risk} integration action requires approval by default policy.`;
+}
+function previewInput(input) {
+  return redactUnknown(input);
+}
+function redactUnknown(value) {
+  if (Array.isArray(value)) return value.map(redactUnknown);
+  if (!value || typeof value !== "object") return value;
+  const out = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (/token|secret|password|authorization|api[_-]?key|credential/i.test(key)) {
+      out[key] = "[REDACTED]";
+    } else {
+      out[key] = redactUnknown(child);
+    }
+  }
+  return out;
+}
+
+// src/sandbox.ts
+function buildIntegrationInvocationEnvelope(input) {
+  const parsed = parseIntegrationToolName(input.toolName);
+  return {
+    kind: "integration.invocation",
+    capabilityToken: input.capabilityToken,
+    toolName: input.toolName,
+    action: parsed.actionId,
+    input: input.args,
+    idempotencyKey: input.idempotencyKey,
+    dryRun: input.dryRun,
+    metadata: input.metadata
+  };
+}
+function invocationRequestFromEnvelope(envelope) {
+  return {
+    action: envelope.action,
+    input: envelope.input,
+    idempotencyKey: envelope.idempotencyKey,
+    dryRun: envelope.dryRun,
+    metadata: envelope.metadata
+  };
+}
+function redactInvocationEnvelope(envelope) {
+  return {
+    ...envelope,
+    capabilityToken: "[REDACTED]",
+    input: redactUnknown2(envelope.input)
+  };
+}
+function redactCapability(capability) {
+  return {
+    ...capability,
+    metadata: redactUnknown2(capability.metadata)
+  };
+}
+function normalizeIntegrationResult(result) {
+  const output = result.output;
+  if (!result.ok && output?.approvalRequired === true && output.approval) {
+    return {
+      status: "approval_required",
+      action: result.action,
+      approval: output.approval,
+      metadata: result.metadata
+    };
+  }
+  if (!result.ok) {
+    return {
+      status: "failed",
+      action: result.action,
+      error: String(result.output ?? result.warnings?.[0] ?? "integration action failed"),
+      metadata: result.metadata
+    };
+  }
+  return {
+    status: "ok",
+    action: result.action,
+    output: result.output,
+    metadata: result.metadata
+  };
+}
+function redactUnknown2(value) {
+  if (Array.isArray(value)) return value.map(redactUnknown2);
+  if (!value || typeof value !== "object") return value;
+  const out = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (/token|secret|password|authorization|api[_-]?key|credential/i.test(key)) {
+      out[key] = "[REDACTED]";
+    } else {
+      out[key] = redactUnknown2(child);
+    }
+  }
+  return out;
+}
+
+// src/adapter-provider.ts
+function createConnectorAdapterProvider(options) {
+  const providerId = options.id ?? "first-party";
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  const adapters = /* @__PURE__ */ new Map();
+  for (const adapter of options.adapters) {
+    adapters.set(adapter.manifest.kind, adapter);
+  }
+  return {
+    id: providerId,
+    kind: options.kind ?? "first_party",
+    listConnectors: () => [...adapters.values()].map((adapter) => manifestToConnector(providerId, adapter)),
+    async invokeAction(connection, request) {
+      const adapter = adapters.get(connection.connectorId);
+      if (!adapter) {
+        throw new IntegrationError(`Connector adapter ${connection.connectorId} not found.`, "connector_not_found");
+      }
+      const capability = adapter.manifest.capabilities.find((candidate) => candidate.name === request.action);
+      if (!capability) {
+        throw new IntegrationError(`Capability ${request.action} is not defined by ${connection.connectorId}.`, "action_not_found");
+      }
+      const source = await options.resolveDataSource(connection);
+      const invocation = {
+        source,
+        capabilityName: request.action,
+        args: toRecord(request.input),
+        idempotencyKey: request.idempotencyKey ?? `idem_${connection.id}_${request.action}_${now().getTime()}`,
+        expectedEtag: typeof request.metadata?.expectedEtag === "string" ? request.metadata.expectedEtag : void 0,
+        callSessionId: typeof request.metadata?.callSessionId === "string" ? request.metadata.callSessionId : void 0
+      };
+      if (capability.class === "read") {
+        if (!adapter.executeRead) {
+          throw new IntegrationError(`Connector ${connection.connectorId} does not implement reads.`, "action_not_found");
+        }
+        const result = await adapter.executeRead(invocation);
+        return readResultToAction(request, result);
+      }
+      if (capability.class === "mutation") {
+        if (!adapter.executeMutation) {
+          throw new IntegrationError(`Connector ${connection.connectorId} does not implement mutations.`, "action_not_found");
+        }
+        const result = await adapter.executeMutation(invocation);
+        return mutationResultToAction(request, result);
+      }
+      throw new IntegrationError(`Capability ${request.action} is not invokable as an action.`, "action_not_found");
+    }
+  };
+}
+function manifestToConnector(providerId, adapter) {
+  const manifest = adapter.manifest;
+  return {
+    id: manifest.kind,
+    providerId,
+    title: manifest.displayName,
+    category: mapCategory(manifest.category),
+    auth: mapAuth(manifest.auth.kind),
+    scopes: manifest.auth.kind === "oauth2" ? manifest.auth.scopes : [],
+    actions: manifest.capabilities.filter((capability) => capability.class === "read" || capability.class === "mutation").map((capability) => ({
+      id: capability.name,
+      title: titleFromName(capability.name),
+      risk: capability.class === "read" ? "read" : capability.externalEffect ? "destructive" : "write",
+      requiredScopes: capability.requiredScopes ?? [],
+      dataClass: inferDataClass(manifest.category),
+      description: capability.description,
+      approvalRequired: capability.class === "mutation",
+      inputSchema: capability.parameters
+    }))
+  };
+}
+function readResultToAction(request, result) {
+  return {
+    ok: true,
+    action: request.action,
+    output: result.data,
+    metadata: {
+      etag: result.etag,
+      fetchedAt: result.fetchedAt
+    }
+  };
+}
+function mutationResultToAction(request, result) {
+  if (result.status === "committed") {
+    return {
+      ok: true,
+      action: request.action,
+      output: result.data,
+      metadata: {
+        etagAfter: result.etagAfter,
+        committedAt: result.committedAt,
+        idempotentReplay: result.idempotentReplay
+      }
+    };
+  }
+  if (result.status === "conflict") {
+    return {
+      ok: false,
+      action: request.action,
+      output: {
+        conflict: true,
+        message: result.message,
+        alternatives: result.alternatives,
+        currentState: result.currentState
+      }
+    };
+  }
+  return {
+    ok: false,
+    action: request.action,
+    output: {
+      rateLimited: true,
+      retryAfterMs: result.retryAfterMs,
+      message: result.message
+    }
+  };
+}
+function mapAuth(kind) {
+  if (kind === "oauth2") return "oauth2";
+  if (kind === "api-key") return "api_key";
+  if (kind === "none") return "none";
+  return "custom";
+}
+function mapCategory(category) {
+  if (category === "comms") return "chat";
+  if (category === "spreadsheet") return "database";
+  if (category === "doc") return "docs";
+  if (category === "commerce") return "workflow";
+  return category === "other" ? "other" : category;
+}
+function inferDataClass(category) {
+  if (category === "commerce") return "sensitive";
+  if (category === "webhook") return "internal";
+  return "private";
+}
+function titleFromName(name) {
+  return name.split(/[._-]/g).filter(Boolean).map((part) => part.slice(0, 1).toUpperCase() + part.slice(1)).join(" ");
+}
+function toRecord(input) {
+  if (input && typeof input === "object" && !Array.isArray(input)) return input;
+  return {};
+}
+
 // src/index.ts
 var IntegrationError = class extends Error {
   constructor(message, code) {
@@ -2671,6 +3099,7 @@ var IntegrationHub = class {
   store;
   capabilitySecret;
   guard;
+  policy;
   now;
   constructor(options) {
     if (!options.capabilitySecret) {
@@ -2680,6 +3109,7 @@ var IntegrationHub = class {
     this.store = options.store;
     this.capabilitySecret = options.capabilitySecret;
     this.guard = options.guard;
+    this.policy = options.policy;
     this.now = options.now ?? (() => /* @__PURE__ */ new Date());
   }
   async listConnectors() {
@@ -2709,11 +3139,11 @@ var IntegrationHub = class {
     assertScopes(connection, request.scopes);
     const now = this.now();
     const capability = {
-      id: `cap_${randomUUID()}`,
+      id: `cap_${randomUUID2()}`,
       subject: request.subject,
       connectionId: request.connectionId,
-      scopes: unique(request.scopes),
-      allowedActions: unique(request.allowedActions),
+      scopes: unique2(request.scopes),
+      allowedActions: unique2(request.allowedActions),
       issuedAt: now.toISOString(),
       expiresAt: new Date(now.getTime() + request.ttlMs).toISOString(),
       metadata: request.metadata
@@ -2741,6 +3171,25 @@ var IntegrationHub = class {
     assertScopes(connection, action.requiredScopes);
     assertScopes({ ...connection, grantedScopes: capability.scopes }, action.requiredScopes);
     const fullRequest = { ...request, connectionId: connection.id };
+    if (this.policy) {
+      const decision = await this.policy.decide({
+        connection,
+        request: fullRequest,
+        action,
+        subject: capability.subject
+      });
+      if (decision.decision === "deny") {
+        throw new IntegrationError(decision.reason, "policy_denied");
+      }
+      if (decision.decision === "require_approval") {
+        return {
+          ok: false,
+          action: request.action,
+          output: { approvalRequired: true, approval: decision.approval },
+          metadata: { policyDecision: decision.decision, reason: decision.reason, ...decision.metadata }
+        };
+      }
+    }
     const proceed = () => Promise.resolve(provider.invokeAction(connection, fullRequest));
     if (this.guard) {
       return this.guard.invokeAction({ connection, request: fullRequest, action }, proceed);
@@ -2940,7 +3389,7 @@ function base64UrlEncode(value) {
 function base64UrlDecode(value) {
   return Buffer.from(value, "base64url").toString("utf8");
 }
-function unique(values) {
+function unique2(values) {
   return [...new Set(values)];
 }
 export {
@@ -2951,9 +3400,15 @@ export {
   IntegrationError,
   IntegrationHub,
   ResourceContention,
+  StaticIntegrationPolicyEngine,
   _resetPendingFlowsForTests,
   assertValidConnectorManifest,
+  buildApprovalRequest,
+  buildIntegrationInvocationEnvelope,
+  buildIntegrationToolCatalog,
   consumePendingFlow,
+  createConnectorAdapterProvider,
+  createDefaultIntegrationPolicyEngine,
   createHttpIntegrationProvider,
   createMockIntegrationProvider,
   exchangeAuthorizationCode,
@@ -2961,17 +3416,27 @@ export {
   googleCalendar,
   googleSheets,
   hubspot,
+  integrationToolName,
+  invocationRequestFromEnvelope,
+  manifestToConnector,
   microsoftCalendar,
+  normalizeIntegrationResult,
   notionDatabase,
+  parseIntegrationToolName,
   parseStripeSignatureHeader,
+  redactApprovalRequest,
+  redactCapability,
+  redactInvocationEnvelope,
   refreshAccessToken,
   sanitizeConnection,
+  searchIntegrationTools,
   signCapability,
   slack,
   slackEventsConnector,
   startOAuthFlow,
   stripePackConnector,
   stripeWebhookReceiverConnector,
+  toMcpTools,
   twilioSmsConnector,
   validateConnectorManifest,
   verifyCapabilityToken,