@hogsend/engine 0.7.0 → 0.9.0

package/src/lib/webhook-signing.ts

@@ -0,0 +1,152 @@
+import { randomBytes } from "node:crypto";
+import { Webhook } from "svix";
+
+/**
+ * Outbound webhook signing core.
+ *
+ * Hogsend emits a Svix-style HMAC-SHA256 signed event stream. The signing
+ * scheme is the Standard Webhooks spec (the same one `svix` implements and that
+ * `plugin-resend` consumes for inbound Resend webhooks):
+ *
+ *   signedContent = `${id}.${timestampSeconds}.${body}`
+ *   signature     = base64( HMAC_SHA256( base64decode(secret without `whsec_`), signedContent ) )
+ *   header value  = `v1,${signature}`
+ *
+ * Pure `node:crypto` equivalent (documented for the SDK / spec consumers and
+ * subscriber-side verification without a `svix` dependency):
+ *
+ *   import { createHmac, timingSafeEqual } from "node:crypto";
+ *   const key = Buffer.from(secret.slice(6), "base64"); // drop the `whsec_` prefix
+ *   const sig = createHmac("sha256", key)
+ *     .update(`${id}.${ts}.${body}`)
+ *     .digest("base64");
+ *   const header = `v1,${sig}`;
+ *   // compare each space-delimited `v1,<sig>` candidate with timingSafeEqual.
+ */
+
+/**
+ * The 13-event catalog — the SINGLE source of truth (schema, routes, client,
+ * CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
+ * member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
+ */
+export const WEBHOOK_EVENT_TYPES = [
+  "contact.created",
+  "contact.updated",
+  "contact.deleted",
+  "contact.unsubscribed",
+  "email.sent",
+  "email.delivered",
+  "email.opened",
+  "email.clicked",
+  "email.bounced",
+  "email.complained",
+  "journey.completed",
+  "bucket.entered",
+  "bucket.left",
+] as const;
+
+export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
+
+/**
+ * Generate a new `whsec_<base64(32 bytes)>` signing secret plus its display
+ * prefix (safe to surface on list/get responses).
+ *
+ * NOTE: the secret body is STANDARD base64, not base64url. svix (via
+ * standardwebhooks → @stablelib/base64) strips the `whsec_` prefix and decodes
+ * the remainder with a STRICT standard-base64 decoder that rejects the `-`/`_`
+ * characters base64url emits (~74% of base64url secrets contain one and fail
+ * `new Webhook(secret)`). Standard base64 round-trips cleanly through both svix
+ * and the `node:crypto` fallback (`Buffer.from(secret.slice(6), "base64")`).
+ */
+export function generateWebhookSecret(): {
+  secret: string;
+  secretPrefix: string;
+} {
+  const secret = `whsec_${randomBytes(32).toString("base64")}`;
+  return { secret, secretPrefix: secret.slice(0, 12) };
+}
+
+export interface SignedWebhook {
+  headers: {
+    "Webhook-Id": string;
+    "Webhook-Timestamp": string;
+    "Webhook-Signature": string;
+    "Content-Type": "application/json";
+  };
+  /**
+   * The EXACT bytes that were signed AND must be sent. Never re-stringify the
+   * payload between signing and sending — the signature covers these bytes.
+   */
+  body: string;
+}
+
+/**
+ * Sign an outbound webhook payload, producing the Standard Webhooks header set
+ * (`Webhook-Id` / `Webhook-Timestamp` / `Webhook-Signature`) plus the exact
+ * `body` bytes that were signed.
+ *
+ * `timestamp` is unix SECONDS — the caller passes `Math.floor(Date.now()/1000)`.
+ * `payload` is JSON-stringified when an object; a string is used verbatim.
+ */
+export function signWebhook(opts: {
+  id: string;
+  timestamp: number;
+  payload: unknown;
+  secret: string;
+}): SignedWebhook {
+  const body =
+    typeof opts.payload === "string"
+      ? opts.payload
+      : JSON.stringify(opts.payload);
+
+  const wh = new Webhook(opts.secret);
+  // svix's `sign` takes the timestamp as a Date and floors it to seconds
+  // internally; pass the canonical seconds back through a Date to keep the exact
+  // value the caller intended.
+  const signature = wh.sign(opts.id, new Date(opts.timestamp * 1000), body);
+
+  return {
+    headers: {
+      "Webhook-Id": opts.id,
+      "Webhook-Timestamp": String(opts.timestamp),
+      "Webhook-Signature": signature,
+      "Content-Type": "application/json",
+    },
+    body,
+  };
+}
+
+/**
+ * Consumer/test-facing verification of an inbound Hogsend webhook. Enforces the
+ * 5-minute timestamp tolerance and uses a constant-time signature compare (both
+ * inside svix). Throws on a bad signature or stale timestamp.
+ *
+ * Accepts either Title-Case (`Webhook-Id`) or lowercase (`webhook-id`) header
+ * keys — and the `svix-*` aliases — by normalizing the header map first.
+ */
+export function verifyWebhookSignature(opts: {
+  payload: string;
+  headers: Record<string, string>;
+  secret: string;
+}): unknown {
+  const lowered: Record<string, string> = {};
+  for (const [key, value] of Object.entries(opts.headers)) {
+    lowered[key.toLowerCase()] = value;
+  }
+
+  // Coalesce to "" so a genuinely-absent header reaches svix as an empty
+  // string — svix then throws its own clear "Missing required header" rather
+  // than a type error here.
+  const id = lowered["webhook-id"] ?? lowered["svix-id"] ?? "";
+  const timestamp =
+    lowered["webhook-timestamp"] ?? lowered["svix-timestamp"] ?? "";
+  const signature =
+    lowered["webhook-signature"] ?? lowered["svix-signature"] ?? "";
+
+  const wh = new Webhook(opts.secret);
+  return wh.verify(opts.payload, {
+    "webhook-id": id,
+    "webhook-timestamp": timestamp,
+    "webhook-signature": signature,
+  });
+}

package/src/routes/admin/contacts.ts

@@ -9,6 +9,7 @@ import {
   serializeContact as serializeContactRow,
   serializePrefs,
 } from "../../lib/contacts.js";
+import { emitOutbound } from "../../lib/outbound.js";
 
 const contactSchema = z.object({
   id: z.string(),
@@ -262,13 +263,18 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
     );
   })
   .openapi(createRoute_, async (c) => {
-    const { db } = c.get("container");
+    const { db, hatchet, logger } = c.get("container");
     const body = c.req.valid("json");
 
     // Delegate to the identity resolver (D1): it upserts/merges on the provided
     // identity keys (externalId and/or email), so the hand-rolled existence
     // check + raw insert + 409 are gone (§5). Read the row back to serialize.
-    const { id } = await resolveOrCreateContact({
+    const {
+      id,
+      created: wasCreated,
+      linked,
+      merged,
+    } = await resolveOrCreateContact({
       db,
       userId: body.externalId,
       email: body.email,
@@ -280,10 +286,26 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
       throw new Error("Failed to create contact");
     }
 
+    // INTENT-LAYER outbound emit (decision #3): admin upsert mirrors the public
+    // route — `contact.created` on a real creation, `contact.updated` when an
+    // existing contact was linked/merged with a non-empty property delta.
+    const hadPropertyDelta = Boolean(
+      body.properties && Object.keys(body.properties).length > 0,
+    );
+    if (wasCreated || (linked || merged ? hadPropertyDelta : false)) {
+      void emitOutbound({
+        db,
+        hatchet,
+        logger,
+        event: wasCreated ? "contact.created" : "contact.updated",
+        payload: serializeContactRow(created),
+      }).catch(logger.warn);
+    }
+
     return c.json({ contact: serializeContact(created) }, 201);
   })
   .openapi(updateRoute, async (c) => {
-    const { db } = c.get("container");
+    const { db, hatchet, logger } = c.get("container");
     const { id } = c.req.valid("param");
     const body = c.req.valid("json");
 
@@ -331,6 +353,24 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
       throw new Error("Failed to update contact");
     }
 
+    // INTENT-LAYER outbound emit (decision #3): the admin update is an explicit
+    // edit — emit `contact.updated` on a non-empty property delta or a filled
+    // email (a newly-attached identity). Fire-and-forget; the serialized updated
+    // row is the catalog payload.
+    const hadPropertyDelta = Boolean(
+      body.properties && Object.keys(body.properties).length > 0,
+    );
+    const filledEmail = Boolean(body.email && body.email !== current.email);
+    if (hadPropertyDelta || filledEmail) {
+      void emitOutbound({
+        db,
+        hatchet,
+        logger,
+        event: "contact.updated",
+        payload: serializeContactRow(updated),
+      }).catch(logger.warn);
+    }
+
     return c.json({ contact: serializeContact(updated) }, 200);
   })
   .openapi(deleteRoute, async (c) => {

package/src/routes/admin/index.ts

@@ -20,6 +20,7 @@ import { reportingRouter } from "./reporting.js";
 import { suppressionsRouter } from "./suppressions.js";
 import { templatesRouter } from "./templates.js";
 import { timelineRouter } from "./timeline.js";
+import { webhooksRouter } from "./webhooks.js";
 
 export const adminRouter = new OpenAPIHono<AppEnv>();
 adminRouter.use("*", requireAdmin);
@@ -39,6 +40,7 @@ adminRouter.route("/reporting", reportingRouter);
 adminRouter.route("/templates", templatesRouter);
 adminRouter.route("/suppressions", suppressionsRouter);
 adminRouter.route("/api-keys", apiKeysRouter);
+adminRouter.route("/webhooks", webhooksRouter);
 adminRouter.route("/audit-logs", auditLogsRouter);
 adminRouter.route("/alerts", alertsRouter);
 adminRouter.route("/dlq", dlqRouter);