@hogsend/engine 0.21.1 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.21.1",
+  "version": "0.23.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -40,14 +40,14 @@
     "svix": "^1.95.1",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.21.1",
-    "@hogsend/db": "^0.21.1",
-    "@hogsend/email": "^0.21.1",
-    "@hogsend/plugin-posthog": "^0.21.1",
-    "@hogsend/plugin-resend": "^0.21.1"
+    "@hogsend/core": "^0.23.0",
+    "@hogsend/db": "^0.23.0",
+    "@hogsend/email": "^0.23.0",
+    "@hogsend/plugin-posthog": "^0.23.0",
+    "@hogsend/plugin-resend": "^0.23.0"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.21.1"
+    "@hogsend/plugin-postmark": "^0.23.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/app.ts

@@ -6,6 +6,7 @@ import { cors } from "hono/cors";
 import { requestId } from "hono/request-id";
 import { secureHeaders } from "hono/secure-headers";
 import type { ErrorHandler, MiddlewareHandler } from "hono/types";
+import { connectorsFromEnv } from "./connectors/presets/index.js";
 import type { HogsendClient } from "./container.js";
 import { API_VERSION } from "./env.js";
 import type { Auth } from "./lib/auth.js";
@@ -15,8 +16,10 @@ import { errorHandler } from "./middleware/error-handler.js";
 import { clientIpKey, createRateLimit } from "./middleware/rate-limit.js";
 import { requestLogger } from "./middleware/request-logger.js";
 import { registerRoutes } from "./routes/index.js";
-import type { DefinedWebhookSource } from "./webhook-sources/define-webhook-source.js";
-import { presetsFromEnv } from "./webhook-sources/presets/index.js";
+import {
+  type DefinedWebhookSource,
+  webhookSourceToConnector,
+} from "./webhook-sources/define-webhook-source.js";
 
 type AuthSession = Awaited<ReturnType<Auth["api"]["getSession"]>>;
 
@@ -42,27 +45,18 @@ export interface CreateAppOptions {
    * Segment) for every preset whose env secret is configured (gated further by
    * `ENABLED_WEBHOOK_PRESETS`). Consumer-supplied `webhookSources` always win on
    * an id collision. Set `false` to opt out entirely. Default `true`.
+   *
+   * @deprecated prefer `createHogsendClient({ enablePresets })` — preset
+   * resolution now lives in the container's connector registry. This flag is
+   * STILL HONORED end-to-end: when `false`, `createApp` strips the env-preset
+   * ids back out of the already-built registry, so the opt-out is NOT a silent
+   * no-op.
    */
   enablePresets?: boolean;
   /** Override the default error handler. */
   onError?: ErrorHandler<AppEnv>;
 }
 
-/**
- * Merge env-enabled presets with the consumer's explicit sources. The
- * consumer-supplied source WINS on an id collision (so a hand-tuned override of
- * a preset replaces the shipped one rather than registering a duplicate route).
- */
-function dedupeById(sources: DefinedWebhookSource[]): DefinedWebhookSource[] {
-  const byId = new Map<string, DefinedWebhookSource>();
-  for (const source of sources) {
-    // Last write wins; callers order presets BEFORE consumer sources so the
-    // consumer override lands last.
-    byId.set(source.meta.id, source);
-  }
-  return [...byId.values()];
-}
-
 export function createApp(
   container: HogsendClient,
   opts: CreateAppOptions = {},
@@ -130,19 +124,32 @@ export function createApp(
     return c.json({ needsSetup });
   });
 
-  // Merge env-enabled presets ahead of the consumer's explicit sources so a
-  // consumer override of a preset id wins (decision #13). `enablePresets`
-  // defaults true; setting only `STRIPE_WEBHOOK_SECRET` auto-mounts Stripe at
-  // `POST /v1/webhooks/stripe` and nothing else.
-  const enablePresets = opts.enablePresets ?? true;
-  const webhookSources = enablePresets
-    ? dedupeById([
-        ...presetsFromEnv(container.env),
-        ...(opts.webhookSources ?? []),
-      ])
-    : (opts.webhookSources ?? []);
-
-  registerRoutes(app, { webhookSources });
+  // The container is the single merge point for inbound connectors (env presets
+  // + `connectors` + the deprecated `webhookSources` passed to the client).
+  // Any `webhookSources` passed HERE (the createApp path) are appended into the
+  // installed registry as transport:"webhook" connectors — last-writer-wins,
+  // idempotent.
+  for (const source of opts.webhookSources ?? []) {
+    container.connectorRegistry.register(webhookSourceToConnector(source));
+  }
+
+  // Back-compat: the deprecated `enablePresets: false` STILL suppresses env
+  // presets end-to-end. The container builds presets unconditionally when the
+  // client wasn't told otherwise, so when this flag is explicitly false we strip
+  // the env-preset ids back out of the registry here — but never one a consumer
+  // `webhookSources` override re-registered above (those are kept).
+  if (opts.enablePresets === false) {
+    const overriddenIds = new Set(
+      (opts.webhookSources ?? []).map((s) => s.meta.id),
+    );
+    for (const preset of connectorsFromEnv(container.env)) {
+      if (!overriddenIds.has(preset.meta.id)) {
+        container.connectorRegistry.unregister(preset.meta.id);
+      }
+    }
+  }
+
+  registerRoutes(app, { container });
 
   // Serve the Studio SPA at /studio/* (static layer, no auth — the SPA gates
   // itself via /v1/auth/status + login; data endpoints stay behind requireAdmin).

package/src/connectors/define-connector.ts

@@ -0,0 +1,205 @@
+import type { Database } from "@hogsend/db";
+import type { z } from "zod";
+import type { env as engineEnv } from "../env.js";
+import type { ConnectorStateIntent } from "../lib/connector-state.js";
+import type { IngestEvent } from "../lib/ingestion.js";
+import type { Logger } from "../lib/logger.js";
+import type {
+  SignatureScheme,
+  VerifySignatureArgs,
+} from "../webhook-sources/verify.js";
+
+/**
+ * The unified INBOUND connector abstraction. A connector is one platform's
+ * inbound face — it turns a raw platform payload into an {@link IngestEvent}
+ * via {@link DefinedConnector.transform}. The transform contract is IDENTICAL
+ * across transports; only the ACTIVATION RUNTIME differs:
+ *
+ *  - `"webhook"` — an HTTP route (`POST /v1/webhooks/:id`) verifies the inbound
+ *    request and calls `transform`. (The long-standing `defineWebhookSource`
+ *    behavior, now one transport under this umbrella.)
+ *  - `"gateway"` — a long-lived worker process (its OWN entrypoint / Railway
+ *    service, NOT a Hatchet task) holds a socket to the platform, and on each
+ *    platform event POSTs into this connector's own ingress
+ *    (`POST /v1/connectors/:id/ingress`, shared internal secret) so ALL
+ *    transform logic stays here and the socket worker stays dumb.
+ *  - `"poll"` — a Hatchet cron pulls the platform on a schedule (using the
+ *    stored credential) and runs `transform` per pulled item.
+ *
+ * The symmetric INBOUND twin of {@link DefinedDestination}.
+ * {@link defineConnector} is an identity / validating function.
+ */
+export type ConnectorTransport = "webhook" | "gateway" | "poll";
+
+// ---------------------------------------------------------------------------
+// Auth is TRANSPORT-SHAPED — two distinct concerns, never one union.
+// ---------------------------------------------------------------------------
+
+/**
+ * INBOUND-REQUEST VERIFICATION — webhook transport only. "Does this HTTP
+ * request prove it came from the platform?" The EXACT pre-existing
+ * `WebhookSourceAuth` union, re-homed here (re-exported by
+ * define-webhook-source for back-compat). `match` = shared-secret equality
+ * (OPEN when unset); `signature` = provider HMAC (FAIL CLOSED when unset).
+ */
+export type InboundVerifyAuth =
+  | {
+      type: "match";
+      header: string;
+      envKey: string;
+    }
+  | {
+      type: "signature";
+      scheme: SignatureScheme;
+      envKey: string;
+      header: string;
+      fallbackMatchHeader?: string;
+      verify?(args: VerifySignatureArgs): boolean | Promise<boolean>;
+    };
+
+/**
+ * STORED OUTBOUND CREDENTIAL — gateway/poll transports only. The connector PULLS
+ * from the platform and must present a credential. Declares WHICH
+ * `provider_credentials` row to read. The engine resolves the row at activation
+ * time and hands the decrypted material to the gateway worker / poll cron —
+ * never the transform. SEPARATE from {@link InboundVerifyAuth} by design.
+ */
+export interface StoredCredentialRef {
+  /** `provider_credentials.providerId` to read (defaults to `meta.id`). */
+  providerId?: string;
+  /** Which credential kind the runtime resolves. Default `"oauth"`. */
+  kind?: "oauth" | "derived";
+}
+
+// ---------------------------------------------------------------------------
+// Context handed to transform()
+// ---------------------------------------------------------------------------
+
+/**
+ * Side context handed to {@link DefinedConnector.transform}. A superset of the
+ * old `WebhookSourceCtx`: `rawBody`/`headers` are populated by the webhook
+ * route; `transport` lets a shared transform branch when a platform feeds more
+ * than one transport.
+ */
+export interface ConnectorCtx {
+  db: Database;
+  logger: Logger;
+  /** Which activation runtime invoked the transform. */
+  transport: ConnectorTransport;
+  /** Webhook transport only — EXACT raw request bytes. */
+  rawBody?: string;
+  /** Webhook transport only — inbound request headers (lowercased keys). */
+  headers?: Record<string, string>;
+}
+
+export interface ConnectorMeta {
+  id: string;
+  name: string;
+  description?: string;
+  /** The activation runtime. Defaults to `"webhook"` (back-compat). */
+  transport?: ConnectorTransport;
+}
+
+// ---------------------------------------------------------------------------
+// OAuth / interactions handlers — the GENERIC engine route surface.
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal handler context for the generic connector routes. `env` is the EXACT
+ * validated engine env object (number/boolean fields included) — NOT a string
+ * Record — so the route can pass `c.get("container").env` straight through.
+ */
+export interface ConnectorRouteCtx {
+  db: Database;
+  logger: Logger;
+  env: typeof engineEnv;
+  /** Public base URL of this instance (redirect-URI construction). */
+  apiPublicUrl: string;
+}
+
+export type ConnectorOAuthResult =
+  | { kind: "redirect"; location: string }
+  | { kind: "json"; status: number; body: unknown }
+  // A self-contained HTML page (e.g. the branded OAuth-fallback success page)
+  // the route serves with text/html — NOT JSON-encoded.
+  | { kind: "html"; status: number; body: string };
+
+export type ConnectorInteractionResult =
+  // A non-event handshake the connector already answered (route 200s `body`).
+  | { kind: "ack"; status?: number; body?: unknown }
+  // An event to push through the ingest pipeline (route ingests + 200s).
+  | { kind: "ingest"; event: IngestEvent }
+  // Signature failed — route 401s.
+  | { kind: "unauthorized" };
+
+/**
+ * OPTIONAL per-connector OAuth + interactions hooks dispatched by the GENERIC
+ * engine routes (mirrors how `/v1/webhooks/:sourceId` dispatches `transform`),
+ * so platform #3 needs no new routes.
+ *
+ *  - `oauthCallback` — handle `GET|POST /v1/connectors/:id/oauth/callback`:
+ *    exchange the code, persist into `provider_credentials`, return a
+ *    redirect/JSON result. The connector imports the engine's credential-save
+ *    helpers directly (they are public exports). The ENGINE owns CSRF `state`
+ *    verification GENERICALLY (the route verifies the signed state before
+ *    dispatch and hands the decoded {@link ConnectorStateIntent} in as `state`);
+ *    the handler must NOT re-verify the raw query `state`.
+ *  - `interactions` — handle `POST /v1/connectors/:id/interactions`: the
+ *    connector verifies the platform signature ITSELF (Discord ed25519), may
+ *    200 a handshake (Discord PING), and may return an {@link IngestEvent}.
+ */
+export interface ConnectorHandlers {
+  oauthCallback?(args: {
+    query: Record<string, string>;
+    body: unknown;
+    /** Engine-verified, decoded OAuth `state` (CSRF + member-link binding). */
+    state: ConnectorStateIntent;
+    ctx: ConnectorRouteCtx;
+  }): Promise<ConnectorOAuthResult>;
+  interactions?(args: {
+    rawBody: string;
+    headers: Record<string, string>;
+    ctx: ConnectorRouteCtx;
+  }): Promise<ConnectorInteractionResult>;
+}
+
+// ---------------------------------------------------------------------------
+// The umbrella interface
+// ---------------------------------------------------------------------------
+
+export interface DefinedConnector<T = unknown> {
+  meta: ConnectorMeta;
+  /**
+   * Inbound-request verification — REQUIRED for `transport: "webhook"`,
+   * forbidden otherwise.
+   */
+  inboundVerify?: InboundVerifyAuth;
+  /** Stored outbound credential to pull with — used by `gateway`/`poll`. */
+  credential?: StoredCredentialRef;
+  /** Optional Zod schema validating the payload BEFORE transform. */
+  schema?: z.ZodSchema<T>;
+  /** The transport-invariant heart: raw platform payload → IngestEvent | null. */
+  transform(payload: T, ctx: ConnectorCtx): Promise<IngestEvent | null>;
+  /** OPTIONAL OAuth + interactions hooks for the generic dispatch routes. */
+  handlers?: ConnectorHandlers;
+}
+
+export function defineConnector<T>(
+  def: DefinedConnector<T>,
+): DefinedConnector<T> {
+  // Cheap authoring guard: the two auth concerns are transport-shaped, so a
+  // mis-paired definition is a config error worth catching at module load.
+  const transport = def.meta.transport ?? "webhook";
+  if (transport === "webhook" && !def.inboundVerify) {
+    throw new Error(
+      `connector "${def.meta.id}" (transport=webhook) must declare inboundVerify`,
+    );
+  }
+  if (transport !== "webhook" && def.inboundVerify) {
+    throw new Error(
+      `connector "${def.meta.id}" (transport=${transport}) must not declare ` +
+        "inboundVerify — gateway/poll pull with a stored credential",
+    );
+  }
+  return def;
+}

package/src/connectors/presets/index.ts

@@ -0,0 +1,31 @@
+import type { env as engineEnv } from "../../env.js";
+import { webhookSourceToConnector } from "../../webhook-sources/define-webhook-source.js";
+import {
+  PRESET_SOURCES,
+  presetsFromEnv,
+} from "../../webhook-sources/presets/index.js";
+import type { DefinedConnector } from "../define-connector.js";
+
+/**
+ * Every shipped connector preset, keyed by id. Webhook-transport presets are
+ * the existing `defineWebhookSource` presets lifted onto the umbrella; gateway/
+ * poll presets (Discord) are SHIPPED IN THE PLUGIN, not here — the engine
+ * bundles no Discord code.
+ */
+export const PRESET_CONNECTORS: Record<string, DefinedConnector> =
+  Object.fromEntries(
+    Object.values(PRESET_SOURCES).map((s) => [
+      s.meta.id,
+      webhookSourceToConnector(s),
+    ]),
+  );
+
+/**
+ * Resolve which connector presets to register from env. Webhook presets keep
+ * their exact env-secret gating (delegated to `presetsFromEnv`). Gateway/poll
+ * presets are consumer-supplied via `opts.connectors` (the Discord plugin), so
+ * this preset resolver covers only the engine-shipped webhook presets.
+ */
+export function connectorsFromEnv(env: typeof engineEnv): DefinedConnector[] {
+  return presetsFromEnv(env).map(webhookSourceToConnector);
+}

package/src/connectors/registry-singleton.ts

@@ -0,0 +1,79 @@
+import type {
+  ConnectorTransport,
+  DefinedConnector,
+} from "./define-connector.js";
+import { PRESET_CONNECTORS } from "./presets/index.js";
+
+/**
+ * The process-wide connector registry, set once by `createHogsendClient` at
+ * startup. Mirrors {@link DestinationRegistry}: keyed by `meta.id`,
+ * last-writer-wins on collision, with a lazy preset-only fallback so a
+ * self-booting context (a bare poll cron, a test harness) still resolves the
+ * shipped presets even before any container ran.
+ *
+ * Read by: the webhook route (`getByTransport("webhook")`), the generic
+ * `/v1/connectors/:id/*` routes (`get(id)` → `handlers`), the poll-cron
+ * registrar, and the gateway launcher.
+ */
+export class ConnectorRegistry {
+  private readonly byId = new Map<string, DefinedConnector>();
+
+  constructor(connectors: DefinedConnector[] = []) {
+    for (const connector of connectors) {
+      this.byId.set(connector.meta.id, connector);
+    }
+  }
+
+  /** Register / overwrite a connector (last-writer-wins). */
+  register(connector: DefinedConnector): void {
+    this.byId.set(connector.meta.id, connector);
+  }
+
+  /**
+   * Remove a connector by id (no-op when absent). Used by the deprecated
+   * `createApp({ enablePresets: false })` strip path to suppress env presets the
+   * container already installed.
+   */
+  unregister(id: string): boolean {
+    return this.byId.delete(id);
+  }
+
+  get(id: string): DefinedConnector | undefined {
+    return this.byId.get(id);
+  }
+
+  getAll(): DefinedConnector[] {
+    return [...this.byId.values()];
+  }
+
+  /** Every connector whose (defaulted) transport matches. */
+  getByTransport(transport: ConnectorTransport): DefinedConnector[] {
+    return this.getAll().filter(
+      (c) => (c.meta.transport ?? "webhook") === transport,
+    );
+  }
+
+  count(): number {
+    return this.byId.size;
+  }
+}
+
+let fallback: ConnectorRegistry | undefined;
+let installed: ConnectorRegistry | undefined;
+
+export function setConnectorRegistry(registry: ConnectorRegistry): void {
+  installed = registry;
+}
+
+export function getConnectorRegistry(): ConnectorRegistry {
+  if (installed) return installed;
+  if (!fallback) {
+    fallback = new ConnectorRegistry(Object.values(PRESET_CONNECTORS));
+  }
+  return fallback;
+}
+
+/** Reset the installed registry — only for test cleanup. */
+export function resetConnectorRegistry(): void {
+  installed = undefined;
+}

package/src/container.ts

@@ -20,6 +20,12 @@ import {
   buildBucketRegistry,
   collectBucketReactionJourneys,
 } from "./buckets/registry.js";
+import type { DefinedConnector } from "./connectors/define-connector.js";
+import { connectorsFromEnv } from "./connectors/presets/index.js";
+import {
+  ConnectorRegistry,
+  setConnectorRegistry,
+} from "./connectors/registry-singleton.js";
 import type { DefinedDestination } from "./destinations/define-destination.js";
 import { destinationsFromEnv } from "./destinations/presets/index.js";
 import {
@@ -50,6 +56,10 @@ import type {
   FrequencyCapConfig,
 } from "./lib/email-service-types.js";
 import { hatchet } from "./lib/hatchet.js";
+import {
+  createIdentityService,
+  type IdentityService,
+} from "./lib/identity-service.js";
 import { createLogger, type Logger } from "./lib/logger.js";
 import { createTrackedMailer } from "./lib/mailer.js";
 import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
@@ -58,6 +68,10 @@ import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
 import { prepareTrackedHtml } from "./lib/tracking.js";
 import type { DefinedList } from "./lists/define-list.js";
 import { buildListRegistry, type ListRegistry } from "./lists/registry.js";
+import {
+  type DefinedWebhookSource,
+  webhookSourceToConnector,
+} from "./webhook-sources/define-webhook-source.js";
 
 export interface HogsendDefaults {
   /** Global fallback IANA timezone for scheduling. Defaults to "UTC". */
@@ -114,6 +128,15 @@ export interface HogsendClient {
    * treats that as a silent no-op.
    */
   analytics?: AnalyticsProvider;
+  /**
+   * Identity-attach helper that resolves/merges a contact AND propagates the
+   * analytics merge (§5.3) in one call, for identity-attach OUTSIDE the
+   * `/v1/events` ingest path. Discord `/link` (§7) wires its `resolveContact`
+   * callback to `client.identity.linkContact` so a successful contact-merge
+   * folds the discord-keyed person into the canonical one through the SAME
+   * engine emission ingest uses — never bespoke per-consumer plumbing.
+   */
+  identity: IdentityService;
   registry: JourneyRegistry;
   /**
    * The bucket registry (id map + event/property inverted indexes for candidate
@@ -130,6 +153,14 @@ export interface HogsendClient {
    * elsewhere via `getListRegistry()`). Empty when no lists are wired.
    */
   listRegistry: ListRegistry;
+  /**
+   * The unified inbound CONNECTOR registry, keyed by `meta.id`. Holds every
+   * transport: webhook (the `:sourceId` dispatch + legacy webhookSources),
+   * gateway, and poll. Installed as the process singleton in BOTH the API and
+   * worker. The webhook route reads `getByTransport("webhook")`; the generic
+   * `/v1/connectors/:id/*` routes read `get(id).handlers`.
+   */
+  connectorRegistry: ConnectorRegistry;
   hatchet: HatchetClient;
   /**
    * The client repo's migration journal (`migrations/meta/_journal.json`),
@@ -242,6 +273,29 @@ export interface HogsendClientOptions {
    * worker, so it is wired in both. Defaults to none (presets only).
    */
   destinations?: DefinedDestination[];
+  /**
+   * Code-defined inbound CONNECTORS (the unified umbrella). Each is a
+   * `defineConnector()` of any transport. MERGED with `connectorsFromEnv` env
+   * presets (consumer LAST ⇒ wins on id collision, mirroring destinations). The
+   * legacy `webhookSources` array is folded in here as `transport:"webhook"`
+   * connectors. Defaults to none.
+   */
+  connectors?: DefinedConnector[];
+  /**
+   * @deprecated pass `connectors` instead. Back-compat array of
+   * `defineWebhookSource()` sources; converted to webhook-transport connectors.
+   * Still also accepted by `createApp({ webhookSources })`.
+   */
+  webhookSources?: DefinedWebhookSource[];
+  /**
+   * Auto-register the shipped webhook-source PRESETS (Clerk, Supabase, Stripe,
+   * Segment) for every preset whose env secret is configured (gated further by
+   * `ENABLED_WEBHOOK_PRESETS`). Set `false` to suppress env presets entirely.
+   * Default `true`. (Mirrors — and is also honored from — the deprecated
+   * `createApp({ enablePresets })` flag, which strips preset ids back out of the
+   * registry when set there.)
+   */
+  enablePresets?: boolean;
   /**
    * Comma-separated ids (or `*`) controlling which journeys load. Defaults to
    * `env.ENABLED_JOURNEYS`.
@@ -573,6 +627,13 @@ export function createHogsendClient(
   // undefined (no provider configured) — the reads stay no-ops.
   setAnalytics(analytics);
 
+  // Identity-attach helper (§7): bound to THIS container's db + resolved
+  // analytics provider so a contact-merge outside the `/v1/events` ingest path
+  // (Discord `/link`) propagates the analytics merge through the same engine
+  // emission ingest uses. Closes over `analytics` (may be undefined → the merge
+  // emission no-ops; the resolve still happens).
+  const identity = createIdentityService({ db, analytics, logger });
+
   // Build + install the outbound DESTINATION registry (Phase 3) the
   // self-booting delivery task resolves by `webhook_endpoints.kind`. Order is
   // load-bearing: the env-enabled presets come FIRST and the consumer's
@@ -587,6 +648,37 @@ export function createHogsendClient(
   const destinationRegistry = new DestinationRegistry(destinations);
   setDestinationRegistry(destinationRegistry);
 
+  // Build + install the unified inbound CONNECTOR registry — the structural
+  // twin of the destination registry above. Order is load-bearing (consumer
+  // last/wins, mirroring destinations): env presets FIRST (gated by
+  // `enablePresets`), then legacy `webhookSources` lifted onto the umbrella,
+  // then the first-class `connectors` LAST. Runs in BOTH the API and worker.
+  // The webhook route reads `getByTransport("webhook")`; the generic
+  // `/v1/connectors/:id/*` routes read `get(id).handlers`. The `email`
+  // reserved-id guard is the authoritative one (the route reads the registry).
+  const enablePresets = opts.enablePresets ?? true;
+  const connectorList = [
+    ...(enablePresets ? connectorsFromEnv(env) : []),
+    ...(opts.webhookSources ?? []).map(webhookSourceToConnector),
+    ...(opts.connectors ?? []),
+  ];
+  for (const connector of connectorList) {
+    if (
+      (connector.meta.transport ?? "webhook") === "webhook" &&
+      connector.meta.id === "email"
+    ) {
+      throw new Error(
+        'Connector id "email" is reserved for the email-provider route ' +
+          "(POST /v1/webhooks/email/:providerId). Rename the connector.",
+      );
+    }
+  }
+  const connectorRegistry = new ConnectorRegistry(connectorList);
+  setConnectorRegistry(connectorRegistry);
+  logger.debug(
+    `Connector registry loaded: ${connectorRegistry.count()} connectors`,
+  );
+
   // Optional: auto-seed a PostHog DESTINATION on the outbound spine so the email
   // lifecycle fans out to PostHog durably. Default OFF (ENABLE_POSTHOG_DESTINATION)
   // to avoid double-emit alongside the fire-and-forget capture path. Idempotent +
@@ -628,9 +720,11 @@ export function createHogsendClient(
     templates,
     analyticsProviders,
     analytics,
+    identity,
     registry,
     bucketRegistry,
     listRegistry,
+    connectorRegistry,
     hatchet: opts.overrides?.hatchet ?? hatchet,
     clientJournal: opts.clientJournal ?? { entries: [] },
     defaults,

package/src/env.ts

@@ -202,6 +202,11 @@ export const env = createEnv({
     // Preset enablement override: csv of preset ids, `"*"` (all with a secret),
     // or `"none"`. Absent → auto-enable any preset whose secret is set.
     ENABLED_WEBHOOK_PRESETS: z.string().optional(),
+    // Shared internal secret authenticating the gateway-worker → connector
+    // ingress hop (`POST /v1/connectors/:id/ingress`). Fail-CLOSED when unset
+    // (the route 401s), so a gateway worker cannot relay without it. MUST be
+    // high-entropy — generate with `openssl rand -base64 32`.
+    CONNECTOR_INGRESS_SECRET: z.string().min(32).optional(),
     // --- Outbound destination presets (Phase 3) ---
     // Which `defineDestination()` PRESETS are registered into the process
     // destination registry the delivery task resolves by `endpoint.kind`. csv of