@tangle-network/agent-integrations 0.4.0 → 0.5.0

package/README.md

@@ -58,7 +58,10 @@ The SDK surface for that flow is:
 - `toMcpTools` for MCP-compatible tool export.
 - `IntegrationHub.issueCapability` for scoped sandbox handoff.
 - `createDefaultIntegrationPolicyEngine` for allow / approval / deny decisions.
-- `buildIntegrationInvocationEnvelope` for sandbox-safe tool calls.
+- `buildIntegrationInvocationEnvelope` and
+  `validateIntegrationInvocationEnvelope` for sandbox-safe tool calls with
+  action/tool consistency, idempotency-key, metadata-shape, known-tool, and
+  input-size checks.
 - `createConnectorAdapterProvider` to run first-party adapters through the hub.
 
 ```ts
@@ -143,6 +146,7 @@ without changing agent code.
 - Capability tokens contain no provider credential.
 - Secret refs are redacted from public telemetry.
 - Write/destructive actions can be policy-gated.
+- Sandbox invocation envelopes are validated before conversion to hub requests.
 - Action invocation checks connection ownership, status, scopes, allowed
   actions, and expiration.
 - Optional `IntegrationActionGuard` wraps every action invocation for

package/dist/index.d.ts

@@ -533,6 +533,25 @@ interface GenericHmacVerifyOptions {
     lowercaseHex?: boolean;
 }
 declare function verifyHmacSignature(rawBody: string, signatureHeader: string, secret: string, options?: GenericHmacVerifyOptions): boolean;
+interface TwilioVerifyOptions {
+    /** Skip verification when the auth token isn't configured. Useful in
+     *  dev where the receiver wants to accept any payload. Default `false`
+     *  — production should always require a configured token. */
+    skipWhenAuthTokenMissing?: boolean;
+    /** When true, sign the raw body instead of the URL-encoded sorted-params
+     *  reduction. Twilio uses raw-body signing for `application/json`
+     *  webhook bodies. Default `false`. */
+    bodyAsRaw?: boolean;
+    /** When `bodyAsRaw` is true, the raw body to sign. Ignored otherwise. */
+    rawBody?: string;
+}
+/** Verify a Twilio webhook signature. */
+declare function verifyTwilioSignature(input: {
+    authToken: string | null | undefined;
+    signatureHeader: string | string[] | undefined;
+    fullUrl: string | null | undefined;
+    params: Record<string, string> | undefined;
+}, options?: TwilioVerifyOptions): boolean;
 declare function firstHeader(headers: Record<string, string | string[] | undefined>, name: string): string | undefined;
 
 /**
@@ -1008,6 +1027,11 @@ interface IntegrationInvocationEnvelope {
     dryRun?: boolean;
     metadata?: Record<string, unknown>;
 }
+interface IntegrationInvocationEnvelopeValidationOptions {
+    connectors?: IntegrationConnector[];
+    maxInputBytes?: number;
+    requireKnownTool?: boolean;
+}
 type NormalizedIntegrationResult = {
     status: 'ok';
     action: string;
@@ -1033,6 +1057,7 @@ declare function buildIntegrationInvocationEnvelope(input: {
     metadata?: Record<string, unknown>;
 }): IntegrationInvocationEnvelope;
 declare function invocationRequestFromEnvelope(envelope: IntegrationInvocationEnvelope): InvokeWithCapabilityRequest;
+declare function validateIntegrationInvocationEnvelope(envelope: IntegrationInvocationEnvelope, options?: IntegrationInvocationEnvelopeValidationOptions): void;
 declare function redactInvocationEnvelope(envelope: IntegrationInvocationEnvelope): Omit<IntegrationInvocationEnvelope, 'capabilityToken'> & {
     capabilityToken: '[REDACTED]';
 };
@@ -1399,4 +1424,4 @@ declare function createHttpIntegrationProvider(options: HttpIntegrationProviderO
 declare function signCapability(capability: IntegrationCapability, secret: string): string;
 declare function verifyCapabilityToken(token: string, secret: string): IntegrationCapability;
 
-export { type AuthSpec, type CASStrategy, type Capability, type CapabilityClass, type CapabilityMutation, type CapabilityMutationResult, type CapabilityParameterSchema, type CapabilityRead, type CapabilityReadResult, type CompleteAuthRequest, type ConnectorAdapter, type ConnectorAdapterProviderOptions, type ConnectorCredentials, type ConnectorInvocation, type ConnectorManifest, type ConnectorManifestValidationIssue, type ConnectorManifestValidationResult, type ConsistencyModel, CredentialsExpired, DEFAULT_SIGNATURE_TOLERANCE_SECONDS, type DataSourceMetadata, type EventHandlerResult, type ExchangeCodeInput, type GenericHmacVerifyOptions, type GoogleCalendarOptions, type GoogleSheetsOptions, type GraphqlOperationSpec, type HttpIntegrationProviderOptions, type HubSpotOptions, type ImportCatalogOptions, InMemoryConnectionStore, InMemoryOAuthFlowStore, type InboundEvent, type IntegrationActionGuard, type IntegrationActionRequest, type IntegrationActionResult, type IntegrationActionRisk, type IntegrationActor, type IntegrationApprovalRequest, type IntegrationApprovalResolution, type IntegrationCapability, type IntegrationConnection, type IntegrationConnectionStore, type IntegrationConnector, type IntegrationConnectorAction, type IntegrationConnectorCategory, type IntegrationConnectorTrigger, type IntegrationDataClass, IntegrationError, type IntegrationGuardContext, IntegrationHub, type IntegrationHubOptions, type IntegrationInvocationEnvelope, type IntegrationPolicyDecision, type IntegrationPolicyEffect, type IntegrationPolicyEngine, type IntegrationPolicyRule, type IntegrationProvider, type IntegrationProviderKind, type IntegrationToolDefinition, type IntegrationToolSearchFilters, type IntegrationToolSearchResult, type IntegrationTriggerEvent, type IntegrationTriggerSubscription, type InvokeWithCapabilityRequest, type IssueCapabilityRequest, type IssuedIntegrationCapability, type McpCatalog, type McpCatalogTool, type McpToolDefinition, type MicrosoftCalendarOptions, type NormalizedIntegrationResult, type NotionDatabaseOptions, type OAuthFlowStore, type OAuthTokens, type OpenApiDocument, type OpenApiOperation, type ParsedStripeSignatureHeader, type PendingOAuthFlow, type RateLimitSpec, type RefreshInput, type ResolvedDataSource, ResourceContention, type SecretRef, type SlackOptions, type SlackVerifyOptions, type StartAuthRequest, type StartAuthResult, type StartOAuthInput, type StartOAuthOutput, StaticIntegrationPolicyEngine, type StaticIntegrationPolicyOptions, type StripeVerifyOptions, _resetPendingFlowsForTests, assertValidConnectorManifest, buildApprovalRequest, buildIntegrationInvocationEnvelope, buildIntegrationToolCatalog, consumePendingFlow, createConnectorAdapterProvider, createDefaultIntegrationPolicyEngine, createHttpIntegrationProvider, createMockIntegrationProvider, exchangeAuthorizationCode, firstHeader, googleCalendar, googleSheets, hubspot, importGraphqlConnector, importMcpConnector, importOpenApiConnector, integrationToolName, invocationRequestFromEnvelope, manifestToConnector, microsoftCalendar, normalizeIntegrationResult, notionDatabase, parseIntegrationToolName, parseStripeSignatureHeader, redactApprovalRequest, redactCapability, redactInvocationEnvelope, refreshAccessToken, sanitizeConnection, searchIntegrationTools, signCapability, slack, slackEventsConnector, startOAuthFlow, stripePackConnector, stripeWebhookReceiverConnector, toMcpTools, twilioSmsConnector, validateConnectorManifest, verifyCapabilityToken, verifyHmacSignature, verifySlackSignature, verifyStripeSignature, webhookConnector };
+export { type AuthSpec, type CASStrategy, type Capability, type CapabilityClass, type CapabilityMutation, type CapabilityMutationResult, type CapabilityParameterSchema, type CapabilityRead, type CapabilityReadResult, type CompleteAuthRequest, type ConnectorAdapter, type ConnectorAdapterProviderOptions, type ConnectorCredentials, type ConnectorInvocation, type ConnectorManifest, type ConnectorManifestValidationIssue, type ConnectorManifestValidationResult, type ConsistencyModel, CredentialsExpired, DEFAULT_SIGNATURE_TOLERANCE_SECONDS, type DataSourceMetadata, type EventHandlerResult, type ExchangeCodeInput, type GenericHmacVerifyOptions, type GoogleCalendarOptions, type GoogleSheetsOptions, type GraphqlOperationSpec, type HttpIntegrationProviderOptions, type HubSpotOptions, type ImportCatalogOptions, InMemoryConnectionStore, InMemoryOAuthFlowStore, type InboundEvent, type IntegrationActionGuard, type IntegrationActionRequest, type IntegrationActionResult, type IntegrationActionRisk, type IntegrationActor, type IntegrationApprovalRequest, type IntegrationApprovalResolution, type IntegrationCapability, type IntegrationConnection, type IntegrationConnectionStore, type IntegrationConnector, type IntegrationConnectorAction, type IntegrationConnectorCategory, type IntegrationConnectorTrigger, type IntegrationDataClass, IntegrationError, type IntegrationGuardContext, IntegrationHub, type IntegrationHubOptions, type IntegrationInvocationEnvelope, type IntegrationInvocationEnvelopeValidationOptions, type IntegrationPolicyDecision, type IntegrationPolicyEffect, type IntegrationPolicyEngine, type IntegrationPolicyRule, type IntegrationProvider, type IntegrationProviderKind, type IntegrationToolDefinition, type IntegrationToolSearchFilters, type IntegrationToolSearchResult, type IntegrationTriggerEvent, type IntegrationTriggerSubscription, type InvokeWithCapabilityRequest, type IssueCapabilityRequest, type IssuedIntegrationCapability, type McpCatalog, type McpCatalogTool, type McpToolDefinition, type MicrosoftCalendarOptions, type NormalizedIntegrationResult, type NotionDatabaseOptions, type OAuthFlowStore, type OAuthTokens, type OpenApiDocument, type OpenApiOperation, type ParsedStripeSignatureHeader, type PendingOAuthFlow, type RateLimitSpec, type RefreshInput, type ResolvedDataSource, ResourceContention, type SecretRef, type SlackOptions, type SlackVerifyOptions, type StartAuthRequest, type StartAuthResult, type StartOAuthInput, type StartOAuthOutput, StaticIntegrationPolicyEngine, type StaticIntegrationPolicyOptions, type StripeVerifyOptions, type TwilioVerifyOptions, _resetPendingFlowsForTests, assertValidConnectorManifest, buildApprovalRequest, buildIntegrationInvocationEnvelope, buildIntegrationToolCatalog, consumePendingFlow, createConnectorAdapterProvider, createDefaultIntegrationPolicyEngine, createHttpIntegrationProvider, createMockIntegrationProvider, exchangeAuthorizationCode, firstHeader, googleCalendar, googleSheets, hubspot, importGraphqlConnector, importMcpConnector, importOpenApiConnector, integrationToolName, invocationRequestFromEnvelope, manifestToConnector, microsoftCalendar, normalizeIntegrationResult, notionDatabase, parseIntegrationToolName, parseStripeSignatureHeader, redactApprovalRequest, redactCapability, redactInvocationEnvelope, refreshAccessToken, sanitizeConnection, searchIntegrationTools, signCapability, slack, slackEventsConnector, startOAuthFlow, stripePackConnector, stripeWebhookReceiverConnector, toMcpTools, twilioSmsConnector, validateConnectorManifest, validateIntegrationInvocationEnvelope, verifyCapabilityToken, verifyHmacSignature, verifySlackSignature, verifyStripeSignature, verifyTwilioSignature, webhookConnector };

package/dist/index.js

@@ -242,6 +242,20 @@ function verifyHmacSignature(rawBody, signatureHeader, secret, options = {}) {
   if (sigBuf.length !== expectedBuf.length) return false;
   return timingSafeEqual(sigBuf, expectedBuf);
 }
+function verifyTwilioSignature(input, options = {}) {
+  if (!input.authToken) {
+    return options.skipWhenAuthTokenMissing === true;
+  }
+  const signature = input.signatureHeader;
+  if (!signature || Array.isArray(signature)) return false;
+  if (!input.fullUrl) return false;
+  const data = options.bodyAsRaw === true ? input.fullUrl + (options.rawBody ?? "") : Object.keys(input.params ?? {}).sort().reduce((acc, key) => acc + key + (input.params[key] ?? ""), input.fullUrl);
+  const expected = createHmac("sha1", input.authToken).update(data).digest("base64");
+  const expectedBuf = Buffer.from(expected);
+  const sigBuf = Buffer.from(signature);
+  if (expectedBuf.length !== sigBuf.length) return false;
+  return timingSafeEqual(expectedBuf, sigBuf);
+}
 function firstHeader(headers, name) {
   const v = headers[name] ?? headers[name.toLowerCase()] ?? Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1];
   if (Array.isArray(v)) return v[0];
@@ -2743,10 +2757,10 @@ 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");
+  return Buffer.from(value, "utf8").toString("base64url").replace(/_/g, ".");
 }
 function decodeToolPart(value) {
-  return Buffer.from(value, "base64url").toString("utf8");
+  return Buffer.from(value.replace(/\./g, "_"), "base64url").toString("utf8");
 }
 function unique(values) {
   return [...new Set(values)];
@@ -2855,7 +2869,7 @@ function redactUnknown(value) {
 // src/sandbox.ts
 function buildIntegrationInvocationEnvelope(input) {
   const parsed = parseIntegrationToolName(input.toolName);
-  return {
+  const envelope = {
     kind: "integration.invocation",
     capabilityToken: input.capabilityToken,
     toolName: input.toolName,
@@ -2865,8 +2879,11 @@ function buildIntegrationInvocationEnvelope(input) {
     dryRun: input.dryRun,
     metadata: input.metadata
   };
+  validateIntegrationInvocationEnvelope(envelope);
+  return envelope;
 }
 function invocationRequestFromEnvelope(envelope) {
+  validateIntegrationInvocationEnvelope(envelope);
   return {
     action: envelope.action,
     input: envelope.input,
@@ -2875,6 +2892,34 @@ function invocationRequestFromEnvelope(envelope) {
     metadata: envelope.metadata
   };
 }
+function validateIntegrationInvocationEnvelope(envelope, options = {}) {
+  if (!envelope || typeof envelope !== "object") throw new Error("Integration invocation envelope is required.");
+  if (envelope.kind !== "integration.invocation") throw new Error("Invalid integration invocation envelope kind.");
+  if (!isNonEmptyString(envelope.capabilityToken)) throw new Error("Integration invocation envelope is missing capabilityToken.");
+  if (!isNonEmptyString(envelope.toolName)) throw new Error("Integration invocation envelope is missing toolName.");
+  if (!isNonEmptyString(envelope.action)) throw new Error("Integration invocation envelope is missing action.");
+  if (!isNonEmptyString(envelope.idempotencyKey)) throw new Error("Integration invocation envelope is missing idempotencyKey.");
+  if (envelope.metadata !== void 0 && !isPlainRecord(envelope.metadata)) {
+    throw new Error("Integration invocation envelope metadata must be an object.");
+  }
+  const parsed = parseIntegrationToolName(envelope.toolName);
+  if (parsed.actionId !== envelope.action) {
+    throw new Error(`Integration invocation action ${envelope.action} does not match tool ${parsed.actionId}.`);
+  }
+  const inputBytes = Buffer.byteLength(JSON.stringify(envelope.input ?? null), "utf8");
+  const maxInputBytes = options.maxInputBytes ?? 256 * 1024;
+  if (inputBytes > maxInputBytes) {
+    throw new Error(`Integration invocation input exceeds ${maxInputBytes} bytes.`);
+  }
+  if (options.requireKnownTool || options.connectors) {
+    if (!options.connectors) throw new Error("connectors are required when requireKnownTool is true.");
+    const connector = options.connectors.find(
+      (candidate) => candidate.providerId === parsed.providerId && candidate.id === parsed.connectorId
+    );
+    const action = connector?.actions.find((candidate) => candidate.id === parsed.actionId);
+    if (!connector || !action) throw new Error(`Unknown integration tool ${envelope.toolName}.`);
+  }
+}
 function redactInvocationEnvelope(envelope) {
   return {
     ...envelope,
@@ -2926,6 +2971,12 @@ function redactUnknown2(value) {
   }
   return out;
 }
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isPlainRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 
 // src/adapter-provider.ts
 function createConnectorAdapterProvider(options) {
@@ -3552,10 +3603,12 @@ export {
   toMcpTools,
   twilioSmsConnector,
   validateConnectorManifest,
+  validateIntegrationInvocationEnvelope,
   verifyCapabilityToken,
   verifyHmacSignature,
   verifySlackSignature,
   verifyStripeSignature,
+  verifyTwilioSignature,
   webhookConnector
 };
 //# sourceMappingURL=index.js.map