@hogsend/engine 0.21.1 → 0.23.0

package/src/routes/connectors/index.ts

@@ -0,0 +1,279 @@
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
+import type { AppEnv } from "../../app.js";
+import type { DefinedConnector } from "../../connectors/define-connector.js";
+import { getConnectorRegistry } from "../../connectors/registry-singleton.js";
+import { verifyConnectorState } from "../../lib/connector-state.js";
+import { headersToRecord } from "../../lib/headers.js";
+import { ingestEvent } from "../../lib/ingestion.js";
+import type { Logger } from "../../lib/logger.js";
+import { getRedisIfConnected } from "../../lib/redis.js";
+import { clientIpKey, createRateLimit } from "../../middleware/rate-limit.js";
+import { safeEqual } from "../../webhook-sources/verify.js";
+
+/**
+ * Diagnose a registered-but-bare connector: a `transport: "gateway"` connector
+ * present in the registry that ships NO `handlers` cannot answer the generic
+ * oauth/interactions dispatch and would otherwise 404 silently (looking like an
+ * unknown connector). Log a warning so a misconfigured bare-connector
+ * registration (the bare `discordConnector` vs. `createDiscordConnector(...)`)
+ * is diagnosable. A genuinely unknown id (no connector) stays a quiet 404.
+ */
+function warnBareGatewayConnector(
+  logger: Logger,
+  id: string,
+  connector: DefinedConnector | undefined,
+  surface: "oauthCallback" | "interactions",
+): void {
+  if (connector && (connector.meta.transport ?? "webhook") === "gateway") {
+    logger.warn(
+      "connector registered without handlers — gateway connector cannot " +
+        `serve ${surface}; register the connect-ready factory (e.g. ` +
+        "createDiscordConnector(config)) instead of the bare const",
+      { connectorId: id, surface },
+    );
+  }
+}
+
+/**
+ * The generic connector dispatch surface: oauth/interactions/ingress. These
+ * routes are UNAUTHENTICATED at the api-key layer BY DESIGN — each
+ * self-authenticates (oauth `state` + code exchange, ed25519 interaction
+ * signatures, the shared ingress secret). Do NOT add a blanket api-key guard.
+ *
+ * Because they are public + self-verifying, an attacker can otherwise hammer
+ * them to force an ed25519 verify / constant-time secret compare per request
+ * (CPU amplification). So we layer an IP-keyed sliding-window rate limit on the
+ * whole `/v1/connectors/*` subtree (distinct prefix → isolated budget, mirroring
+ * the sign-up throttle in app.ts).
+ */
+export function registerConnectorRoutes(app: OpenAPIHono<AppEnv>) {
+  const connectorRateLimit = createRateLimit({
+    prefix: "ratelimit:connectors",
+    windowMs: 60_000,
+    max: 60,
+    keyFn: clientIpKey,
+  });
+  // `/ingress` is authed by the shared ingress secret (hit once per event by the
+  // trusted gateway worker); `/interactions` is authed by Discord's ed25519
+  // signature + a timestamp replay window. BOTH arrive from a SMALL set of source
+  // IPs (the worker behind a tunnel; Discord's interaction egress), so per-IP
+  // keying would collapse a whole community onto ONE 60/min bucket and 429 the
+  // very /link & /verify loop we ship (Discord renders a 429 as "the application
+  // did not respond"). The IP limit is sized for the public, self-verifying OAuth
+  // callback — keep it there only; the ed25519 verify + replay window already
+  // gate /interactions, and the constant-time secret compare gates /ingress.
+  app.use("/v1/connectors/*", async (c, next) => {
+    const p = c.req.path;
+    if (p.endsWith("/ingress") || p.endsWith("/interactions")) return next();
+    return connectorRateLimit(c, next);
+  });
+
+  // --- OAuth callback: GET|POST /v1/connectors/:id/oauth/callback -----------
+  // GET handles the browser redirect-URI return (most OAuth flows); a POST
+  // variant is mounted too for connectors that prefer it. Both dispatch to
+  // handlers.oauthCallback.
+  for (const method of ["get", "post"] as const) {
+    app.openapi(
+      createRoute({
+        method,
+        path: "/v1/connectors/{id}/oauth/callback",
+        tags: ["Connectors"],
+        request: { params: z.object({ id: z.string() }) },
+        responses: {
+          200: { description: "OAuth handled" },
+          302: { description: "Redirect" },
+          400: { description: "Missing / invalid / expired state" },
+          404: { description: "Unknown connector / no oauth handler" },
+        },
+      }),
+      async (c) => {
+        const { id } = c.req.valid("param");
+        const { db, logger, env } = c.get("container");
+        const connector = getConnectorRegistry().get(id);
+        if (!connector?.handlers?.oauthCallback) {
+          warnBareGatewayConnector(logger, id, connector, "oauthCallback");
+          return c.json({ error: "Unknown connector" }, 404);
+        }
+        const url = new URL(c.req.url);
+        const query = Object.fromEntries(url.searchParams.entries());
+
+        // The ENGINE owns CSRF state GENERICALLY: this callback lands
+        // UNAUTHENTICATED, so a forged callback (login-CSRF / grafting an
+        // identity onto an arbitrary contact) is only prevented by a
+        // server-minted, server-verified signed `state`. Verify BEFORE
+        // dispatching — a missing/invalid/expired state never reaches the
+        // connector handler (no code exchange, no contact binding).
+        const stateCheck = verifyConnectorState(
+          query.state ?? "",
+          env.BETTER_AUTH_SECRET,
+        );
+        if (!stateCheck.valid || !stateCheck.intent) {
+          logger.warn("connector oauth callback: invalid state", {
+            connectorId: id,
+            reason: stateCheck.reason,
+          });
+          return c.json({ error: "Invalid state" }, 400);
+        }
+        // Bind the state to THIS connector: `BETTER_AUTH_SECRET` signs every
+        // connector's state, so a state minted for connector A is
+        // signature-valid here too. Reject a state whose `connectorId` does not
+        // match this route's `:id` (cross-connector state replay).
+        if (stateCheck.intent.connectorId !== id) {
+          logger.warn("connector oauth callback: state connector mismatch", {
+            routeConnectorId: id,
+            stateConnectorId: stateCheck.intent.connectorId,
+          });
+          return c.json({ error: "Invalid state" }, 400);
+        }
+
+        // SINGLE-USE: the signed state is otherwise TTL-replayable — a captured
+        // callback URL works until `exp`. Burn the per-mint nonce on first use:
+        // a `SET … NX EX` succeeds exactly once, so a second callback carrying the
+        // same nonce (NX fails → `null`) is rejected as a replay. The TTL matches
+        // the max state window (900s) so the used-marker outlives any valid state.
+        // Redis-less deploys (self-host without redis, tests) fall back to
+        // TTL-only single-validity — we never block a callback on a cache miss.
+        const redis = getRedisIfConnected();
+        if (redis) {
+          const usedKey = `connector:state:used:${stateCheck.intent.nonce}`;
+          const claimed = await redis.set(usedKey, "1", "EX", 900, "NX");
+          if (claimed !== "OK") {
+            logger.warn("connector oauth callback: state replay rejected", {
+              connectorId: id,
+            });
+            return c.json({ error: "Invalid state" }, 400);
+          }
+        }
+
+        let body: unknown;
+        try {
+          body = method === "post" ? await c.req.json() : undefined;
+        } catch {
+          body = undefined;
+        }
+        const result = await connector.handlers.oauthCallback({
+          query,
+          body,
+          state: stateCheck.intent,
+          ctx: { db, logger, env, apiPublicUrl: env.API_PUBLIC_URL },
+        });
+        if (result.kind === "redirect") {
+          return c.redirect(result.location, 302);
+        }
+        if (result.kind === "html") {
+          // Serve a self-contained branded page as text/html (a raw HTML
+          // string through the `json` kind would be JSON-quoted in the browser).
+          return c.html(result.body, result.status === 400 ? 400 : 200);
+        }
+        // `c.json`'s typed status union only accepts the route's declared
+        // literals — branch on the concrete status instead of casting a runtime
+        // number to a literal.
+        if (result.status === 404) {
+          return c.json(result.body as object, 404);
+        }
+        return c.json(result.body as object, 200);
+      },
+    );
+  }
+
+  // --- Interactions: POST /v1/connectors/:id/interactions -------------------
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/v1/connectors/{id}/interactions",
+      tags: ["Connectors"],
+      request: { params: z.object({ id: z.string() }) },
+      responses: {
+        200: { description: "Interaction acknowledged / ingested" },
+        401: { description: "Bad platform signature" },
+        404: { description: "Unknown connector / no interactions handler" },
+      },
+    }),
+    async (c) => {
+      const { id } = c.req.valid("param");
+      const { db, logger, env, registry, hatchet } = c.get("container");
+      const connector = getConnectorRegistry().get(id);
+      if (!connector?.handlers?.interactions) {
+        warnBareGatewayConnector(logger, id, connector, "interactions");
+        return c.json({ error: "Unknown connector" }, 404);
+      }
+      const rawBody = await c.req.text(); // EXACT bytes — ed25519 covers them
+      const headers = headersToRecord(c.req.raw.headers);
+      const result = await connector.handlers.interactions({
+        rawBody,
+        headers,
+        ctx: { db, logger, env, apiPublicUrl: env.API_PUBLIC_URL },
+      });
+      if (result.kind === "unauthorized") {
+        return c.json({ error: "Invalid signature" }, 401);
+      }
+      if (result.kind === "ingest") {
+        await ingestEvent({
+          db,
+          registry,
+          hatchet,
+          logger,
+          event: result.event,
+        });
+        return c.json({ ok: true }, 200);
+      }
+      // `kind: "ack"` — a non-event handshake the connector already answered.
+      return c.json((result.body ?? { ok: true }) as object, 200);
+    },
+  );
+
+  // --- Gateway ingress: POST /v1/connectors/:id/ingress ---------------------
+  // The long-lived gateway worker POSTs raw platform events here behind the
+  // shared internal secret; the route runs the connector's transform so ALL
+  // transform logic stays in the connector and the worker is dumb.
+  app.openapi(
+    createRoute({
+      method: "post",
+      path: "/v1/connectors/{id}/ingress",
+      tags: ["Connectors"],
+      request: { params: z.object({ id: z.string() }) },
+      responses: {
+        200: { description: "Ingested / skipped" },
+        401: { description: "Bad internal secret" },
+        404: { description: "Unknown gateway connector" },
+      },
+    }),
+    async (c) => {
+      const { id } = c.req.valid("param");
+      const connector = getConnectorRegistry().get(id);
+      if (!connector || (connector.meta.transport ?? "webhook") !== "gateway") {
+        return c.json({ error: "Unknown gateway connector" }, 404);
+      }
+      const { db, logger, env, registry, hatchet } = c.get("container");
+      const expected = env.CONNECTOR_INGRESS_SECRET;
+      const provided = c.req.header("x-hogsend-ingress-secret");
+      // Fail CLOSED: an unconfigured ingress secret cannot be relayed into.
+      // `safeEqual` length-guards before the constant-time compare, so a length
+      // mismatch returns false rather than throwing.
+      if (!expected || !provided || !safeEqual(provided, expected)) {
+        return c.json({ error: "Unauthorized" }, 401);
+      }
+      const payload = await c.req.json();
+      const event = await connector.transform(payload, {
+        db,
+        logger,
+        transport: "gateway",
+      });
+      if (!event) return c.json({ ok: true, skipped: true }, 200);
+      const result = await ingestEvent({
+        db,
+        registry,
+        hatchet,
+        logger,
+        event,
+      });
+      // INTENTIONALLY `result.exits.length` (a number) — a deliberate
+      // divergence from the `/v1/webhooks/:sourceId` route, which returns the
+      // ExitResult[] ARRAY for back-compat. Do NOT unify the two.
+      return c.json(
+        { ok: true, event: event.event, exits: result.exits.length },
+        200,
+      );
+    },
+  );
+}

package/src/routes/contacts/index.ts

@@ -39,6 +39,10 @@ const upsertRoute = createRoute({
           schema: z.object({
             email: z.string().email().optional(),
             userId: z.string().min(1).optional(),
+            // §4: caller's analytics anon id — the resolver's 2nd-precedence
+            // key. An EXTRA, never a third identity arm: `requireIdentity`
+            // still requires email or userId below.
+            anonymousId: z.string().min(1).max(200).optional(),
             properties: z.record(z.string(), z.unknown()).optional(),
             lists: z.record(z.string(), z.boolean()).optional(),
           }),
@@ -142,6 +146,9 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
       db,
       userId: body.userId,
       email: body.email,
+      // §4: 2nd-precedence resolver key (zero-merge stitch). Identity is still
+      // enforced via `requireIdentity` (email/userId) above.
+      anonymousId: body.anonymousId,
       contactProperties: body.properties,
     });
 

package/src/routes/events/index.ts

@@ -9,6 +9,14 @@ const eventRequestSchema = z.object({
   name: z.string().min(1),
   email: z.string().email().optional(),
   userId: z.string().min(1).optional(),
+  // §4: the caller's analytics anon id (e.g. posthog-js `get_distinct_id()`).
+  // 2nd in the resolver's key precedence (`external → email → anonymous →
+  // discord`), so when no `external_id` is attached the contact's canonical key
+  // BECOMES this value — the browser's own anon events and the server's captures
+  // then land on ONE analytics person with zero merge calls. An EXTRA, never a
+  // third identity arm: `requireIdentity` still requires email or userId
+  // (anon-only public ingest is an abuse vector).
+  anonymousId: z.string().min(1).max(200).optional(),
   eventProperties: z.record(z.string(), z.unknown()).optional(),
   contactProperties: z.record(z.string(), z.unknown()).optional(),
   lists: z.record(z.string(), z.boolean()).optional(),
@@ -68,7 +76,7 @@ const eventRoute = createRoute({
 export const eventsRouter = new OpenAPIHono<AppEnv>().openapi(
   eventRoute,
   async (c) => {
-    const { db, registry, hatchet, logger } = c.get("container");
+    const { db, registry, hatchet, logger, analytics } = c.get("container");
     const body = c.req.valid("json");
 
     const guard = requireIdentity(c, body);
@@ -83,10 +91,17 @@ export const eventsRouter = new OpenAPIHono<AppEnv>().openapi(
       registry,
       hatchet,
       logger,
+      // §5.3: thread the active analytics provider so a collide-MERGE / key-flip
+      // fires the provider-neutral `mergeIdentities` stitch. Absent ⇒ no-op.
+      analytics,
       event: {
         event: body.name,
         userId: body.userId,
         userEmail: body.email,
+        // §4: 2nd-precedence resolver key — lets the contact's canonical key
+        // equal the browser anon id (zero-merge stitch). Identity is still
+        // enforced via `requireIdentity` (email/userId) above.
+        anonymousId: body.anonymousId,
         eventProperties: body.eventProperties ?? {},
         contactProperties: body.contactProperties,
         idempotencyKey,

package/src/routes/index.ts

@@ -1,10 +1,11 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { AppEnv } from "../app.js";
+import type { HogsendClient } from "../container.js";
 import { requireApiKey, requireScope } from "../middleware/api-key.js";
 import { createRateLimit } from "../middleware/rate-limit.js";
-import type { DefinedWebhookSource } from "../webhook-sources/define-webhook-source.js";
 import { adminRouter } from "./admin/index.js";
 import { campaignsRouter } from "./campaigns/index.js";
+import { registerConnectorRoutes } from "./connectors/index.js";
 import { contactsRouter } from "./contacts/index.js";
 import { emailRouter } from "./email/index.js";
 import { emailsRouter } from "./emails/index.js";
@@ -15,7 +16,7 @@ import { trackingRouter } from "./tracking/index.js";
 import { registerWebhookRoutes } from "./webhooks/index.js";
 
 export interface RegisterRoutesOptions {
-  webhookSources: DefinedWebhookSource[];
+  container: HogsendClient;
 }
 
 // Conservative per-key email budget. `/v1/emails` MUST use a distinct prefix so
@@ -76,7 +77,19 @@ export function registerRoutes(
 
   app.route("/v1", v1);
 
+  // Generic connector dispatch (oauth/interactions/ingress) — the static
+  // `connectors/` prefix is registered BEFORE the `:sourceId` webhook catch-all
+  // so it wins path matching. These routes self-authenticate (oauth state +
+  // code, ed25519 signatures, the shared ingress secret) and are intentionally
+  // OUTSIDE the api-key data plane — see registerConnectorRoutes.
+  registerConnectorRoutes(app);
+
   // Webhooks (built-in Resend + injected content sources) are registered on the
-  // app at absolute paths.
-  registerWebhookRoutes(app, { webhookSources: opts.webhookSources });
+  // app at absolute paths. The webhook route sources its connectors from the
+  // container's unified registry (transport === "webhook"), NOT from a passed
+  // array.
+  registerWebhookRoutes(app, {
+    webhookConnectors:
+      opts.container.connectorRegistry.getByTransport("webhook"),
+  });
 }

package/src/routes/tracking/answer.ts

@@ -150,8 +150,15 @@ export const answerRouter = new OpenAPIHono<AppEnv>()
       );
     }
 
-    const ctx = await resolveEmailSendContext(db, link.emailSendId);
-    if (ctx) {
+    // The answer/comment flow is EMAIL-semantic (it re-ingests a
+    // `<event>.comment` keyed on the send). A non-email semantic link has no
+    // send to attribute the comment to — `emailSendId` is nullable since the
+    // identity-stitching minor, so narrow it here.
+    const emailSendId = link.emailSendId;
+    const ctx = emailSendId
+      ? await resolveEmailSendContext(db, emailSendId)
+      : null;
+    if (ctx && emailSendId) {
       // `<event>.comment` is a consumer-namespace event — journeys can wait
       // on it and destinations receive it like any other. First comment per
       // (send, event) wins; repeats are no-ops.
@@ -161,7 +168,7 @@ export const answerRouter = new OpenAPIHono<AppEnv>()
         registry,
         logger,
         event: `${link.event}.comment`,
-        emailSendId: link.emailSendId,
+        emailSendId,
         properties: {
           comment,
           parentEvent: link.event,
@@ -169,7 +176,7 @@ export const answerRouter = new OpenAPIHono<AppEnv>()
           linkId: link.id,
         },
         resolvedContext: ctx,
-        idempotencyKey: `semc:${link.emailSendId}:${link.event}`,
+        idempotencyKey: `semc:${emailSendId}:${link.event}`,
       }).catch((err) => {
         logger.warn("Failed to ingest answer comment", {
           linkId: link.id,