@contractspec/integration.runtime 2.9.0 → 3.0.0

package/dist/node/channel/service.js

@@ -0,0 +1,286 @@
+// src/channel/policy.ts
+var DEFAULT_MESSAGING_POLICY_CONFIG = {
+  autoResolveMinConfidence: 0.85,
+  assistMinConfidence: 0.65,
+  blockedSignals: [
+    "ignore previous instructions",
+    "reveal secret",
+    "api key",
+    "password",
+    "token",
+    "drop table",
+    "delete repository"
+  ],
+  highRiskSignals: [
+    "refund",
+    "delete account",
+    "cancel subscription",
+    "permission",
+    "admin access",
+    "wire transfer",
+    "bank account"
+  ],
+  mediumRiskSignals: [
+    "urgent",
+    "legal",
+    "compliance",
+    "frustrated",
+    "escalate",
+    "outage"
+  ],
+  safeAckTemplate: "Thanks for your message. We received it and are preparing the next step."
+};
+
+class MessagingPolicyEngine {
+  config;
+  constructor(config) {
+    this.config = {
+      ...DEFAULT_MESSAGING_POLICY_CONFIG,
+      ...config ?? {}
+    };
+  }
+  evaluate(input) {
+    const text = (input.event.message?.text ?? "").toLowerCase();
+    if (containsAny(text, this.config.blockedSignals)) {
+      return {
+        confidence: 0.2,
+        riskTier: "blocked",
+        verdict: "blocked",
+        reasons: ["blocked_signal_detected"],
+        responseText: this.config.safeAckTemplate,
+        requiresApproval: true
+      };
+    }
+    if (containsAny(text, this.config.highRiskSignals)) {
+      return {
+        confidence: 0.55,
+        riskTier: "high",
+        verdict: "assist",
+        reasons: ["high_risk_topic_detected"],
+        responseText: this.config.safeAckTemplate,
+        requiresApproval: true
+      };
+    }
+    const mediumRiskDetected = containsAny(text, this.config.mediumRiskSignals);
+    const confidence = mediumRiskDetected ? 0.74 : 0.92;
+    const riskTier = mediumRiskDetected ? "medium" : "low";
+    if (confidence >= this.config.autoResolveMinConfidence && riskTier === "low") {
+      return {
+        confidence,
+        riskTier,
+        verdict: "autonomous",
+        reasons: ["low_risk_high_confidence"],
+        responseText: this.defaultResponseText(input.event),
+        requiresApproval: false
+      };
+    }
+    if (confidence >= this.config.assistMinConfidence) {
+      return {
+        confidence,
+        riskTier,
+        verdict: "assist",
+        reasons: ["needs_human_review"],
+        responseText: this.config.safeAckTemplate,
+        requiresApproval: true
+      };
+    }
+    return {
+      confidence,
+      riskTier: "blocked",
+      verdict: "blocked",
+      reasons: ["low_confidence"],
+      responseText: this.config.safeAckTemplate,
+      requiresApproval: true
+    };
+  }
+  defaultResponseText(event) {
+    if (!event.message?.text) {
+      return this.config.safeAckTemplate;
+    }
+    return `Acknowledged: ${event.message.text.slice(0, 240)}`;
+  }
+}
+function containsAny(text, candidates) {
+  return candidates.some((candidate) => text.includes(candidate));
+}
+
+// src/channel/service.ts
+import { createHash, randomUUID } from "node:crypto";
+class ChannelRuntimeService {
+  store;
+  policy;
+  asyncProcessing;
+  processInBackground;
+  modelName;
+  promptVersion;
+  policyVersion;
+  telemetry;
+  constructor(store, options = {}) {
+    this.store = store;
+    this.policy = options.policy ?? new MessagingPolicyEngine;
+    this.asyncProcessing = options.asyncProcessing ?? true;
+    this.processInBackground = options.processInBackground ?? ((task) => {
+      setTimeout(() => {
+        task();
+      }, 0);
+    });
+    this.modelName = options.modelName ?? "policy-heuristics-v1";
+    this.promptVersion = options.promptVersion ?? "channel-runtime.v1";
+    this.policyVersion = options.policyVersion ?? "messaging-policy.v1";
+    this.telemetry = options.telemetry;
+  }
+  async ingest(event) {
+    const startedAtMs = Date.now();
+    const claim = await this.store.claimEventReceipt({
+      workspaceId: event.workspaceId,
+      providerKey: event.providerKey,
+      externalEventId: event.externalEventId,
+      eventType: event.eventType,
+      signatureValid: event.signatureValid,
+      payloadHash: event.rawPayload ? sha256(event.rawPayload) : undefined,
+      traceId: event.traceId
+    });
+    if (claim.duplicate) {
+      this.telemetry?.record({
+        stage: "ingest",
+        status: "duplicate",
+        workspaceId: event.workspaceId,
+        providerKey: event.providerKey,
+        receiptId: claim.receiptId,
+        traceId: event.traceId,
+        latencyMs: Date.now() - startedAtMs
+      });
+      return {
+        status: "duplicate",
+        receiptId: claim.receiptId
+      };
+    }
+    this.telemetry?.record({
+      stage: "ingest",
+      status: "accepted",
+      workspaceId: event.workspaceId,
+      providerKey: event.providerKey,
+      receiptId: claim.receiptId,
+      traceId: event.traceId,
+      latencyMs: Date.now() - startedAtMs
+    });
+    const task = async () => {
+      await this.processAcceptedEvent(claim.receiptId, event);
+    };
+    if (this.asyncProcessing) {
+      this.processInBackground(task);
+    } else {
+      await task();
+    }
+    return {
+      status: "accepted",
+      receiptId: claim.receiptId
+    };
+  }
+  async processAcceptedEvent(receiptId, event) {
+    try {
+      await this.store.updateReceiptStatus(receiptId, "processing");
+      const thread = await this.store.upsertThread({
+        workspaceId: event.workspaceId,
+        providerKey: event.providerKey,
+        externalThreadId: event.thread.externalThreadId,
+        externalChannelId: event.thread.externalChannelId,
+        externalUserId: event.thread.externalUserId,
+        occurredAt: event.occurredAt
+      });
+      const policyDecision = this.policy.evaluate({ event });
+      this.telemetry?.record({
+        stage: "decision",
+        status: "processed",
+        workspaceId: event.workspaceId,
+        providerKey: event.providerKey,
+        receiptId,
+        traceId: event.traceId,
+        metadata: {
+          verdict: policyDecision.verdict,
+          riskTier: policyDecision.riskTier,
+          confidence: policyDecision.confidence
+        }
+      });
+      const decision = await this.store.saveDecision({
+        receiptId,
+        threadId: thread.id,
+        policyMode: policyDecision.verdict === "autonomous" ? "autonomous" : "assist",
+        riskTier: policyDecision.riskTier,
+        confidence: policyDecision.confidence,
+        modelName: this.modelName,
+        promptVersion: this.promptVersion,
+        policyVersion: this.policyVersion,
+        actionPlan: {
+          verdict: policyDecision.verdict,
+          reasons: policyDecision.reasons
+        },
+        requiresApproval: policyDecision.requiresApproval
+      });
+      if (policyDecision.verdict === "autonomous") {
+        await this.store.enqueueOutboxAction({
+          workspaceId: event.workspaceId,
+          providerKey: event.providerKey,
+          decisionId: decision.id,
+          threadId: thread.id,
+          actionType: "reply",
+          idempotencyKey: buildOutboxIdempotencyKey(event, policyDecision.responseText),
+          target: {
+            externalThreadId: event.thread.externalThreadId,
+            externalChannelId: event.thread.externalChannelId,
+            externalUserId: event.thread.externalUserId
+          },
+          payload: {
+            id: randomUUID(),
+            text: policyDecision.responseText
+          }
+        });
+        this.telemetry?.record({
+          stage: "outbox",
+          status: "accepted",
+          workspaceId: event.workspaceId,
+          providerKey: event.providerKey,
+          receiptId,
+          traceId: event.traceId,
+          metadata: {
+            actionType: "reply"
+          }
+        });
+      }
+      await this.store.updateReceiptStatus(receiptId, "processed");
+      this.telemetry?.record({
+        stage: "ingest",
+        status: "processed",
+        workspaceId: event.workspaceId,
+        providerKey: event.providerKey,
+        receiptId,
+        traceId: event.traceId
+      });
+    } catch (error) {
+      await this.store.updateReceiptStatus(receiptId, "failed", {
+        code: "PROCESSING_FAILED",
+        message: error instanceof Error ? error.message : String(error)
+      });
+      this.telemetry?.record({
+        stage: "ingest",
+        status: "failed",
+        workspaceId: event.workspaceId,
+        providerKey: event.providerKey,
+        receiptId,
+        traceId: event.traceId,
+        metadata: {
+          errorCode: "PROCESSING_FAILED"
+        }
+      });
+    }
+  }
+}
+function buildOutboxIdempotencyKey(event, responseText) {
+  return sha256(`${event.workspaceId}:${event.providerKey}:${event.externalEventId}:reply:${responseText}`);
+}
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+export {
+  ChannelRuntimeService
+};

package/dist/node/channel/slack.js

@@ -0,0 +1,81 @@
+// src/channel/slack.ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+function verifySlackSignature(input) {
+  if (!input.requestTimestamp || !input.requestSignature) {
+    return { valid: false, reason: "missing_signature_headers" };
+  }
+  const timestamp = Number.parseInt(input.requestTimestamp, 10);
+  if (!Number.isFinite(timestamp)) {
+    return { valid: false, reason: "invalid_timestamp" };
+  }
+  const nowMs = input.nowMs ?? Date.now();
+  const toleranceMs = (input.toleranceSeconds ?? 300) * 1000;
+  if (Math.abs(nowMs - timestamp * 1000) > toleranceMs) {
+    return { valid: false, reason: "timestamp_out_of_range" };
+  }
+  const base = `v0:${input.requestTimestamp}:${input.rawBody}`;
+  const expected = `v0=${createHmac("sha256", input.signingSecret).update(base).digest("hex")}`;
+  const receivedBuffer = Buffer.from(input.requestSignature, "utf8");
+  const expectedBuffer = Buffer.from(expected, "utf8");
+  if (receivedBuffer.length !== expectedBuffer.length) {
+    return { valid: false, reason: "signature_length_mismatch" };
+  }
+  const valid = timingSafeEqual(receivedBuffer, expectedBuffer);
+  return valid ? { valid: true } : { valid: false, reason: "signature_mismatch" };
+}
+function parseSlackWebhookPayload(rawBody) {
+  const parsed = JSON.parse(rawBody);
+  return parsed;
+}
+function isSlackUrlVerificationPayload(payload) {
+  return payload.type === "url_verification";
+}
+function normalizeSlackInboundEvent(input) {
+  if (input.payload.type !== "event_callback") {
+    return null;
+  }
+  const event = input.payload.event;
+  if (!event?.type) {
+    return null;
+  }
+  if (event.subtype === "bot_message" || event.bot_id) {
+    return null;
+  }
+  const externalEventId = input.payload.event_id ?? event.ts;
+  if (!externalEventId) {
+    return null;
+  }
+  const threadId = event.thread_ts ?? event.ts ?? externalEventId;
+  if (!threadId) {
+    return null;
+  }
+  return {
+    workspaceId: input.workspaceId,
+    providerKey: "messaging.slack",
+    externalEventId,
+    eventType: `slack.${event.type}`,
+    occurredAt: input.payload.event_time ? new Date(input.payload.event_time * 1000) : new Date,
+    signatureValid: input.signatureValid,
+    traceId: input.traceId,
+    rawPayload: input.rawBody,
+    thread: {
+      externalThreadId: threadId,
+      externalChannelId: event.channel,
+      externalUserId: event.user
+    },
+    message: event.text ? {
+      text: event.text,
+      externalMessageId: event.ts
+    } : undefined,
+    metadata: {
+      slackEventType: event.type,
+      slackTeamId: input.payload.team_id ?? input.workspaceId
+    }
+  };
+}
+export {
+  verifySlackSignature,
+  parseSlackWebhookPayload,
+  normalizeSlackInboundEvent,
+  isSlackUrlVerificationPayload
+};

package/dist/node/channel/whatsapp-meta.js

@@ -0,0 +1,65 @@
+// src/channel/whatsapp-meta.ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+function verifyMetaSignature(input) {
+  if (!input.signatureHeader) {
+    return { valid: false, reason: "missing_signature" };
+  }
+  const expected = `sha256=${createHmac("sha256", input.appSecret).update(input.rawBody).digest("hex")}`;
+  const expectedBuffer = Buffer.from(expected, "utf8");
+  const providedBuffer = Buffer.from(input.signatureHeader, "utf8");
+  if (expectedBuffer.length !== providedBuffer.length) {
+    return { valid: false, reason: "signature_length_mismatch" };
+  }
+  return timingSafeEqual(expectedBuffer, providedBuffer) ? { valid: true } : { valid: false, reason: "signature_mismatch" };
+}
+function parseMetaWebhookPayload(rawBody) {
+  return JSON.parse(rawBody);
+}
+function normalizeMetaWhatsappInboundEvents(input) {
+  const events = [];
+  for (const entry of input.payload.entry ?? []) {
+    for (const change of entry.changes ?? []) {
+      const value = change.value;
+      if (!value)
+        continue;
+      const phoneNumberId = value.metadata?.phone_number_id;
+      for (const message of value.messages ?? []) {
+        const from = message.from;
+        const messageId = message.id;
+        const text = message.text?.body;
+        if (!from || !messageId || !text)
+          continue;
+        const occurredAt = message.timestamp ? new Date(Number(message.timestamp) * 1000) : new Date;
+        events.push({
+          workspaceId: input.workspaceId,
+          providerKey: "messaging.whatsapp.meta",
+          externalEventId: messageId,
+          eventType: "whatsapp.meta.message",
+          occurredAt,
+          signatureValid: input.signatureValid,
+          traceId: input.traceId,
+          rawPayload: input.rawBody,
+          thread: {
+            externalThreadId: from,
+            externalChannelId: phoneNumberId,
+            externalUserId: from
+          },
+          message: {
+            text,
+            externalMessageId: messageId
+          },
+          metadata: {
+            messageType: message.type ?? "text",
+            phoneNumberId: phoneNumberId ?? ""
+          }
+        });
+      }
+    }
+  }
+  return events;
+}
+export {
+  verifyMetaSignature,
+  parseMetaWebhookPayload,
+  normalizeMetaWhatsappInboundEvents
+};

package/dist/node/channel/whatsapp-twilio.js

@@ -0,0 +1,60 @@
+// src/channel/whatsapp-twilio.ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+function verifyTwilioSignature(input) {
+  if (!input.signatureHeader) {
+    return { valid: false, reason: "missing_signature" };
+  }
+  const sortedKeys = Array.from(input.formBody.keys()).sort();
+  let payload = input.requestUrl;
+  for (const key of sortedKeys) {
+    const value = input.formBody.get(key) ?? "";
+    payload += `${key}${value}`;
+  }
+  const expected = createHmac("sha1", input.authToken).update(payload).digest("base64");
+  const expectedBuffer = Buffer.from(expected, "utf8");
+  const providedBuffer = Buffer.from(input.signatureHeader, "utf8");
+  if (expectedBuffer.length !== providedBuffer.length) {
+    return { valid: false, reason: "signature_length_mismatch" };
+  }
+  return timingSafeEqual(expectedBuffer, providedBuffer) ? { valid: true } : { valid: false, reason: "signature_mismatch" };
+}
+function parseTwilioFormPayload(rawBody) {
+  return new URLSearchParams(rawBody);
+}
+function normalizeTwilioWhatsappInboundEvent(input) {
+  const messageSid = input.formBody.get("MessageSid");
+  const from = input.formBody.get("From");
+  const to = input.formBody.get("To");
+  const body = input.formBody.get("Body");
+  if (!messageSid || !from || !body) {
+    return null;
+  }
+  return {
+    workspaceId: input.workspaceId,
+    providerKey: "messaging.whatsapp.twilio",
+    externalEventId: messageSid,
+    eventType: "whatsapp.twilio.message",
+    occurredAt: new Date,
+    signatureValid: input.signatureValid,
+    traceId: input.traceId,
+    rawPayload: input.rawBody,
+    thread: {
+      externalThreadId: from,
+      externalChannelId: to ?? undefined,
+      externalUserId: from
+    },
+    message: {
+      text: body,
+      externalMessageId: messageSid
+    },
+    metadata: {
+      accountSid: input.formBody.get("AccountSid") ?? "",
+      profileName: input.formBody.get("ProfileName") ?? ""
+    }
+  };
+}
+export {
+  verifyTwilioSignature,
+  parseTwilioFormPayload,
+  normalizeTwilioWhatsappInboundEvent
+};