@hogsend/engine 0.21.0 → 0.22.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/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/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
@@ -52,9 +52,19 @@ async function resolveStoredPosthogSecret(
   return value;
 }
 
+/**
+ * Drop the module-level stored-secret cache so the next inbound PostHog webhook
+ * re-reads from the `kind="derived"` store. Called right after `hogsend connect`
+ * mints + persists a secret, so the freshly-minted value is enforced
+ * immediately instead of waiting out the `STORED_SECRET_RECHECK_MS` window.
+ */
+export function invalidateStoredPosthogSecret(): void {
+  storedPosthogSecret = undefined;
+}
+
 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"`
@@ -112,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
@@ -119,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
@@ -129,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) {
@@ -145,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) {
@@ -173,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) {
@@ -206,6 +219,7 @@ export function registerWebhookSourceRoutes(
     const event = await source.transform(payload, {
       db,
       logger,
+      transport: "webhook",
       rawBody,
       headers,
     });
@@ -220,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) {