@hogsend/engine 0.21.1 → 0.23.0

package/src/index.ts

@@ -91,6 +91,30 @@ export {
   resetBucketRegistry,
   setBucketRegistry,
 } from "./buckets/registry-singleton.js";
+// --- Inbound connectors: unified authoring layer ---
+export {
+  type ConnectorCtx,
+  type ConnectorHandlers,
+  type ConnectorInteractionResult,
+  type ConnectorMeta,
+  type ConnectorOAuthResult,
+  type ConnectorRouteCtx,
+  type ConnectorTransport,
+  type DefinedConnector,
+  defineConnector,
+  type InboundVerifyAuth,
+  type StoredCredentialRef,
+} from "./connectors/define-connector.js";
+export {
+  connectorsFromEnv,
+  PRESET_CONNECTORS,
+} from "./connectors/presets/index.js";
+export {
+  ConnectorRegistry,
+  getConnectorRegistry,
+  resetConnectorRegistry,
+  setConnectorRegistry,
+} from "./connectors/registry-singleton.js";
 export {
   createHogsendClient,
   type HogsendClient,
@@ -141,6 +165,11 @@ export {
   setJourneyRegistry,
 } from "./journeys/registry-singleton.js";
 // --- Analytics provider registry (the analytics sibling) ---
+export {
+  type IdentityMergeReason,
+  logResidualTwins,
+  mergeAnalyticsIdentities,
+} from "./lib/analytics-identity.js";
 export { AnalyticsProviderRegistry } from "./lib/analytics-provider-registry.js";
 export { analyticsProvidersFromEnv } from "./lib/analytics-providers-from-env.js";
 // --- Auth ---
@@ -172,6 +201,28 @@ export {
   type BucketTransitionSource,
   emitBucketTransition,
 } from "./lib/bucket-emit.js";
+// --- Single-use link codes (native connector /link → /verify identify loop) ---
+export {
+  type CreateLinkCodeResult,
+  createLinkCode,
+  generateLinkCode,
+  hashLinkCode,
+  LINK_CODE_MAX_PER_EMAIL,
+  LINK_CODE_MAX_PER_USER,
+  LINK_CODE_THROTTLE_WINDOW_SECONDS,
+  LINK_CODE_TTL_SECONDS,
+  type LinkCodeThrottleScope,
+  type RedeemLinkCodeResult,
+  redeemLinkCode,
+} from "./lib/connector-link-codes.js";
+// --- Generic signed connector state (CSRF + member-link binding) ---
+export {
+  type ConnectorStateIntent,
+  signConnectorState,
+  verifyConnectorState,
+} from "./lib/connector-state.js";
+// --- Contacts identity (resolve/create — used by connector member-link) ---
+export { resolveOrCreateContact } from "./lib/contacts.js";
 export {
   AdminAlreadyExistsError,
   type CreatedAdmin,
@@ -179,6 +230,12 @@ export {
 } from "./lib/create-admin.js";
 // --- Infrastructure singletons ---
 export { getDb } from "./lib/db.js";
+// --- Discord gateway-worker liveness heartbeat (Studio status) ---
+export {
+  type DiscordGatewayHeartbeat,
+  getDiscordGatewayHeartbeat,
+  startDiscordGatewayHeartbeat,
+} from "./lib/discord-gateway-heartbeat.js";
 // --- Sending-domain status service (cached; container-held) ---
 export {
   createDomainStatusService,
@@ -188,6 +245,7 @@ export {
 } from "./lib/domain-status.js";
 // --- Email ---
 export {
+  getEmailService,
   type SendEmailOptions,
   type SendEmailResult,
   sendEmail,
@@ -212,9 +270,16 @@ export { checkEmailPreferences } from "./lib/enrollment-guards.js";
 export { isFrequencyCapped } from "./lib/frequency-cap.js";
 export { addrSpecOf, hostOfFromAddress } from "./lib/from-address.js";
 export { hatchet } from "./lib/hatchet.js";
+// --- Identity service (resolve/merge + analytics merge propagation, §7) ---
+export {
+  createIdentityService,
+  type IdentityService,
+  type LinkContactArgs,
+} from "./lib/identity-service.js";
 export {
   generateIdentityToken,
   type IdentityTokenPayload,
+  type IdentityTokenScope,
   InvalidIdentityTokenError,
   validateIdentityToken,
 } from "./lib/identity-token.js";
@@ -254,6 +319,7 @@ export {
   type CredentialKind,
   type DecryptedProviderCredential,
   type DerivedCredentialPayload,
+  deleteAllProviderCredentials,
   deleteProviderCredential,
   getDerivedCredential,
   getProviderCredential,
@@ -267,6 +333,7 @@ export {
 export {
   type AuthSecondaryStorage,
   createRedisSecondaryStorage,
+  getRedis,
   getRedisIfConnected,
 } from "./lib/redis.js";
 // --- Self-service password reset (engine-owned, self-contained email) ---
@@ -295,6 +362,7 @@ export {
 } from "./lib/tracked.js";
 // --- Tracking ---
 export {
+  createTrackedLink,
   injectOpenPixel,
   prepareTrackedHtml,
   rewriteLinks,
@@ -338,6 +406,7 @@ export {
   type WebhookSourceAuth,
   type WebhookSourceCtx,
   type WebhookSourceMeta,
+  webhookSourceToConnector,
 } from "./webhook-sources/define-webhook-source.js";
 // --- Integration presets (Section 2.3/2.4) ---
 export {

package/src/lib/analytics-identity.ts

@@ -0,0 +1,112 @@
+import type { AnalyticsProvider } from "@hogsend/core";
+import type { Logger } from "./logger.js";
+
+/**
+ * The reason a merge was emitted — surfaced on the `identity.merge.emitted`
+ * structured log so an operator can see WHICH resolver path stitched (§10.5). A
+ * declining `collide_merge` / `key_flip` volume after anon threading lands
+ * (Stage 1) is the empirical "forks prevented" signal.
+ */
+export type IdentityMergeReason =
+  | "collide_merge"
+  | "key_flip"
+  | "click_identify"
+  | "discord_link";
+
+/**
+ * Fan out the provider-neutral `mergeIdentities` primitive (§5.3) once per
+ * loser key, folding each absorbed (anonymous/uuid) key INTO the surviving
+ * canonical contact key. Fire-and-forget and never throws: analytics is
+ * non-load-bearing, so a provider error must not fail the ingest that triggered
+ * the merge.
+ *
+ * Direction is load-bearing (MF-1): `survivorKey` is the SURVIVING/canonical
+ * (identified) id and each `loserKey` is the ABSORBED (anonymous) one — mapped
+ * straight to `mergeIdentities({ distinctId: survivorKey, alias: loserKey })`.
+ *
+ * No-ops cleanly when:
+ * - no provider is injected (`!analytics`),
+ * - the active provider can't merge (`!capabilities.identityMerge` — a legacy
+ *   adapter or a provider without an `alias` wire),
+ * - or it carries no `mergeIdentities` method.
+ *
+ * MF-2: callers MUST pass only the SAFE-to-absorb loser keys (anonymous/uuid,
+ * never an `external_id` that already identified a PostHog person). Aliasing an
+ * already-identified key is the identified→identified merge PostHog refuses
+ * (R2/R4) — it silently no-ops AND spams "Refused to merge" warnings on the
+ * normal merge path. The filtering happens at the emission point (the resolver
+ * splits its loser keys into safe vs. identified); this helper only fans out
+ * what it is given and skips a self-alias (`loserKey === survivorKey`).
+ */
+export function mergeAnalyticsIdentities(opts: {
+  analytics?: AnalyticsProvider;
+  survivorKey: string;
+  loserKeys: string[];
+  /** Stitching path, for the `identity.merge.emitted` observability log. */
+  reason: IdentityMergeReason;
+  /** The contact id, for correlating the merge log to a contact row. */
+  contactId?: string;
+  logger?: Logger;
+}): void {
+  const { analytics, survivorKey, loserKeys, reason, contactId, logger } = opts;
+
+  if (!analytics?.capabilities.identityMerge) {
+    if (loserKeys.length > 0) {
+      logger?.debug("identity.merge.skipped", {
+        reason: analytics ? "no_capability" : "no_provider",
+      });
+    }
+    return;
+  }
+  if (!analytics.mergeIdentities) return;
+
+  for (const loserKey of loserKeys) {
+    if (!loserKey || loserKey === survivorKey) {
+      logger?.debug("identity.merge.skipped", { reason: "self_alias" });
+      continue;
+    }
+    try {
+      analytics.mergeIdentities({ distinctId: survivorKey, alias: loserKey });
+      logger?.info("identity.merge.emitted", {
+        provider: analytics.meta.id,
+        survivorKey,
+        alias: loserKey,
+        reason,
+        ...(contactId ? { contactId } : {}),
+      });
+    } catch (err) {
+      // Best-effort: analytics is non-load-bearing — never throw.
+      logger?.warn("identity.merge.failed", {
+        provider: analytics.meta.id,
+        reason,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+}
+
+/**
+ * Emit the `identity.merge.residual_twin` observability log (§10.5) for each
+ * loser key MF-2 excluded from the safe fan-out: a loser carrying an
+ * `external_id` is, by the engine's own model, an already-identified PostHog
+ * person, and PostHog refuses to merge two identified persons on the safe path.
+ * These twins are the known steady-state residual (OQ-1) made visible — NOT an
+ * error, just the honest "one email → one person, except across two prior
+ * identified persons" outcome surfaced for monitoring.
+ */
+export function logResidualTwins(opts: {
+  survivorKey: string;
+  identifiedLoserKeys: string[];
+  contactId?: string;
+  logger?: Logger;
+}): void {
+  const { survivorKey, identifiedLoserKeys, contactId, logger } = opts;
+  for (const loserExternalId of identifiedLoserKeys) {
+    if (!loserExternalId || loserExternalId === survivorKey) continue;
+    logger?.info("identity.merge.residual_twin", {
+      survivorKey,
+      loserExternalId,
+      ...(contactId ? { contactId } : {}),
+    });
+  }
+}

package/src/lib/connector-link-codes.ts

@@ -0,0 +1,218 @@
+import { createHash, randomInt } from "node:crypto";
+import { connectorLinkCodes, type Database } from "@hogsend/db";
+import { and, count, eq, gte, isNull, sql } from "drizzle-orm";
+import { safeEqual } from "../webhook-sources/verify.js";
+
+/**
+ * Single-use verification codes for the native in-connector identify loop
+ * (Discord `/link <email>` → emailed code → `/verify <code>`).
+ *
+ * Security posture (all four hold simultaneously — the 6-digit code's small
+ * keyspace is acceptable ONLY because of this stack):
+ *  - SINGLE-USE — redeem is an atomic `UPDATE … SET used_at WHERE used_at IS
+ *    NULL RETURNING`; a second redeem of the same code affects zero rows.
+ *  - TTL'd — `expires_at` is checked on redeem; an aged code is rejected.
+ *  - IDENTITY-BOUND — the code is bound to the invoking platform user at mint
+ *    and re-checked at redeem with a CONSTANT-TIME compare; a code minted for
+ *    one account can never be redeemed by another.
+ *  - HASHED-AT-REST — only `sha256(code)` is stored; the plaintext code lives
+ *    only in the member's inbox, so a DB read never yields a redeemable code.
+ *  - THROTTLED — the anti-email-bomb throttle counts mints in a rolling window.
+ *    The per-USER cap ({@link LINK_CODE_MAX_PER_USER}) is the PRIMARY backstop:
+ *    it caps how many codes ONE Discord account can trigger regardless of
+ *    address. The per-EMAIL cap ({@link LINK_CODE_MAX_PER_EMAIL}) is a
+ *    SECONDARY, BEST-EFFORT speed bump — `+tag`/dot aliasing sidesteps it
+ *    (`a@x.com`, `a+1@x.com`, `a.@x.com` normalize to DISTINCT `targetEmail`
+ *    buckets under `trim().toLowerCase()`, which does NOT canonicalize
+ *    Gmail-style aliases; canonicalizing is out of scope). Either cap, when hit,
+ *    refuses to mint+send.
+ */
+
+/** How long a minted code is valid before `/verify` (15 minutes). */
+export const LINK_CODE_TTL_SECONDS = 900;
+
+/** Rolling window (seconds) the anti-email-bomb throttle counts mints over. */
+export const LINK_CODE_THROTTLE_WINDOW_SECONDS = 900;
+
+/** Max codes one invoking platform user may mint per throttle window. */
+export const LINK_CODE_MAX_PER_USER = 5;
+
+/** Max codes that may be minted FOR one target email per throttle window. */
+export const LINK_CODE_MAX_PER_EMAIL = 3;
+
+/** sha256 of the plaintext code, lowercase hex — the at-rest lookup key. */
+export function hashLinkCode(code: string): string {
+  return createHash("sha256").update(code, "utf8").digest("hex");
+}
+
+/**
+ * A 6-digit, human-typable, zero-padded code drawn from a CSPRNG. Entropy is
+ * intentionally low (≈20 bits) — the security comes from single-use + TTL +
+ * identity-binding + throttling, NOT from the code being hard to guess (a
+ * guesser must hit a code minted FOR THEIR OWN platform id in a 15-min window,
+ * which is self-targeting and pointless). 6 digits is the universal
+ * "verification code" UX, trivial to type on mobile.
+ */
+export function generateLinkCode(): string {
+  return String(randomInt(0, 1_000_000)).padStart(6, "0");
+}
+
+/** Why a `/link` mint was refused. */
+export type LinkCodeThrottleScope = "platformUser" | "email";
+
+export type CreateLinkCodeResult =
+  | { ok: true; code: string }
+  | { ok: false; reason: "throttled"; scope: LinkCodeThrottleScope };
+
+/**
+ * Mint a single-use link code, enforcing the anti-email-bomb throttle FIRST.
+ *
+ * The throttle counts rows already minted for this connector in the rolling
+ * window — per invoking `platformUserId` (≤ {@link LINK_CODE_MAX_PER_USER}) AND
+ * per target `email` (≤ {@link LINK_CODE_MAX_PER_EMAIL}) — and refuses to mint
+ * (so nothing is emailed) when either cap is already met. Counting on MINT and
+ * never freeing on redeem/expiry is the email-bomb control. On success the row
+ * stores ONLY the sha256 hash and returns the plaintext `code` for the caller
+ * to email.
+ *
+ * NOTE: a DB failure throws — callers MUST treat that as a hard failure and
+ * NOT fall through to sending an email (an unthrottled send would defeat the
+ * email-bomb control).
+ */
+export async function createLinkCode(opts: {
+  db: Database;
+  connectorId: string;
+  platformUserId: string;
+  email: string;
+  ttlSeconds?: number;
+  maxPerUser?: number;
+  maxPerEmail?: number;
+  windowSeconds?: number;
+}): Promise<CreateLinkCodeResult> {
+  const {
+    db,
+    connectorId,
+    platformUserId,
+    ttlSeconds = LINK_CODE_TTL_SECONDS,
+    maxPerUser = LINK_CODE_MAX_PER_USER,
+    maxPerEmail = LINK_CODE_MAX_PER_EMAIL,
+    windowSeconds = LINK_CODE_THROTTLE_WINDOW_SECONDS,
+  } = opts;
+  // Normalize the email so the per-email throttle + the stored resolution key
+  // are case-insensitive (mirrors the contacts email normalization).
+  const email = opts.email.trim().toLowerCase();
+
+  const since = new Date(Date.now() - windowSeconds * 1000);
+
+  // Per-invoking-user throttle: caps one account spamming many addresses.
+  const [userRow] = await db
+    .select({ n: count() })
+    .from(connectorLinkCodes)
+    .where(
+      and(
+        eq(connectorLinkCodes.connectorId, connectorId),
+        eq(connectorLinkCodes.platformUserId, platformUserId),
+        gte(connectorLinkCodes.createdAt, since),
+      ),
+    );
+  if ((userRow?.n ?? 0) >= maxPerUser) {
+    return { ok: false, reason: "throttled", scope: "platformUser" };
+  }
+
+  // Per-target-email throttle: caps bombing one victim across many accounts.
+  const [emailRow] = await db
+    .select({ n: count() })
+    .from(connectorLinkCodes)
+    .where(
+      and(
+        eq(connectorLinkCodes.connectorId, connectorId),
+        eq(connectorLinkCodes.targetEmail, email),
+        gte(connectorLinkCodes.createdAt, since),
+      ),
+    );
+  if ((emailRow?.n ?? 0) >= maxPerEmail) {
+    return { ok: false, reason: "throttled", scope: "email" };
+  }
+
+  const code = generateLinkCode();
+  const expiresAt = new Date(Date.now() + ttlSeconds * 1000);
+
+  await db.insert(connectorLinkCodes).values({
+    connectorId,
+    codeHash: hashLinkCode(code),
+    platformUserId,
+    targetEmail: email,
+    expiresAt,
+  });
+
+  return { ok: true, code };
+}
+
+export type RedeemLinkCodeResult =
+  | { ok: true; email: string }
+  | { ok: false; reason: "invalid" | "expired" | "used" | "wrong_user" };
+
+/**
+ * Redeem a typed code for the bound email — single-use, TTL-enforced, and
+ * identity-bound to the invoking platform user.
+ *
+ * Resolution is by `sha256(code)` (the plaintext is never stored). A missing
+ * row → `invalid`. A row whose `platformUserId` does not match the caller
+ * (CONSTANT-TIME compared so a redeem can't probe other accounts' codes) →
+ * `wrong_user`. An expired row → `expired`. Single-use is the atomic
+ * `UPDATE … SET used_at = now() WHERE id = ? AND used_at IS NULL RETURNING`:
+ * the FIRST redeem wins and every later one sees zero affected rows → `used`
+ * (this also closes the read-then-write race two concurrent `/verify`s create).
+ */
+export async function redeemLinkCode(opts: {
+  db: Database;
+  connectorId: string;
+  platformUserId: string;
+  code: string;
+}): Promise<RedeemLinkCodeResult> {
+  const { db, connectorId, platformUserId } = opts;
+  const code = opts.code.trim();
+  if (code.length === 0) return { ok: false, reason: "invalid" };
+
+  const codeHash = hashLinkCode(code);
+
+  const [row] = await db
+    .select()
+    .from(connectorLinkCodes)
+    .where(
+      and(
+        eq(connectorLinkCodes.connectorId, connectorId),
+        eq(connectorLinkCodes.codeHash, codeHash),
+      ),
+    )
+    .limit(1);
+
+  if (!row) return { ok: false, reason: "invalid" };
+
+  // Identity binding — constant-time so a redeem can't time-probe which codes
+  // belong to which account. A mismatch is rejected WITHOUT marking the code
+  // used, so the rightful owner can still redeem it.
+  if (!safeEqual(row.platformUserId, platformUserId)) {
+    return { ok: false, reason: "wrong_user" };
+  }
+
+  if (row.usedAt !== null) return { ok: false, reason: "used" };
+  if (row.expiresAt.getTime() <= Date.now()) {
+    return { ok: false, reason: "expired" };
+  }
+
+  // Atomic single-use claim: only the redeem that flips `used_at` from NULL
+  // wins. A concurrent redeem (or a replay that slipped past the read above)
+  // sees zero rows returned.
+  const claimed = await db
+    .update(connectorLinkCodes)
+    .set({ usedAt: sql`now()`, updatedAt: sql`now()` })
+    .where(
+      and(eq(connectorLinkCodes.id, row.id), isNull(connectorLinkCodes.usedAt)),
+    )
+    .returning({ id: connectorLinkCodes.id });
+
+  if (claimed.length === 0) return { ok: false, reason: "used" };
+
+  return { ok: true, email: row.targetEmail };
+}

package/src/lib/connector-state.ts

@@ -0,0 +1,114 @@
+import { createHmac } from "node:crypto";
+import { safeEqual } from "../webhook-sources/verify.js";
+
+/**
+ * Engine-owned, GENERIC signed connector state — the CSRF/binding token carried
+ * on a connector OAuth `state` query param. The connector OAuth callback lands
+ * UNAUTHENTICATED (it is a public redirect target), so every connect/authorize
+ * URL must carry a server-minted, server-verified `state`:
+ *
+ *  - `purpose: "install"` — CSRF only (a one-click bot/app install). No contact
+ *    is bound; the callback just proves the redirect was initiated by us.
+ *  - `purpose: "member_link"` — binds the EXACT contact/email the per-member
+ *    link was issued for, so the callback attaches the platform identity to THAT
+ *    contact (never to whatever email the platform happens to report — the
+ *    grafting/account-takeover vector).
+ *
+ * The token is `base64url(JSON(payload)).base64url(HMAC-SHA256(payloadB64))`,
+ * signed with the engine's `BETTER_AUTH_SECRET`. The same hardened constant-time
+ * compare the connector ingress uses ({@link safeEqual}) guards verification.
+ *
+ * REPLAY: the token is single-use WHEN a nonce store is available — the OAuth
+ * callback burns the per-mint `nonce` on first use (a `SET … NX` in Redis), so a
+ * captured callback URL cannot be replayed. Without Redis (self-host without it,
+ * tests) it degrades to TTL-bounded validity: the signature + `exp` still gate
+ * it, but the same token works until expiry. The mint TTL is the replay window.
+ */
+export interface ConnectorStateIntent {
+  purpose: "install" | "member_link";
+  connectorId: string;
+  /** Member-link only — the bound contact id (authoritative resolution key). */
+  contactId?: string;
+  /** Member-link only — the bound contact email (authoritative resolution key). */
+  email?: string;
+  /**
+   * High-entropy per-mint value so two states are never byte-identical AND so
+   * the callback can burn it for single-use replay protection (see header).
+   */
+  nonce: string;
+}
+
+interface SignedStatePayload extends ConnectorStateIntent {
+  /** Absolute expiry, seconds since the unix epoch. */
+  exp: number;
+}
+
+function base64url(input: Buffer | string): string {
+  return Buffer.from(input).toString("base64url");
+}
+
+function sign(payloadB64: string, secret: string): string {
+  return createHmac("sha256", secret).update(payloadB64).digest("base64url");
+}
+
+/**
+ * Mint a signed connector-state token from an intent. `Date.now()` is fine here
+ * — this is engine RUNTIME code (route handlers), not a journey workflow script.
+ */
+export function signConnectorState(
+  intent: ConnectorStateIntent,
+  secret: string,
+  ttlSeconds: number,
+): string {
+  const payload: SignedStatePayload = {
+    ...intent,
+    exp: Math.floor(Date.now() / 1000) + ttlSeconds,
+  };
+  const payloadB64 = base64url(JSON.stringify(payload));
+  const sigB64 = sign(payloadB64, secret);
+  return `${payloadB64}.${sigB64}`;
+}
+
+/**
+ * Verify a signed connector-state token. Recomputes the HMAC, constant-time
+ * compares it, then enforces expiry. Returns `{ valid: false, reason }` on ANY
+ * malformed/bad/expired input — NEVER throws.
+ */
+export function verifyConnectorState(
+  token: string,
+  secret: string,
+): { valid: boolean; intent?: ConnectorStateIntent; reason?: string } {
+  if (typeof token !== "string" || token.length === 0) {
+    return { valid: false, reason: "missing_token" };
+  }
+  const dot = token.indexOf(".");
+  if (dot <= 0 || dot === token.length - 1) {
+    return { valid: false, reason: "malformed_token" };
+  }
+  const payloadB64 = token.slice(0, dot);
+  const sigB64 = token.slice(dot + 1);
+
+  const expectedSig = sign(payloadB64, secret);
+  if (!safeEqual(sigB64, expectedSig)) {
+    return { valid: false, reason: "bad_signature" };
+  }
+
+  let payload: SignedStatePayload;
+  try {
+    payload = JSON.parse(
+      Buffer.from(payloadB64, "base64url").toString("utf8"),
+    ) as SignedStatePayload;
+  } catch {
+    return { valid: false, reason: "malformed_payload" };
+  }
+
+  if (typeof payload.exp !== "number") {
+    return { valid: false, reason: "malformed_payload" };
+  }
+  if (payload.exp <= Math.floor(Date.now() / 1000)) {
+    return { valid: false, reason: "expired" };
+  }
+
+  const { exp: _exp, ...intent } = payload;
+  return { valid: true, intent };
+}