@svsprotocol/solana 0.1.0

package/dist/webhooks.js

@@ -0,0 +1,834 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { hashObject } from "./receipt.js";
+
+export const WEBHOOK_EVENT_VERSION = "svs.webhook-event.v1";
+export const WEBHOOK_SIGNATURE_VERSION = "v1";
+export const WEBHOOK_REPLAY_STORE_VERSION = "svs.webhook-replay-store.v1";
+export const DEFAULT_WEBHOOK_REPLAY_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const DEFAULT_WEBHOOK_RETRY_DELAYS_MS = [
+  60 * 1000,
+  5 * 60 * 1000,
+  15 * 60 * 1000,
+  60 * 60 * 1000,
+  6 * 60 * 60 * 1000
+];
+
+export async function emitWebhookEvent({
+  outboxDir = "./data/webhook-outbox",
+  botRegistryPath = "./.devnet/bots.json",
+  eventType,
+  record,
+  previousStatus = null,
+  eventData = null,
+  fetchImpl = globalThis.fetch,
+  deliver = true,
+  createdAt = new Date().toISOString()
+} = {}) {
+  if (!record) {
+    return null;
+  }
+
+  const bot = await findWebhookBot({
+    botRegistryPath,
+    botId: record.source?.authenticatedBotId ?? record.intent?.botId
+  });
+
+  if (!bot?.webhookUrl) {
+    return null;
+  }
+
+  const event = createWebhookEvent({
+    eventType,
+    record,
+    previousStatus,
+    bot,
+    eventData,
+    createdAt
+  });
+  const outboxEntry = {
+    ...event,
+    delivery: {
+      mode: "outbox",
+      url: bot.webhookUrl,
+      attemptedAt: null,
+      deliveredAt: null,
+      statusCode: null,
+      ok: false,
+      error: null
+    }
+  };
+  const path = join(outboxDir, `${event.createdAt.replaceAll(":", "-")}-${event.eventId}.json`);
+
+  await writeWebhookEvent(path, outboxEntry);
+
+  if (!deliver) {
+    return {
+      path,
+      event: outboxEntry
+    };
+  }
+
+  const delivered = await deliverWebhookEvent({
+    path,
+    event: outboxEntry,
+    webhookSecret: bot.webhookSecret,
+    fetchImpl
+  });
+
+  return {
+    path,
+    event: delivered
+  };
+}
+
+export async function emitBotWebhookTest({
+  outboxDir = "./data/webhook-outbox",
+  botRegistryPath = "./.devnet/bots.json",
+  botId,
+  fetchImpl = globalThis.fetch,
+  deliver = true,
+  createdAt = new Date().toISOString()
+} = {}) {
+  if (!botId) {
+    throw new Error("botId is required.");
+  }
+
+  const bot = await findWebhookBot({ botRegistryPath, botId });
+
+  if (!bot?.webhookUrl) {
+    return null;
+  }
+
+  const record = {
+    id: `webhook-test-${randomUUID()}`,
+    status: "webhook_test",
+    authorizationType: "webhook_test",
+    intent: {
+      botId,
+      controllerWallet: null
+    },
+    source: {
+      authenticatedBotId: botId,
+      actionRequestHash: null,
+      idempotencyKey: null
+    },
+    policySummary: {
+      id: null
+    },
+    receipt: {
+      receiptId: null,
+      receiptHash: null
+    }
+  };
+  const event = createWebhookEvent({
+    eventType: "bot.webhook_test",
+    record,
+    previousStatus: null,
+    bot,
+    createdAt
+  });
+  const outboxEntry = {
+    ...event,
+    delivery: {
+      mode: "outbox",
+      url: bot.webhookUrl,
+      attemptedAt: null,
+      deliveredAt: null,
+      statusCode: null,
+      ok: false,
+      error: null
+    }
+  };
+  const path = join(outboxDir, `${event.createdAt.replaceAll(":", "-")}-${event.eventId}.json`);
+
+  await writeWebhookEvent(path, outboxEntry);
+
+  if (!deliver) {
+    return {
+      path,
+      event: outboxEntry
+    };
+  }
+
+  const delivered = await deliverWebhookEvent({
+    path,
+    event: outboxEntry,
+    webhookSecret: bot.webhookSecret,
+    fetchImpl
+  });
+
+  return {
+    path,
+    event: delivered
+  };
+}
+
+export async function listWebhookEvents({
+  outboxDir = "./data/webhook-outbox"
+} = {}) {
+  let files;
+
+  try {
+    files = await readdir(outboxDir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+
+    throw error;
+  }
+
+  return Promise.all(
+    files
+      .filter((file) => file.endsWith(".json"))
+      .sort()
+      .map(async (file) => {
+        const path = join(outboxDir, file);
+
+        return {
+          path,
+          event: JSON.parse(await readFile(path, "utf8"))
+        };
+      })
+  );
+}
+
+export async function retryWebhookEvents({
+  outboxDir = "./data/webhook-outbox",
+  botRegistryPath = "./.devnet/bots.json",
+  eventId = null,
+  onlyFailed = true,
+  force = false,
+  limit = 25,
+  fetchImpl = globalThis.fetch,
+  now = new Date()
+} = {}) {
+  const entries = await listWebhookEvents({ outboxDir });
+  const hasMatchingEvent = !eventId || entries.some(({ event }) => event.eventId === eventId);
+  const retryable = entries
+    .filter(({ event }) => !eventId || event.eventId === eventId)
+    .filter(({ event }) => !onlyFailed || !event.delivery?.ok)
+    .filter(({ event }) => force || isWebhookRetryDue(event, now))
+    .slice(0, limit);
+  const results = [];
+
+  for (const entry of retryable) {
+    const bot = await findWebhookBot({
+      botRegistryPath,
+      botId: entry.event.authenticatedBotId ?? entry.event.botId
+    });
+
+    if (!bot?.webhookUrl) {
+      results.push({
+        path: entry.path,
+        event: entry.event,
+        retried: false,
+        error: "No active bot webhook URL is configured."
+      });
+      continue;
+    }
+
+    const event = {
+      ...entry.event,
+      webhookUrl: bot.webhookUrl,
+      delivery: {
+        ...(entry.event.delivery ?? {}),
+        url: bot.webhookUrl
+      }
+    };
+    const delivered = await deliverWebhookEvent({
+      path: entry.path,
+      event,
+      webhookSecret: bot.webhookSecret,
+      fetchImpl,
+      now
+    });
+
+    results.push({
+      path: entry.path,
+      event: delivered,
+      retried: true,
+      error: null
+    });
+  }
+
+  if (eventId && !hasMatchingEvent) {
+    throw new Error(`Webhook event ${eventId} was not found or is not retryable.`);
+  }
+
+  return {
+    version: "svs.webhook-retry-result.v1",
+    retriedAt: now.toISOString(),
+    eventId,
+    onlyFailed,
+    force,
+    count: results.length,
+    delivered: results.filter((result) => result.event.delivery?.ok).length,
+    failed: results.filter((result) => result.retried && !result.event.delivery?.ok).length,
+    skipped: results.filter((result) => !result.retried).length,
+    results
+  };
+}
+
+function createWebhookEvent({
+  eventType,
+  record,
+  previousStatus,
+  bot,
+  eventData,
+  createdAt
+}) {
+  const payload = {
+    version: WEBHOOK_EVENT_VERSION,
+    eventId: randomUUID(),
+    eventType,
+    createdAt,
+    botId: record.intent?.botId ?? null,
+    authenticatedBotId: record.source?.authenticatedBotId ?? null,
+    recordId: record.id,
+    previousStatus,
+    status: record.status,
+    authorizationType: record.authorizationType,
+    controllerWallet: record.intent?.controllerWallet ?? null,
+    policyId: record.policySummary?.id ?? record.receipt?.policyId ?? null,
+    receiptHash: record.receipt?.receiptHash ?? null,
+    receiptId: record.receipt?.receiptId ?? record.id,
+    broadcastSignature: record.broadcast?.signature ?? null,
+    anchorSignature: record.anchor?.signature ?? null,
+    feePaymentSignature: record.feePayment?.signature ?? null,
+    idempotencyKey: record.source?.idempotencyKey ?? null,
+    actionRequestHash: record.source?.actionRequestHash ?? null,
+    links: {
+      action: `/api/actions/${encodeURIComponent(record.id)}`,
+      receipt: `/api/actions/${encodeURIComponent(record.id)}/receipt`,
+      report: `/api/actions/${encodeURIComponent(record.id)}/report`
+    }
+  };
+
+  if (eventData !== null && eventData !== undefined) {
+    payload.data = eventData;
+  }
+
+  return {
+    ...payload,
+    webhookUrl: bot.webhookUrl,
+    payloadHashAlgorithm: "sha256",
+    payloadHash: hashObject(payload)
+  };
+}
+
+async function deliverWebhookEvent({
+  path,
+  event,
+  webhookSecret,
+  fetchImpl,
+  now = new Date()
+}) {
+  const attemptedAt = now.toISOString();
+
+  if (!fetchImpl) {
+    const failed = withDeliveryAttempt(event, {
+      attemptedAt,
+      error: "fetch is not available."
+    });
+
+    await writeWebhookEvent(path, failed);
+    return failed;
+  }
+
+  try {
+    const body = JSON.stringify(event);
+    const signatureHeaders = webhookSecret
+      ? createWebhookSignatureHeaders({ body, webhookSecret, timestamp: attemptedAt })
+      : {};
+    const response = await fetchImpl(event.webhookUrl, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "svs-event-type": event.eventType,
+        "svs-event-id": event.eventId,
+        "svs-payload-hash": event.payloadHash,
+        ...signatureHeaders
+      },
+      body
+    });
+    const delivered = withDeliveryAttempt(event, {
+      attemptedAt,
+      deliveredAt: response.ok ? now.toISOString() : null,
+      statusCode: response.status,
+      ok: Boolean(response.ok),
+      error: response.ok ? null : `HTTP ${response.status}`,
+      signature: signatureHeaders["svs-webhook-signature"] ?? null,
+      signatureTimestamp: signatureHeaders["svs-webhook-timestamp"] ?? null
+    });
+
+    await writeWebhookEvent(path, delivered);
+    return delivered;
+  } catch (error) {
+    const failed = withDeliveryAttempt(event, {
+      attemptedAt,
+      error: error.message
+    });
+
+    await writeWebhookEvent(path, failed);
+    return failed;
+  }
+}
+
+export function createWebhookSignatureHeaders({
+  body,
+  webhookSecret,
+  timestamp = new Date().toISOString()
+}) {
+  if (!webhookSecret) {
+    return {};
+  }
+
+  return {
+    "svs-webhook-timestamp": timestamp,
+    "svs-webhook-signature": createWebhookSignature({ body, webhookSecret, timestamp })
+  };
+}
+
+export function createWebhookSignature({ body, webhookSecret, timestamp }) {
+  if (!webhookSecret) {
+    throw new Error("webhookSecret is required.");
+  }
+
+  if (!timestamp) {
+    throw new Error("timestamp is required.");
+  }
+
+  const digest = createHmac("sha256", webhookSecret)
+    .update(`${timestamp}.${body}`)
+    .digest("hex");
+
+  return `${WEBHOOK_SIGNATURE_VERSION}=${digest}`;
+}
+
+export function verifyWebhookSignature({
+  body,
+  webhookSecret,
+  timestamp,
+  signature,
+  toleranceMs = 5 * 60 * 1000,
+  now = new Date()
+}) {
+  if (!webhookSecret || !timestamp || !signature) {
+    return {
+      ok: false,
+      reason: "missing_signature_fields"
+    };
+  }
+
+  const signedAt = new Date(timestamp);
+
+  if (Number.isNaN(signedAt.getTime())) {
+    return {
+      ok: false,
+      reason: "invalid_timestamp"
+    };
+  }
+
+  if (toleranceMs !== null && Math.abs(now.getTime() - signedAt.getTime()) > toleranceMs) {
+    return {
+      ok: false,
+      reason: "timestamp_outside_tolerance"
+    };
+  }
+
+  const expected = createWebhookSignature({ body, webhookSecret, timestamp });
+
+  if (!constantTimeEqual(signature, expected)) {
+    return {
+      ok: false,
+      reason: "signature_mismatch"
+    };
+  }
+
+  return {
+    ok: true,
+    reason: "valid",
+    scheme: "hmac-sha256",
+    signatureVersion: WEBHOOK_SIGNATURE_VERSION
+  };
+}
+
+export function verifyWebhookRequest({
+  body,
+  headers = {},
+  webhookSecret,
+  seenEventIds = null,
+  toleranceMs = 5 * 60 * 1000,
+  now = new Date()
+} = {}) {
+  const rawBody = normalizeWebhookBody(body);
+  const eventType = getHeader(headers, "svs-event-type");
+  const eventId = getHeader(headers, "svs-event-id");
+  const payloadHash = getHeader(headers, "svs-payload-hash");
+  const timestamp = getHeader(headers, "svs-webhook-timestamp");
+  const signature = getHeader(headers, "svs-webhook-signature");
+
+  let event;
+
+  try {
+    event = JSON.parse(rawBody);
+  } catch (_error) {
+    return webhookRequestResult(false, "invalid_json", null);
+  }
+
+  if (event.version !== WEBHOOK_EVENT_VERSION) {
+    return webhookRequestResult(false, "unsupported_event_version", event);
+  }
+
+  if (eventType && eventType !== event.eventType) {
+    return webhookRequestResult(false, "event_type_header_mismatch", event);
+  }
+
+  if (eventId && eventId !== event.eventId) {
+    return webhookRequestResult(false, "event_id_header_mismatch", event);
+  }
+
+  if (payloadHash && payloadHash !== event.payloadHash) {
+    return webhookRequestResult(false, "payload_hash_header_mismatch", event);
+  }
+
+  const expectedPayloadHash = hashObject(createWebhookPayloadFromEvent(event));
+
+  if (event.payloadHash !== expectedPayloadHash) {
+    return webhookRequestResult(false, "payload_hash_mismatch", event, { expectedPayloadHash });
+  }
+
+  const signatureResult = verifyWebhookSignature({
+    body: rawBody,
+    webhookSecret,
+    timestamp,
+    signature,
+    toleranceMs,
+    now
+  });
+
+  if (!signatureResult.ok) {
+    return webhookRequestResult(false, signatureResult.reason, event, { signature: signatureResult });
+  }
+
+  if (seenEventIds?.has?.(event.eventId)) {
+    return webhookRequestResult(false, "replayed_event", event, { signature: signatureResult });
+  }
+
+  seenEventIds?.add?.(event.eventId);
+
+  return {
+    ok: true,
+    reason: "valid",
+    event,
+    checks: {
+      eventVersion: WEBHOOK_EVENT_VERSION,
+      payloadHash: event.payloadHash,
+      signature: signatureResult
+    }
+  };
+}
+
+export async function verifyWebhookRequestWithReplayStore({
+  body,
+  headers = {},
+  webhookSecret,
+  replayStorePath = "./data/webhook-receiver-replays.json",
+  replayTtlMs = DEFAULT_WEBHOOK_REPLAY_TTL_MS,
+  maxReplayEvents = 10000,
+  toleranceMs = 5 * 60 * 1000,
+  now = new Date()
+} = {}) {
+  const store = await loadWebhookReplayStore({
+    path: replayStorePath,
+    maxAgeMs: replayTtlMs,
+    maxEntries: maxReplayEvents,
+    now
+  });
+  const replayGuard = createWebhookReplayGuard(store, now);
+  const result = verifyWebhookRequest({
+    body,
+    headers,
+    webhookSecret,
+    seenEventIds: replayGuard,
+    toleranceMs,
+    now
+  });
+
+  if (result.ok || store.pruned) {
+    await writeWebhookReplayStore(replayStorePath, store);
+  }
+
+  return {
+    ...result,
+    replayStore: result.ok
+      ? {
+          path: replayStorePath,
+          eventCount: store.acceptedEvents.length
+        }
+      : undefined
+  };
+}
+
+function withDeliveryAttempt(event, delivery) {
+  const priorAttempts = event.deliveryAttempts ?? [];
+  const attemptNumber = priorAttempts.length + 1;
+  const ok = Boolean(delivery.ok);
+  const nextAttemptAt = ok
+    ? null
+    : calculateNextWebhookAttemptAt({
+        attemptedAt: delivery.attemptedAt,
+        failedAttemptCount: priorAttempts.filter((attempt) => !attempt.ok).length + 1
+      });
+  const attempt = {
+    attempt: attemptNumber,
+    mode: "http",
+    url: event.webhookUrl ?? event.delivery?.url ?? null,
+    attemptedAt: delivery.attemptedAt,
+    deliveredAt: delivery.deliveredAt ?? null,
+    statusCode: delivery.statusCode ?? null,
+    ok,
+    error: delivery.error ?? null,
+    signature: delivery.signature ?? null,
+    signatureTimestamp: delivery.signatureTimestamp ?? null,
+    nextAttemptAt
+  };
+
+  return {
+    ...event,
+    deliveryAttempts: [
+      ...priorAttempts,
+      attempt
+    ],
+    delivery: {
+      ...event.delivery,
+      ...attempt
+    }
+  };
+}
+
+function isWebhookRetryDue(event, now) {
+  if (event.delivery?.ok) return false;
+  if (!event.delivery?.nextAttemptAt) return true;
+
+  return new Date(event.delivery.nextAttemptAt).getTime() <= now.getTime();
+}
+
+function calculateNextWebhookAttemptAt({
+  attemptedAt,
+  failedAttemptCount
+}) {
+  const delay = DEFAULT_WEBHOOK_RETRY_DELAYS_MS[
+    Math.min(failedAttemptCount - 1, DEFAULT_WEBHOOK_RETRY_DELAYS_MS.length - 1)
+  ];
+
+  return new Date(new Date(attemptedAt).getTime() + delay).toISOString();
+}
+
+async function loadWebhookReplayStore({
+  path,
+  maxAgeMs,
+  maxEntries,
+  now
+}) {
+  let store;
+
+  try {
+    store = normalizeWebhookReplayStore(JSON.parse(await readFile(path, "utf8")));
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+
+    store = createEmptyWebhookReplayStore();
+  }
+
+  return pruneWebhookReplayStore(store, { maxAgeMs, maxEntries, now });
+}
+
+function createEmptyWebhookReplayStore() {
+  return {
+    version: WEBHOOK_REPLAY_STORE_VERSION,
+    updatedAt: null,
+    acceptedEvents: []
+  };
+}
+
+function normalizeWebhookReplayStore(store) {
+  if (store?.version !== WEBHOOK_REPLAY_STORE_VERSION) {
+    return createEmptyWebhookReplayStore();
+  }
+
+  return {
+    version: WEBHOOK_REPLAY_STORE_VERSION,
+    updatedAt: store.updatedAt ?? null,
+    acceptedEvents: Array.isArray(store.acceptedEvents)
+      ? store.acceptedEvents
+          .filter((event) => event?.eventId)
+          .map((event) => ({
+            eventId: String(event.eventId),
+            acceptedAt: event.acceptedAt ?? null
+          }))
+      : []
+  };
+}
+
+function pruneWebhookReplayStore(store, { maxAgeMs, maxEntries, now }) {
+  const cutoff = maxAgeMs === null ? null : now.getTime() - maxAgeMs;
+  const originalCount = store.acceptedEvents.length;
+  const acceptedEvents = store.acceptedEvents
+    .filter((event) => {
+      if (cutoff === null) return true;
+      const acceptedAt = new Date(event.acceptedAt);
+
+      return !Number.isNaN(acceptedAt.getTime()) && acceptedAt.getTime() >= cutoff;
+    })
+    .slice(-maxEntries);
+
+  return {
+    ...store,
+    acceptedEvents,
+    pruned: acceptedEvents.length !== originalCount
+  };
+}
+
+function createWebhookReplayGuard(store, now) {
+  const seen = new Set(store.acceptedEvents.map((event) => event.eventId));
+
+  return {
+    has(eventId) {
+      return seen.has(eventId);
+    },
+    add(eventId) {
+      if (seen.has(eventId)) return;
+
+      seen.add(eventId);
+      store.acceptedEvents.push({
+        eventId,
+        acceptedAt: now.toISOString()
+      });
+      store.updatedAt = now.toISOString();
+    }
+  };
+}
+
+async function writeWebhookReplayStore(path, store) {
+  const persisted = {
+    version: WEBHOOK_REPLAY_STORE_VERSION,
+    updatedAt: store.updatedAt ?? null,
+    acceptedEvents: store.acceptedEvents
+  };
+
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(persisted, null, 2)}\n`, { mode: 0o600 });
+}
+
+function createWebhookPayloadFromEvent(event) {
+  const payload = {
+    version: event.version,
+    eventId: event.eventId,
+    eventType: event.eventType,
+    createdAt: event.createdAt,
+    botId: event.botId,
+    authenticatedBotId: event.authenticatedBotId,
+    recordId: event.recordId,
+    previousStatus: event.previousStatus,
+    status: event.status,
+    authorizationType: event.authorizationType,
+    controllerWallet: event.controllerWallet,
+    policyId: event.policyId,
+    receiptHash: event.receiptHash,
+    receiptId: event.receiptId,
+    broadcastSignature: event.broadcastSignature,
+    anchorSignature: event.anchorSignature,
+    feePaymentSignature: event.feePaymentSignature,
+    idempotencyKey: event.idempotencyKey,
+    actionRequestHash: event.actionRequestHash,
+    links: event.links
+  };
+
+  if (event.data !== undefined) {
+    payload.data = event.data;
+  }
+
+  return payload;
+}
+
+function getHeader(headers, name) {
+  if (headers?.get) {
+    return headers.get(name);
+  }
+
+  const lowerName = name.toLowerCase();
+
+  for (const [key, value] of Object.entries(headers ?? {})) {
+    if (key.toLowerCase() === lowerName) {
+      return Array.isArray(value) ? value[0] : value;
+    }
+  }
+
+  return null;
+}
+
+function normalizeWebhookBody(body) {
+  if (Buffer.isBuffer(body)) {
+    return body.toString("utf8");
+  }
+
+  if (body instanceof Uint8Array) {
+    return Buffer.from(body).toString("utf8");
+  }
+
+  if (typeof body === "string") {
+    return body;
+  }
+
+  return JSON.stringify(body ?? {});
+}
+
+function webhookRequestResult(ok, reason, event, checks = {}) {
+  return {
+    ok,
+    reason,
+    event,
+    checks
+  };
+}
+
+function constantTimeEqual(left, right) {
+  const leftBuffer = Buffer.from(String(left));
+  const rightBuffer = Buffer.from(String(right));
+
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+async function findWebhookBot({ botRegistryPath, botId }) {
+  if (!botId) {
+    return null;
+  }
+
+  try {
+    const registry = JSON.parse(await readFile(botRegistryPath, "utf8"));
+    const bot = (registry.bots ?? []).find((candidate) => candidate.id === botId);
+
+    if (!bot || bot.status === "disabled") {
+      return null;
+    }
+
+    return bot;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+async function writeWebhookEvent(path, event) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(event, null, 2)}\n`);
+}