@hogsend/engine 0.7.0 → 0.9.0

package/src/webhook-sources/presets/index.ts

@@ -0,0 +1,80 @@
+import type { env as engineEnv } from "../../env.js";
+import type { DefinedWebhookSource } from "../define-webhook-source.js";
+import { clerkSource } from "./clerk.js";
+import { segmentSource } from "./segment.js";
+import { stripeSource } from "./stripe.js";
+import { supabaseSource } from "./supabase.js";
+
+export { clerkSource } from "./clerk.js";
+export { segmentSource } from "./segment.js";
+export { stripeSource } from "./stripe.js";
+export { supabaseSource } from "./supabase.js";
+
+/**
+ * All shipped integration presets, keyed by their webhook-source id. The id is
+ * also the route segment: `PRESET_SOURCES.stripe` serves `POST /v1/webhooks/stripe`.
+ */
+export const PRESET_SOURCES = {
+  clerk: clerkSource,
+  supabase: supabaseSource,
+  stripe: stripeSource,
+  segment: segmentSource,
+} satisfies Record<string, DefinedWebhookSource>;
+
+/** The stable id of a shipped preset (`"clerk" | "supabase" | "stripe" | "segment"`). */
+export type PresetId = keyof typeof PRESET_SOURCES;
+
+/** The slice of the validated env `presetsFromEnv` reads (preset secrets + override). */
+type PresetEnv = Pick<
+  typeof engineEnv,
+  | "CLERK_WEBHOOK_SECRET"
+  | "SUPABASE_WEBHOOK_SECRET"
+  | "STRIPE_WEBHOOK_SECRET"
+  | "SEGMENT_WEBHOOK_SECRET"
+  | "ENABLED_WEBHOOK_PRESETS"
+>;
+
+/**
+ * Resolve which presets to enable from the validated env (decision #13).
+ *
+ * Resolution order:
+ *  1. `ENABLED_WEBHOOK_PRESETS === "none"` → no presets (hard off).
+ *  2. `ENABLED_WEBHOOK_PRESETS` is a csv of ids → exactly those, but ONLY when
+ *     the preset's secret (`env[auth.envKey]`) is also set (a signature source
+ *     with no secret fails closed at runtime, so enabling it is pointless).
+ *  3. `ENABLED_WEBHOOK_PRESETS === "*"` or absent → AUTO: every preset whose
+ *     secret is present.
+ *
+ * In every branch a preset is only returned when its secret is configured, so a
+ * preset can never be mounted in an always-fail-closed state by accident.
+ */
+export function presetsFromEnv(env: PresetEnv): DefinedWebhookSource[] {
+  const override = env.ENABLED_WEBHOOK_PRESETS?.trim();
+
+  if (override === "none") {
+    return [];
+  }
+
+  const hasSecret = (source: DefinedWebhookSource): boolean => {
+    const secret = env[source.auth.envKey as keyof PresetEnv];
+    return typeof secret === "string" && secret.length > 0;
+  };
+
+  // Explicit csv allow-list (anything other than "*"/empty).
+  if (override && override !== "*") {
+    const ids = new Set(
+      override
+        .split(",")
+        .map((id) => id.trim().toLowerCase())
+        .filter((id) => id.length > 0),
+    );
+    return (
+      Object.entries(PRESET_SOURCES) as [PresetId, DefinedWebhookSource][]
+    )
+      .filter(([id, source]) => ids.has(id) && hasSecret(source))
+      .map(([, source]) => source);
+  }
+
+  // AUTO ("*" or absent): every preset whose secret is set.
+  return Object.values(PRESET_SOURCES).filter(hasSecret);
+}

package/src/webhook-sources/presets/segment.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import type { IngestEvent } from "../../lib/ingestion.js";
+import { defineWebhookSource } from "../define-webhook-source.js";
+
+/**
+ * Segment webhook preset.
+ *
+ * Auth: generic HMAC-hex over the raw body (`x-signature`), verified with
+ * `node:crypto`. Set `SEGMENT_WEBHOOK_SECRET` to auto-enable at
+ * `POST /v1/webhooks/segment`.
+ *
+ * Event mapping (decision #16):
+ *  - `identify` → `contact.updated` (traits → `contactProperties` ONLY)
+ *  - `track`    → the literal `event` name (properties → `eventProperties` ONLY)
+ *  - `page` / `screen` / `group` / `alias` → skipped (`null`)
+ *
+ * Identity: `userId = userId ?? anonymousId`; `email` lifted from
+ * `traits.email`/`context.traits.email`. `idempotencyKey = messageId` so
+ * Segment redelivery dedupes on `user_events.idempotencyKey`.
+ */
+
+const segmentTraitsSchema = z.record(z.string(), z.unknown());
+
+const segmentWebhookSchema = z
+  .object({
+    type: z.string(),
+    event: z.string().nullish(),
+    messageId: z.string().nullish(),
+    userId: z.string().nullish(),
+    anonymousId: z.string().nullish(),
+    traits: segmentTraitsSchema.nullish(),
+    properties: z.record(z.string(), z.unknown()).nullish(),
+    context: z
+      .object({
+        traits: segmentTraitsSchema.nullish(),
+      })
+      .catchall(z.unknown())
+      .nullish(),
+  })
+  .catchall(z.unknown());
+
+type SegmentPayload = z.infer<typeof segmentWebhookSchema>;
+
+/** Pull a string email out of a traits bag, if present. */
+function emailFromTraits(
+  traits: Record<string, unknown> | null | undefined,
+): string | undefined {
+  const email = traits?.email;
+  return typeof email === "string" ? email : undefined;
+}
+
+export const segmentSource = defineWebhookSource({
+  meta: {
+    id: "segment",
+    name: "Segment",
+    description: "Receives Segment identify/track webhooks (HMAC-hex signed).",
+  },
+  auth: {
+    type: "signature",
+    scheme: "hmac-hex",
+    envKey: "SEGMENT_WEBHOOK_SECRET",
+    header: "x-signature",
+  },
+  schema: segmentWebhookSchema,
+  async transform(payload: SegmentPayload): Promise<IngestEvent | null> {
+    const userId = payload.userId ?? payload.anonymousId ?? undefined;
+    if (!userId) {
+      return null;
+    }
+
+    const traits = payload.traits ?? payload.context?.traits ?? undefined;
+    const userEmail =
+      emailFromTraits(payload.traits) ??
+      emailFromTraits(payload.context?.traits) ??
+      "";
+    const idempotencyKey = payload.messageId ?? undefined;
+
+    if (payload.type === "identify") {
+      // identify: traits are profile/identity → contactProperties ONLY.
+      const contactProperties: Record<string, unknown> = { ...(traits ?? {}) };
+      contactProperties.source = "segment";
+
+      return {
+        event: "contact.updated",
+        userId,
+        userEmail,
+        eventProperties: {
+          source: "segment",
+          _segmentType: "identify",
+        },
+        contactProperties,
+        ...(idempotencyKey ? { idempotencyKey } : {}),
+      };
+    }
+
+    if (payload.type === "track") {
+      const eventName = payload.event;
+      if (!eventName) {
+        return null;
+      }
+      // track: properties are behavioral → eventProperties ONLY.
+      const eventProperties: Record<string, unknown> = {
+        ...(payload.properties ?? {}),
+      };
+      eventProperties.source = "segment";
+
+      return {
+        event: eventName,
+        userId,
+        userEmail,
+        eventProperties,
+        contactProperties: {},
+        ...(idempotencyKey ? { idempotencyKey } : {}),
+      };
+    }
+
+    // page / screen / group / alias → skip.
+    return null;
+  },
+});

package/src/webhook-sources/presets/stripe.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import type { IngestEvent } from "../../lib/ingestion.js";
+import { defineWebhookSource } from "../define-webhook-source.js";
+
+/**
+ * Stripe webhook preset.
+ *
+ * Auth: Stripe's `stripe-signature: t=<ts>,v1=<hex>` header, verified with
+ * `node:crypto` (NO `stripe` SDK — decision #14). Set `STRIPE_WEBHOOK_SECRET`
+ * (the `whsec_…` endpoint secret) to auto-enable at `POST /v1/webhooks/stripe`.
+ *
+ * Event mapping (decision #16, normalized to the outbound vocabulary):
+ *  - `customer.created`              → `contact.created`
+ *  - `customer.updated`              → `contact.updated`
+ *  - `customer.deleted`             → `contact.deleted` (EVENT only — decision #15)
+ *  - `customer.subscription.<action>` → `subscription.<action>`
+ *  - `invoice.<action>`              → `invoice.<action>`
+ *
+ * Identity: `userId = obj.id` for customers, `obj.customer` for subscriptions /
+ * invoices. `idempotencyKey = payload.id` (the Stripe event id) so at-least-once
+ * redelivery dedupes on `user_events.idempotencyKey`.
+ *
+ * D2 split: customer profile (`name`, `phone`, `metadata`) → `contactProperties`
+ * ONLY; everything else → `eventProperties` ONLY.
+ */
+
+const stripeObjectSchema = z
+  .object({
+    id: z.string().optional(),
+    object: z.string().optional(),
+    customer: z.string().nullish(),
+    email: z.string().nullish(),
+    name: z.string().nullish(),
+    phone: z.string().nullish(),
+    metadata: z.record(z.string(), z.unknown()).nullish(),
+  })
+  .catchall(z.unknown());
+
+const stripeWebhookSchema = z
+  .object({
+    id: z.string(),
+    type: z.string(),
+    object: z.string().optional(),
+    data: z
+      .object({
+        object: stripeObjectSchema,
+      })
+      .catchall(z.unknown()),
+  })
+  .catchall(z.unknown());
+
+type StripePayload = z.infer<typeof stripeWebhookSchema>;
+
+export const stripeSource = defineWebhookSource({
+  meta: {
+    id: "stripe",
+    name: "Stripe",
+    description:
+      "Receives Stripe customer/subscription/invoice webhooks (signature-verified).",
+  },
+  auth: {
+    type: "signature",
+    scheme: "stripe",
+    envKey: "STRIPE_WEBHOOK_SECRET",
+    header: "stripe-signature",
+  },
+  schema: stripeWebhookSchema,
+  async transform(payload: StripePayload): Promise<IngestEvent | null> {
+    const type = payload.type;
+    const obj = payload.data.object;
+
+    // Normalize the Stripe event name → Hogsend vocabulary + resolve identity.
+    let event: string;
+    let userId: string | undefined;
+    let isCustomerLifecycle = false;
+    let isDelete = false;
+
+    if (type === "customer.created" || type === "customer.updated") {
+      event =
+        type === "customer.created" ? "contact.created" : "contact.updated";
+      userId = obj.id;
+      isCustomerLifecycle = true;
+    } else if (type === "customer.deleted") {
+      event = "contact.deleted";
+      userId = obj.id;
+      isDelete = true;
+    } else if (type.startsWith("customer.subscription.")) {
+      // customer.subscription.created/updated/deleted → subscription.<action>
+      const action = type.slice("customer.subscription.".length);
+      event = `subscription.${action}`;
+      userId = typeof obj.customer === "string" ? obj.customer : undefined;
+    } else if (type.startsWith("invoice.")) {
+      const action = type.slice("invoice.".length);
+      event = `invoice.${action}`;
+      userId = typeof obj.customer === "string" ? obj.customer : undefined;
+    } else {
+      return null;
+    }
+
+    if (!userId) {
+      return null;
+    }
+
+    const userEmail = typeof obj.email === "string" ? obj.email : "";
+
+    const eventProperties: Record<string, unknown> = {
+      source: "stripe",
+      stripeCustomerId: userId,
+      stripeEventId: payload.id,
+      _stripeEvent: type,
+      stripeObject: obj.object,
+    };
+
+    // Only the customer create/update lifecycle carries a profile to merge.
+    // Deletes (decision #15) and subscription/invoice events are event-only.
+    if (!isCustomerLifecycle || isDelete) {
+      return {
+        event,
+        userId,
+        userEmail,
+        eventProperties,
+        contactProperties: {},
+        idempotencyKey: payload.id,
+      };
+    }
+
+    const contactProperties: Record<string, unknown> = {
+      ...(obj.metadata ?? {}),
+    };
+    if (typeof obj.name === "string") {
+      contactProperties.name = obj.name;
+    }
+    if (typeof obj.phone === "string") {
+      contactProperties.phone = obj.phone;
+    }
+    contactProperties.stripeCustomerId = userId;
+
+    return {
+      event,
+      userId,
+      userEmail,
+      eventProperties,
+      contactProperties,
+      idempotencyKey: payload.id,
+    };
+  },
+});

package/src/webhook-sources/presets/supabase.ts

@@ -0,0 +1,131 @@
+import { z } from "zod";
+import type { IngestEvent } from "../../lib/ingestion.js";
+import { defineWebhookSource } from "../define-webhook-source.js";
+
+/**
+ * Supabase `auth.users` webhook preset.
+ *
+ * Auth: Svix-signed when Supabase's "Send HTTP Request" hook is configured with
+ * a signing secret; falls back to the plain `x-supabase-webhook-secret` shared
+ * secret (via `fallbackMatchHeader`) for the database-webhook trigger path. Set
+ * `SUPABASE_WEBHOOK_SECRET` to auto-enable at `POST /v1/webhooks/supabase`.
+ *
+ * Only `schema === "auth" && table === "users"` rows are processed (other tables
+ * are skipped). Event mapping (decision #16, normalized):
+ *  - `INSERT` → `contact.created`
+ *  - `UPDATE` → `contact.updated`
+ *  - `DELETE` → `contact.deleted` (EVENT only — decision #15)
+ *
+ * D2 split: profile fields → `contactProperties` ONLY; behavioral/source fields
+ * → `eventProperties` ONLY.
+ */
+
+const supabaseUserRowSchema = z
+  .object({
+    id: z.string().optional(),
+    email: z.string().nullish(),
+    phone: z.string().nullish(),
+    email_confirmed_at: z.string().nullish(),
+    raw_user_meta_data: z.record(z.string(), z.unknown()).nullish(),
+  })
+  .catchall(z.unknown());
+
+const supabaseWebhookSchema = z
+  .object({
+    type: z.enum(["INSERT", "UPDATE", "DELETE"]),
+    table: z.string(),
+    schema: z.string(),
+    record: supabaseUserRowSchema.nullish(),
+    old_record: supabaseUserRowSchema.nullish(),
+  })
+  .catchall(z.unknown());
+
+type SupabasePayload = z.infer<typeof supabaseWebhookSchema>;
+
+export const supabaseSource = defineWebhookSource({
+  meta: {
+    id: "supabase",
+    name: "Supabase",
+    description:
+      "Receives Supabase auth.users INSERT/UPDATE/DELETE webhooks (Svix-signed or shared-secret).",
+  },
+  auth: {
+    type: "signature",
+    scheme: "svix",
+    envKey: "SUPABASE_WEBHOOK_SECRET",
+    header: "svix-signature",
+    fallbackMatchHeader: "x-supabase-webhook-secret",
+  },
+  schema: supabaseWebhookSchema,
+  async transform(payload: SupabasePayload): Promise<IngestEvent | null> {
+    // Only auth.users mutations map to contacts; ignore everything else.
+    if (payload.schema !== "auth" || payload.table !== "users") {
+      return null;
+    }
+
+    let event: string;
+    switch (payload.type) {
+      case "INSERT":
+        event = "contact.created";
+        break;
+      case "UPDATE":
+        event = "contact.updated";
+        break;
+      case "DELETE":
+        event = "contact.deleted";
+        break;
+      default:
+        return null;
+    }
+
+    // DELETE carries the row in `old_record`; INSERT/UPDATE in `record`.
+    const row =
+      payload.type === "DELETE"
+        ? (payload.old_record ?? payload.record)
+        : (payload.record ?? payload.old_record);
+
+    if (!row) {
+      return null;
+    }
+
+    const userId = row.id;
+    if (!userId) {
+      return null;
+    }
+    const userEmail = typeof row.email === "string" ? row.email : "";
+
+    const eventProperties: Record<string, unknown> = {
+      source: "supabase",
+      supabaseUserId: userId,
+      _supabaseEvent: payload.type,
+    };
+
+    // Deletes carry no profile to merge — emit the event only (decision #15).
+    if (event === "contact.deleted") {
+      return {
+        event,
+        userId,
+        userEmail,
+        eventProperties,
+        contactProperties: {},
+      };
+    }
+
+    const contactProperties: Record<string, unknown> = {
+      ...(row.raw_user_meta_data ?? {}),
+    };
+    if (typeof row.phone === "string") {
+      contactProperties.phone = row.phone;
+    }
+    contactProperties.emailVerified = Boolean(row.email_confirmed_at);
+    contactProperties.supabaseUserId = userId;
+
+    return {
+      event,
+      userId,
+      userEmail,
+      eventProperties,
+      contactProperties,
+    };
+  },
+});

package/src/webhook-sources/verify.ts

@@ -0,0 +1,172 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Webhook } from "svix";
+
+/**
+ * The signature verification schemes understood by `defineWebhookSource`'s
+ * `auth.type: "signature"` variant. Each preset (Clerk, Supabase, Stripe,
+ * Segment) maps to one of these; the route resolves the secret from
+ * `env[auth.envKey]` and calls {@link verifySignature} BEFORE parsing/handing
+ * the payload to `transform()`.
+ *
+ *  - `"svix"`      — Standard Webhooks / Svix header set (`svix-id` /
+ *                    `svix-timestamp` / `svix-signature`). Reuses
+ *                    `svix`'s `Webhook.verify` (the same machinery `plugin-resend`
+ *                    uses for inbound Resend webhooks).
+ *  - `"stripe"`    — `stripe-signature: t=<ts>,v1=<hex>[,v1=<hex>...]`. Computes
+ *                    `HMAC_SHA256(secret, `${t}.${rawBody}`)` with `node:crypto`
+ *                    (NO `stripe` SDK), constant-time compares each `v1` candidate,
+ *                    and enforces the 5-minute timestamp tolerance.
+ *  - `"hmac-hex"`  — Generic `HMAC_SHA256(secret, rawBody)` rendered as lowercase
+ *                    hex, constant-time compared against the header value (e.g.
+ *                    Segment's `x-signature`).
+ */
+export type SignatureScheme = "svix" | "stripe" | "hmac-hex";
+
+export interface VerifySignatureArgs {
+  rawBody: string;
+  headers: Record<string, string>;
+  secret: string;
+}
+
+const STRIPE_TOLERANCE_SECONDS = 5 * 60;
+
+/**
+ * Lowercase every header key so callers can pass the raw (possibly Title-Case)
+ * header record and we still find `svix-id` / `stripe-signature` / `x-signature`.
+ */
+function lowerHeaders(headers: Record<string, string>): Record<string, string> {
+  const lowered: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    lowered[key.toLowerCase()] = value;
+  }
+  return lowered;
+}
+
+/**
+ * Constant-time string comparison that never short-circuits on length. Returns
+ * `false` (rather than throwing) on a length mismatch so callers fail closed.
+ */
+function safeEqual(a: string, b: string): boolean {
+  const bufA = Buffer.from(a, "utf8");
+  const bufB = Buffer.from(b, "utf8");
+  if (bufA.length !== bufB.length) {
+    return false;
+  }
+  return timingSafeEqual(bufA, bufB);
+}
+
+function verifySvix(args: VerifySignatureArgs): boolean {
+  const headers = lowerHeaders(args.headers);
+  const id = headers["svix-id"];
+  const timestamp = headers["svix-timestamp"];
+  const signature = headers["svix-signature"];
+
+  if (!id || !timestamp || !signature) {
+    return false;
+  }
+
+  try {
+    const wh = new Webhook(args.secret);
+    wh.verify(args.rawBody, {
+      "svix-id": id,
+      "svix-timestamp": timestamp,
+      "svix-signature": signature,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function verifyStripe(args: VerifySignatureArgs): boolean {
+  const headers = lowerHeaders(args.headers);
+  const header = headers["stripe-signature"];
+  if (!header) {
+    return false;
+  }
+
+  // `t=1700000000,v1=<hex>,v1=<hex>` — there may be more than one v1 candidate
+  // during a secret rotation and forward-compat `v0`/scheme fields we ignore.
+  let timestamp: string | undefined;
+  const signatures: string[] = [];
+  for (const part of header.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) {
+      continue;
+    }
+    const key = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (key === "t") {
+      timestamp = value;
+    } else if (key === "v1") {
+      signatures.push(value);
+    }
+  }
+
+  if (!timestamp || signatures.length === 0) {
+    return false;
+  }
+
+  const timestampSeconds = Number(timestamp);
+  if (!Number.isFinite(timestampSeconds)) {
+    return false;
+  }
+
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  if (Math.abs(nowSeconds - timestampSeconds) > STRIPE_TOLERANCE_SECONDS) {
+    return false;
+  }
+
+  const expected = createHmac("sha256", args.secret)
+    .update(`${timestamp}.${args.rawBody}`)
+    .digest("hex");
+
+  return signatures.some((candidate) => safeEqual(candidate, expected));
+}
+
+function verifyHmacHex(args: VerifySignatureArgs, headerName: string): boolean {
+  const headers = lowerHeaders(args.headers);
+  const provided = headers[headerName.toLowerCase()];
+  if (!provided) {
+    return false;
+  }
+
+  const expected = createHmac("sha256", args.secret)
+    .update(args.rawBody)
+    .digest("hex");
+
+  return safeEqual(provided.trim(), expected);
+}
+
+/**
+ * Verify an inbound provider webhook signature for the given scheme.
+ *
+ * FAILS CLOSED: returns `false` (never throws) whenever a required header is
+ * missing or the signature does not match. The route enforces that the secret
+ * itself is present before calling this — an unset signature secret is a 401,
+ * NOT an open pass-through (deliberate divergence from the `"match"` variant,
+ * which stays open when unconfigured).
+ *
+ * For `"hmac-hex"` the header carrying the hex digest is passed via `headerName`
+ * (e.g. Segment's `x-signature`); `svix`/`stripe` read their own well-known
+ * headers and ignore `headerName`.
+ */
+export function verifySignature(
+  scheme: SignatureScheme,
+  args: VerifySignatureArgs,
+  headerName?: string,
+): boolean {
+  switch (scheme) {
+    case "svix":
+      return verifySvix(args);
+    case "stripe":
+      return verifyStripe(args);
+    case "hmac-hex":
+      return verifyHmacHex(args, headerName ?? "x-signature");
+    default: {
+      // Exhaustiveness guard — an unknown scheme fails closed.
+      const _never: never = scheme;
+      return _never;
+    }
+  }
+}

package/src/worker.ts

@@ -16,6 +16,10 @@ import {
 } from "./workflows/bucket-backfill.js";
 import { bucketReconcileTask } from "./workflows/bucket-reconcile.js";
 import { checkAlertsTask } from "./workflows/check-alerts.js";
+import {
+  deliverWebhookTask,
+  reapDueWebhookDeliveriesTask,
+} from "./workflows/deliver-webhook.js";
 import { importContactsTask } from "./workflows/import-contacts.js";
 import {
   reapStuckCampaignsTask,
@@ -68,6 +72,8 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
     importContactsTask,
     sendCampaignTask,
     reapStuckCampaignsTask,
+    deliverWebhookTask,
+    reapDueWebhookDeliveriesTask,
     checkAlertsTask,
     bucketReconcileTask,
     bucketBackfillTask,