@hogsend/engine 0.21.1 → 0.23.0

package/src/routes/tracking/click.ts

@@ -38,6 +38,8 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
         id: trackedLinks.id,
         originalUrl: trackedLinks.originalUrl,
         emailSendId: trackedLinks.emailSendId,
+        distinctId: trackedLinks.distinctId,
+        source: trackedLinks.source,
         event: trackedLinks.event,
         eventProperties: trackedLinks.eventProperties,
       })
@@ -56,10 +58,17 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
       null;
     const userAgent = c.req.header("user-agent") ?? null;
 
+    // The linkClicks insert + clickCount increment stay UNCONDITIONAL — every
+    // tracked link counts clicks, email or not.
+    //
     // First-touch state UPDATE: the `WHERE clickedAt IS NULL` sets `clickedAt`
     // exactly once (the first click), which is the row-level state we keep. The
     // outbound emit is NO LONGER gated on this — every destination must receive
-    // EVERY click (owner decision 1), so the emit below fires per-hit.
+    // EVERY click (owner decision 1), so the emit below fires per-hit. The
+    // emailSends update is GATED on `emailSendId != null` (MF-6): a non-email
+    // link has no send row to mark. This was previously safe-by-accident
+    // (`WHERE id = NULL` matches nothing) — the gate makes it explicit.
+    const emailSendId = link.emailSendId;
     await Promise.all([
       db.insert(linkClicks).values({
         trackedLinkId: link.id,
@@ -73,18 +82,22 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
           updatedAt: new Date(),
         })
         .where(eq(trackedLinks.id, link.id)),
-      db
-        .update(emailSends)
-        .set({
-          clickedAt: new Date(),
-          updatedAt: new Date(),
-        })
-        .where(
-          and(
-            eq(emailSends.id, link.emailSendId),
-            isNull(emailSends.clickedAt),
-          ),
-        ),
+      ...(emailSendId
+        ? [
+            db
+              .update(emailSends)
+              .set({
+                clickedAt: new Date(),
+                updatedAt: new Date(),
+              })
+              .where(
+                and(
+                  eq(emailSends.id, emailSendId),
+                  isNull(emailSends.clickedAt),
+                ),
+              ),
+          ]
+        : []),
     ]);
 
     const { hatchet, registry, logger } = c.get("container");
@@ -93,8 +106,11 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
     // deferred past the scanner-burst window (a Hatchet task) so the gate can
     // see the WHOLE burst — an inline check could never suppress a scanner's
     // first click. The task claims the send's answer slot (first answer wins)
-    // and emits the consumer event + email.action outbound.
-    if (link.event) {
+    // and emits the consumer event + email.action outbound. GATED on
+    // `emailSendId != null` (MF-6): the confirm task is email-semantic (it
+    // claims a send's answer slot + emits `email.action`), so a non-email
+    // semantic link would have no send to confirm against.
+    if (link.event && emailSendId) {
       void confirmSemanticClickTask
         .runNoWait({
           trackedLinkId: link.id,
@@ -110,27 +126,48 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
     }
 
     // Cross-device identity stitch (opt-in): append a short-lived signed
-    // `hs_t` token to the destination so the landing site can identify the
-    // session. This is the ONE path that needs the send context BEFORE the
-    // redirect — the awaited resolve is shared with the async chain below so
-    // the read still happens once.
+    // `hs_t` token to the destination so the landing site can fold its own anon
+    // session INTO the subject at `/v1/t/identify`. Two mint sources by link
+    // type (§6.5): a stitch-bearing NON-email link mints from its own
+    // `distinct_id` (`src: "<source>:<id>"`); an EMAIL link mints from the
+    // resolved send context; a BROADCAST link (no `distinct_id`, no send) mints
+    // nothing. The token is minted at CLICK time only — never stored on the
+    // shareable `/v1/t/c/:id` artifact (§6.3). The awaited send resolve is
+    // shared with the async chain below so the read still happens once.
     let redirectUrl = link.originalUrl;
     let preResolved: Awaited<
       ReturnType<typeof resolveEmailSendContext>
     > | null = null;
     let preResolvedSet = false;
     if (env.TRACKING_IDENTITY_TOKEN) {
-      preResolved = await resolveEmailSendContext(db, link.emailSendId);
-      preResolvedSet = true;
-      if (preResolved?.userId) {
+      let tokenDistinctId: string | null = null;
+      let tokenSrc: string | null = null;
+      if (link.distinctId) {
+        // Stitch-bearing non-email link: the subject is the link's own
+        // `distinct_id` (canonical key). No send resolve needed.
+        tokenDistinctId = link.distinctId;
+        tokenSrc = `${link.source ?? "link"}:${link.id}`;
+      } else if (emailSendId) {
+        // Email link: resolve the recipient's canonical key from the send row.
+        preResolved = await resolveEmailSendContext(db, emailSendId);
+        preResolvedSet = true;
+        if (preResolved?.userId) {
+          tokenDistinctId = preResolved.userId;
+          tokenSrc = `email:${emailSendId}`;
+        }
+      }
+      // else: broadcast link (no distinctId, no send) — mint nothing.
+
+      if (tokenDistinctId && tokenSrc) {
         try {
           const url = new URL(link.originalUrl);
           url.searchParams.set(
             "hs_t",
             generateIdentityToken({
               secret: env.BETTER_AUTH_SECRET,
-              distinctId: preResolved.userId,
-              emailSendId: link.emailSendId,
+              distinctId: tokenDistinctId,
+              src: tokenSrc,
+              emailSendId: emailSendId ?? undefined,
             }),
           );
           redirectUrl = url.toString();
@@ -141,58 +178,80 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
       }
     }
 
-    // Resolve the send context ONCE (off the response path) and feed both the
-    // re-ingest and the PER-HIT outbound emit — avoiding a duplicate
-    // `resolveEmailSendContext` read on the click hot path. NO `dedupeKey`: a
-    // NULL dedupe key is distinct in Postgres, so every click creates a fresh
-    // delivery to every subscribed destination (per-hit, not first-touch).
-    const emailSendId = link.emailSendId;
-    void (
-      preResolvedSet
-        ? Promise.resolve(preResolved)
-        : resolveEmailSendContext(db, emailSendId)
-    )
-      .then(async (ctx) => {
-        await pushTrackingEvent({
-          db,
-          hatchet,
-          registry,
-          logger,
-          event: EMAIL_LINK_CLICKED,
-          emailSendId,
-          properties: { linkUrl: link.originalUrl, linkId: link.id },
-          resolvedContext: ctx,
-        }).catch((err) => {
-          logger.warn("Failed to push click tracking event", {
-            linkId: link.id,
-            error: err instanceof Error ? err.message : String(err),
-          });
-        });
-
-        // Only emit when the send-context resolved. A missing emailSends row
-        // (orphaned tracked link / deleted send) has no userId or recipient to
-        // attribute, and a keyed destination (PostHog) would otherwise receive
-        // an empty distinct_id. A normal click always resolves a non-null userId.
-        if (ctx) {
-          await emitOutbound({
+    // PER-HIT outbound emit, off the response path. EMAIL links re-ingest the
+    // first-party `email.link_clicked` event (journey routing + userEvents) and
+    // emit `email.clicked`; NON-email links emit `link.clicked` instead — never
+    // a malformed `email.clicked` (MF-missing #3). NO `dedupeKey`: a NULL dedupe
+    // key is distinct in Postgres, so every click creates a fresh delivery to
+    // every subscribed destination (per-hit, not first-touch).
+    if (emailSendId) {
+      void (
+        preResolvedSet
+          ? Promise.resolve(preResolved)
+          : resolveEmailSendContext(db, emailSendId)
+      )
+        .then(async (ctx) => {
+          await pushTrackingEvent({
             db,
             hatchet,
+            registry,
             logger,
-            event: "email.clicked",
-            payload: {
-              emailSendId,
-              messageId: ctx.messageId ?? null,
-              templateKey: ctx.templateKey ?? null,
-              userId: ctx.userId ?? null,
-              to: ctx.to ?? ctx.userEmail ?? "",
-              at: new Date().toISOString(),
-              linkUrl: link.originalUrl,
+            event: EMAIL_LINK_CLICKED,
+            emailSendId,
+            properties: { linkUrl: link.originalUrl, linkId: link.id },
+            resolvedContext: ctx,
+          }).catch((err) => {
+            logger.warn("Failed to push click tracking event", {
               linkId: link.id,
-            },
+              error: err instanceof Error ? err.message : String(err),
+            });
           });
-        }
-      })
-      .catch(logger.warn);
+
+          // Only emit when the send-context resolved. A missing emailSends row
+          // (orphaned tracked link / deleted send) has no userId or recipient to
+          // attribute, and a keyed destination (PostHog) would otherwise receive
+          // an empty distinct_id. A normal click always resolves a non-null userId.
+          if (ctx) {
+            await emitOutbound({
+              db,
+              hatchet,
+              logger,
+              event: "email.clicked",
+              payload: {
+                emailSendId,
+                messageId: ctx.messageId ?? null,
+                templateKey: ctx.templateKey ?? null,
+                userId: ctx.userId ?? null,
+                to: ctx.to ?? ctx.userEmail ?? "",
+                at: new Date().toISOString(),
+                linkUrl: link.originalUrl,
+                linkId: link.id,
+              },
+            });
+          }
+        })
+        .catch(logger.warn);
+    } else {
+      // Non-email tracked link: emit the catalogued `link.clicked` (NOT
+      // `email.clicked`). `userId` is the link's stitch subject when
+      // identity-bearing, else null for a broadcast link. No re-ingest — the
+      // first-party `email.link_clicked` bus event is email-semantic.
+      void emitOutbound({
+        db,
+        hatchet,
+        logger,
+        event: "link.clicked",
+        payload: {
+          linkId: link.id,
+          source: link.source ?? null,
+          userId: link.distinctId ?? null,
+          emailSendId: null,
+          messageId: null,
+          linkUrl: link.originalUrl,
+          at: new Date().toISOString(),
+        },
+      }).catch(logger.warn);
+    }
 
     return c.redirect(redirectUrl, 302);
   },

package/src/routes/tracking/identify.ts

@@ -6,26 +6,40 @@ import {
 } from "../../lib/identity-token.js";
 
 /**
- * Exchange a redirect identity token (`hs_t`) for the distinct id. Called by
- * the LANDING SITE's frontend (CORS is open app-wide) after the user arrives
- * from a tracked email link; the site then calls `posthog.identify` (or its
- * analytics equivalent) with the result — ideally gated behind whatever
- * analytics consent the site already operates under.
+ * Exchange a redirect identity token (`hs_t`) for the distinct id, AND — when
+ * the caller supplies its own browser anon id (`currentDistinctId`) and the
+ * active analytics provider can merge — fire a SERVER-SIDE `alias` folding the
+ * caller's own anon session INTO the token's canonical subject. Called by the
+ * LANDING SITE's frontend (CORS is open app-wide) after the user arrives from a
+ * tracked link.
  *
  * Possession of a fresh signed token IS the authorization (the same trust
  * model as unsubscribe links): tokens are signed with BETTER_AUTH_SECRET,
- * expire after an hour, and resolve to nothing but the distinct id + send id.
+ * expire after an hour, and resolve to nothing but the canonical key + src.
+ *
+ * ANTI-HIJACK (MF-4): the route NEVER passes `currentDistinctId` as the
+ * survivor and NEVER server-identifies it. A forwarded-token holder can, at
+ * worst, fold THEIR OWN anon session into the subject — never overwrite the
+ * subject, never become the subject, never name a victim's anon id (they don't
+ * know it). A scanner following the redirect runs no posthog-js, so it supplies
+ * no `currentDistinctId` and the merge no-ops — the exchange is inert for
+ * headless prefetch.
  */
 const identifyRoute = createRoute({
   method: "post",
   path: "/identify",
   tags: ["Tracking"],
-  summary: "Exchange a redirect identity token for the distinct id",
+  summary: "Exchange a redirect identity token + optionally alias the caller",
   request: {
     body: {
       content: {
         "application/json": {
-          schema: z.object({ token: z.string().min(1).max(2048) }),
+          schema: z.object({
+            token: z.string().min(1).max(2048),
+            // The caller's OWN browser anon distinct id, to be folded INTO the
+            // token subject. Optional — absent = legacy resolve-only behaviour.
+            currentDistinctId: z.string().min(1).max(200).optional(),
+          }),
         },
       },
     },
@@ -35,8 +49,11 @@ const identifyRoute = createRoute({
       description: "Resolved identity",
       content: {
         "application/json": {
+          // ONE response schema across §6 (MF-5): `src` is the new field,
+          // `emailSendId` retained for the one-minor deprecation window.
           schema: z.object({
             distinctId: z.string(),
+            src: z.string(),
             emailSendId: z.string().optional(),
           }),
         },
@@ -49,23 +66,53 @@ const identifyRoute = createRoute({
 export const identifyRouter = new OpenAPIHono<AppEnv>().openapi(
   identifyRoute,
   async (c) => {
-    const { token } = c.req.valid("json");
-    const { env } = c.get("container");
+    const { token, currentDistinctId } = c.req.valid("json");
+    const { env, analytics, logger } = c.get("container");
 
+    let payload: ReturnType<typeof validateIdentityToken>;
     try {
-      const payload = validateIdentityToken({
+      payload = validateIdentityToken({
         token,
         secret: env.BETTER_AUTH_SECRET,
       });
-      return c.json(
-        { distinctId: payload.distinctId, emailSendId: payload.emailSendId },
-        200,
-      );
     } catch (err) {
       if (err instanceof InvalidIdentityTokenError) {
         return c.body(null, 400);
       }
       throw err;
     }
+
+    // MF-5 — fire the alias FIRE-AND-FORGET (never await on the response path)
+    // and respond synchronously. The token-proven canonical key is the survivor;
+    // the caller's own session is the absorbed (anonymous) side. A provider
+    // without `identityMerge` (or no provider) skips the merge cleanly — the
+    // client falls back to its existing best-effort `posthog.identify`.
+    if (
+      currentDistinctId &&
+      analytics?.capabilities.identityMerge &&
+      analytics.mergeIdentities &&
+      currentDistinctId !== payload.distinctId
+    ) {
+      try {
+        analytics.mergeIdentities({
+          distinctId: payload.distinctId,
+          alias: currentDistinctId,
+        });
+      } catch (err) {
+        // Best-effort — a provider error must never fail the exchange.
+        logger.warn("identify: mergeIdentities failed", {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    return c.json(
+      {
+        distinctId: payload.distinctId,
+        src: payload.src,
+        emailSendId: payload.emailSendId,
+      },
+      200,
+    );
   },
 );

package/src/routes/webhooks/index.ts

@@ -1,12 +1,12 @@
 import type { OpenAPIHono } from "@hono/zod-openapi";
 import type { AppEnv } from "../../app.js";
-import type { DefinedWebhookSource } from "../../webhook-sources/define-webhook-source.js";
+import type { DefinedConnector } from "../../connectors/define-connector.js";
 import { registerEmailProviderRoutes } from "./email-provider.js";
 import { resendWebhookRouter } from "./resend.js";
 import { registerWebhookSourceRoutes } from "./sources.js";
 
 export interface RegisterWebhookRoutesOptions {
-  webhookSources: DefinedWebhookSource[];
+  webhookConnectors: DefinedConnector[]; // pre-filtered to transport "webhook"
 }
 
 export function registerWebhookRoutes(
@@ -20,5 +20,5 @@ export function registerWebhookRoutes(
   //  3. the `/v1/webhooks/:sourceId` consumer-source catch-all (LAST).
   app.route("/v1/webhooks", resendWebhookRouter);
   registerEmailProviderRoutes(app);
-  registerWebhookSourceRoutes(app, opts.webhookSources);
+  registerWebhookSourceRoutes(app, opts.webhookConnectors);
 }

package/src/routes/webhooks/sources.ts

@@ -1,11 +1,11 @@
 import type { Database } from "@hogsend/db";
 import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
 import type { AppEnv } from "../../app.js";
+import type { DefinedConnector } from "../../connectors/define-connector.js";
 import { headersToRecord } from "../../lib/headers.js";
 import { ingestEvent } from "../../lib/ingestion.js";
 import type { Logger } from "../../lib/logger.js";
 import { getDerivedCredential } from "../../lib/provider-credentials.js";
-import type { DefinedWebhookSource } from "../../webhook-sources/define-webhook-source.js";
 import { verifySignature } from "../../webhook-sources/verify.js";
 
 /** Negative-cache window for the stored PostHog secret (mirrors the token
@@ -64,7 +64,7 @@ export function invalidateStoredPosthogSecret(): void {
 
 export function registerWebhookSourceRoutes(
   app: OpenAPIHono<AppEnv>,
-  sources: DefinedWebhookSource[],
+  sources: DefinedConnector[], // already filtered to transport === "webhook"
 ) {
   // Reserve `email` for the email-provider route
   // (`POST /v1/webhooks/email/:providerId`). A source with `meta.id === "email"`
@@ -122,6 +122,12 @@ export function registerWebhookSourceRoutes(
       return c.json({ error: "Unknown webhook source" }, 404);
     }
 
+    // Webhook-transport connectors always carry inboundVerify (defineConnector
+    // enforces it at authoring time). Narrow once so the rest of the auth ladder
+    // is byte-identical to the pre-connector source dispatch.
+    const auth = source.inboundVerify;
+    if (!auth) return c.json({ error: "Unknown webhook source" }, 404);
+
     const { db, logger, env, registry, hatchet } = c.get("container");
 
     // Read the body ONCE as the EXACT received bytes — signature schemes verify
@@ -129,9 +135,7 @@ export function registerWebhookSourceRoutes(
     const rawBody = await c.req.text();
     const headers = headersToRecord(c.req.raw.headers);
 
-    let secret = env[source.auth.envKey as keyof typeof env] as
-      | string
-      | undefined;
+    let secret = env[auth.envKey as keyof typeof env] as string | undefined;
 
     // For the inbound PostHog source, fall back to the secret minted by
     // `hogsend connect` (kind="derived" store) when env has none — so an
@@ -139,13 +143,13 @@ export function registerWebhookSourceRoutes(
     // neither env nor the store has a secret (current behavior preserved).
     if (
       !secret &&
-      source.auth.type === "match" &&
-      source.auth.envKey === "POSTHOG_WEBHOOK_SECRET"
+      auth.type === "match" &&
+      auth.envKey === "POSTHOG_WEBHOOK_SECRET"
     ) {
       secret = await resolveStoredPosthogSecret(db, logger);
     }
 
-    if (source.auth.type === "signature") {
+    if (auth.type === "signature") {
       // Signature sources FAIL CLOSED: an unset secret is a 401, never an open
       // pass-through (deliberate divergence from the "match" variant).
       if (!secret) {
@@ -155,7 +159,6 @@ export function registerWebhookSourceRoutes(
         return c.json({ error: "Webhook signature not configured" }, 401);
       }
 
-      const auth = source.auth;
       let verified = false;
 
       if (auth.verify) {
@@ -183,7 +186,7 @@ export function registerWebhookSourceRoutes(
       // (parity with the pre-engine route).
       if (secret) {
         const provided =
-          headers[source.auth.header.toLowerCase()] ??
+          headers[auth.header.toLowerCase()] ??
           headers.authorization?.replace("Bearer ", "");
 
         if (provided !== secret) {
@@ -216,6 +219,7 @@ export function registerWebhookSourceRoutes(
     const event = await source.transform(payload, {
       db,
       logger,
+      transport: "webhook",
       rawBody,
       headers,
     });
@@ -230,6 +234,12 @@ export function registerWebhookSourceRoutes(
       ok: true,
       event: event.event,
       userId: event.userId,
+      // INTENTIONALLY the ExitResult[] ARRAY (not `.length`) — preserved
+      // byte-for-byte for back-compat. The OpenAPI schema declares
+      // `exits: z.number().optional()`, but this route has always returned the
+      // array; the NEW `/v1/connectors/:id/ingress` route returns
+      // `result.exits.length` as a deliberate divergence. Do NOT "tidy" either
+      // to match the other.
       exits: result.exits,
     });
   });

package/src/webhook-sources/define-webhook-source.ts

@@ -1,52 +1,36 @@
 import type { Database } from "@hogsend/db";
 import type { z } from "zod";
+import {
+  type ConnectorCtx,
+  type DefinedConnector,
+  defineConnector,
+  type InboundVerifyAuth,
+} from "../connectors/define-connector.js";
 import type { IngestEvent } from "../lib/ingestion.js";
 import type { Logger } from "../lib/logger.js";
-import type { SignatureScheme, VerifySignatureArgs } from "./verify.js";
 
 /**
- * How a webhook source authenticates inbound requests.
+ * @deprecated naming only — `defineWebhookSource` is now the
+ * `transport: "webhook"` specialization of {@link defineConnector}, kept as a
+ * behavior- and signature-identical alias. NO migration is required.
  *
- * A discriminated union on `type`:
+ * `WebhookSourceAuth` is an alias of the connector's inbound-verify union —
+ * IDENTICAL shape today, so every existing source's `auth` keeps type-checking.
  *
- *  - `"match"` — plain shared-secret equality. The route compares a configured
- *    secret against the request header (or `Authorization: Bearer`). When the
- *    secret is UNSET the source stays OPEN (parity with the pre-engine route);
- *    this variant is unchanged so PostHog + all consumer sources keep compiling.
- *
- *  - `"signature"` — provider HMAC signature verification (Svix / Stripe /
- *    generic hex HMAC). The route resolves the secret from `env[envKey]`, reads
- *    the EXACT raw request body, and calls `verifySignature` (or the optional
- *    per-source `verify` override) over those bytes. Signature sources FAIL
- *    CLOSED (401) when their secret is unset — they are security-sensitive.
+ * SURFACE PIN: this alias must stay byte-for-byte equal to the frozen
+ * `{ match | signature }` webhook auth shape. `__tests__/connectors.test.ts`
+ * has a type-level assertion (`expectTypeOf<WebhookSourceAuth>()...`) that fails
+ * the build if `InboundVerifyAuth` ever gains a third variant — so a future
+ * additive change to the connector union can never silently widen this frozen
+ * public webhook-source surface.
  */
-export type WebhookSourceAuth =
-  | {
-      type: "match";
-      header: string;
-      envKey: string;
-    }
-  | {
-      type: "signature";
-      scheme: SignatureScheme;
-      envKey: string;
-      header: string;
-      /**
-       * For schemes (notably `"svix"`) whose providers may also send a plain
-       * shared-secret header: when the scheme's signature headers are absent but
-       * this header matches the secret verbatim, accept the request. Lets
-       * Supabase's `x-supabase-webhook-secret` plain-secret mode coexist with
-       * its Svix mode.
-       */
-      fallbackMatchHeader?: string;
-      /**
-       * Optional per-source override of the built-in scheme verification. When
-       * provided, the route calls this INSTEAD of `verifySignature(scheme, …)`.
-       * Receives the EXACT received bytes; must return (or resolve to) a boolean.
-       */
-      verify?(args: VerifySignatureArgs): boolean | Promise<boolean>;
-    };
+export type WebhookSourceAuth = InboundVerifyAuth;
 
+/**
+ * Unchanged public shape. `ctx` stays the narrow webhook-only context —
+ * `ConnectorCtx` minus `transport` — so consumer transforms typed against this
+ * are byte-for-byte source-compatible.
+ */
 export interface WebhookSourceCtx {
   db: Database;
   logger: Logger;
@@ -73,9 +57,30 @@ export interface DefinedWebhookSource<T = unknown> {
   transform(payload: T, ctx: WebhookSourceCtx): Promise<IngestEvent | null>;
 }
 
+/**
+ * Lift a `DefinedWebhookSource` onto the connector umbrella as a
+ * `transport: "webhook"` connector: `auth` → `inboundVerify`, transform `ctx`
+ * widened to {@link ConnectorCtx} (the webhook route always sets
+ * `transport: "webhook"` + `rawBody`/`headers`). Used by the container to
+ * register webhook sources into the unified {@link ConnectorRegistry}.
+ */
+export function webhookSourceToConnector<T>(
+  source: DefinedWebhookSource<T>,
+): DefinedConnector<T> {
+  return defineConnector<T>({
+    meta: { ...source.meta, transport: "webhook" },
+    inboundVerify: source.auth,
+    schema: source.schema,
+    transform: (payload: T, ctx: ConnectorCtx) =>
+      source.transform(payload, ctx),
+  });
+}
+
 export function defineWebhookSource<T>(
   def: DefinedWebhookSource<T>,
 ): DefinedWebhookSource<T> {
+  // Unchanged contract: returns its argument. The container converts it via
+  // webhookSourceToConnector when building the registry.
   return def;
 }
 

package/src/webhook-sources/verify.ts

@@ -45,8 +45,11 @@ function lowerHeaders(headers: Record<string, string>): Record<string, string> {
 /**
  * Constant-time string comparison that never short-circuits on length. Returns
  * `false` (rather than throwing) on a length mismatch so callers fail closed.
+ * Exported so the connector ingress route reuses ONE hardened compare rather
+ * than re-implementing `Buffer.from` + `timingSafeEqual` inline (where a later
+ * refactor could drop the length guard and reintroduce the throw-on-mismatch).
  */
-function safeEqual(a: string, b: string): boolean {
+export function safeEqual(a: string, b: string): boolean {
   const bufA = Buffer.from(a, "utf8");
   const bufB = Buffer.from(b, "utf8");
   if (bufA.length !== bufB.length) {