@hogsend/engine 0.21.0 → 0.22.0

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 };
+}

package/src/lib/contacts.ts

@@ -100,6 +100,7 @@ export function contactSearchFilter(search: string) {
     ilike(contacts.email, `%${search}%`),
     ilike(contacts.externalId, `%${search}%`),
     ilike(contacts.anonymousId, `%${search}%`),
+    ilike(contacts.discordId, `%${search}%`),
   );
 }
 
@@ -115,7 +116,7 @@ export function normalizeEmail(raw: string): string {
 // Identity resolution
 // ---------------------------------------------------------------------------
 
-type Kind = "external" | "email" | "anonymous";
+type Kind = "external" | "email" | "anonymous" | "discord";
 
 interface ResolveKey {
   kind: Kind;
@@ -137,7 +138,9 @@ async function findByKey(tx: Tx, key: ResolveKey): Promise<ContactRow | null> {
       ? contacts.externalId
       : key.kind === "email"
         ? contacts.email
-        : contacts.anonymousId;
+        : key.kind === "anonymous"
+          ? contacts.anonymousId
+          : contacts.discordId;
 
   const direct = await tx
     .select()
@@ -187,6 +190,18 @@ async function findByKey(tx: Tx, key: ResolveKey): Promise<ContactRow | null> {
   return null;
 }
 
+/**
+ * Top-level property keys whose object value is DEEP-merged (one level) rather
+ * than wholly replaced. The §2.1 shallow `||` contract clobbers a top-level key
+ * outright, so a nested metadata object (e.g. the Discord connector's
+ * `properties.discord`) would lose every field the current event doesn't carry
+ * (a reaction knows `last_seen` but not `username`, so it would erase a
+ * previously-captured `username`). Listing the key here makes ONLY that key
+ * additive — siblings stay strictly shallow, preserving the documented contract
+ * for everything else. NON-KEY metadata only; never an identity-resolution key.
+ */
+const DEEP_MERGE_KEYS = ["discord"] as const;
+
 /**
  * Merge `patch` onto the existing jsonb properties (§2.1 contract): additive
  * `COALESCE(existing,'{}') || patch` where the patch wins on key conflict AND an
@@ -197,9 +212,56 @@ async function findByKey(tx: Tx, key: ResolveKey): Promise<ContactRow | null> {
  * Caveat: `jsonb_strip_nulls` also strips any PRE-EXISTING null-valued keys on
  * the contact, which is the intended "null === unset" model (the condition
  * engine already treats JSON null and absent identically).
+ *
+ * EXCEPTION — keys in {@link DEEP_MERGE_KEYS} that carry an object value are
+ * merged ONE level deep: `existing.discord || patch.discord` instead of the
+ * top-level `||` replacing `discord` wholesale. Postgres has no recursive `||`,
+ * so we build the deep-merged sub-object explicitly and overlay it last. A
+ * non-object value for such a key (or an absent one) falls through to the normal
+ * shallow merge untouched.
  */
 function mergePropertiesSql(patch: Record<string, unknown>) {
-  return sql`jsonb_strip_nulls(COALESCE(${contacts.properties}, '{}'::jsonb) || ${JSON.stringify(patch)}::jsonb)`;
+  let merged = sql`COALESCE(${contacts.properties}, '{}'::jsonb) || ${JSON.stringify(patch)}::jsonb`;
+  for (const key of DEEP_MERGE_KEYS) {
+    const sub = patch[key];
+    if (sub && typeof sub === "object" && !Array.isArray(sub)) {
+      // existing[key] (already an object or absent) || patch[key] — the prior
+      // sub-object's fields survive any field the current patch omits.
+      // `${key}` is cast to ::text: jsonb_build_object is VARIADIC "any" and `->`
+      // is overloaded (text key vs int index), so an untyped bound parameter
+      // can't have its type inferred ("could not determine data type of $n").
+      merged = sql`${merged} || jsonb_build_object(${key}::text, COALESCE(${contacts.properties} -> ${key}::text, '{}'::jsonb) || ${JSON.stringify(sub)}::jsonb)`;
+    }
+  }
+  return sql`jsonb_strip_nulls(${merged})`;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return Boolean(v) && typeof v === "object" && !Array.isArray(v);
+}
+
+/**
+ * Spread-merge one `layer` onto the accumulated `acc` (incoming wins per key),
+ * the in-memory analogue of {@link mergePropertiesSql}'s deep-merge exception
+ * for the collide-MERGE fold (which folds properties via JS spread, not SQL).
+ * For each {@link DEEP_MERGE_KEYS} key that is an object on BOTH `acc` and the
+ * incoming `layer`, the sub-objects are themselves shallow-merged (incoming
+ * wins per sub-key) so the layer can't clobber fields the accumulator already
+ * holds — must read the PRE-spread `acc` value, hence a fresh result object.
+ */
+function foldLayer(
+  acc: Record<string, unknown>,
+  layer: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...acc, ...layer };
+  for (const key of DEEP_MERGE_KEYS) {
+    const a = acc[key];
+    const b = layer[key];
+    if (isPlainObject(a) && isPlainObject(b)) {
+      out[key] = { ...a, ...b };
+    }
+  }
+  return out;
 }
 
 /**
@@ -277,6 +339,7 @@ export async function resolveOrCreateContact(opts: {
   userId?: string;
   email?: string;
   anonymousId?: string;
+  discordId?: string;
   contactProperties?: Record<string, unknown>;
 }): Promise<{
   id: string;
@@ -295,15 +358,18 @@ export async function resolveOrCreateContact(opts: {
   const userId = opts.userId?.trim() || undefined;
   const email = opts.email ? normalizeEmail(opts.email) : undefined;
   const anonymousId = opts.anonymousId?.trim() || undefined;
+  const discordId = opts.discordId?.trim() || undefined;
 
   const keys: ResolveKey[] = [];
   if (userId) keys.push({ kind: "external", value: userId });
   if (email) keys.push({ kind: "email", value: email });
   if (anonymousId) keys.push({ kind: "anonymous", value: anonymousId });
+  if (discordId) keys.push({ kind: "discord", value: discordId });
 
   if (keys.length === 0) {
     throw new Error(
-      "resolveOrCreateContact requires at least one of userId, email, anonymousId",
+      "resolveOrCreateContact requires at least one of userId, email, " +
+        "anonymousId, discordId",
     );
   }
 
@@ -338,6 +404,7 @@ export async function resolveOrCreateContact(opts: {
           externalId: userId ?? null,
           email: email ?? null,
           anonymousId: anonymousId ?? null,
+          discordId: discordId ?? null,
           // §2.1: explicit null clears a key — never persist a null-valued prop.
           properties: stripNulls(patch),
         })
@@ -360,6 +427,7 @@ export async function resolveOrCreateContact(opts: {
         userId,
         email,
         anonymousId,
+        discordId,
         patch,
         hasPatch,
       });
@@ -371,6 +439,7 @@ export async function resolveOrCreateContact(opts: {
       userId,
       email,
       anonymousId,
+      discordId,
       patch,
       hasPatch,
     });
@@ -382,6 +451,7 @@ interface ResolveCtx {
   userId?: string;
   email?: string;
   anonymousId?: string;
+  discordId?: string;
   patch: Record<string, unknown>;
   hasPatch: boolean;
 }
@@ -420,6 +490,14 @@ async function fillInLink(
     set.email = ctx.email;
     promoted.push({ kind: "email", value: ctx.email });
   }
+  // discord_id is an attachable resolvable key but NEVER the canonical key
+  // (external_id ?? anonymous_id ?? id), so it does NOT touch
+  // nextExternalId/nextAnonymousId — gaining it never flips the canonical key,
+  // so no own-history re-point follows.
+  if (ctx.discordId && !row.discordId) {
+    set.discordId = ctx.discordId;
+    promoted.push({ kind: "discord", value: ctx.discordId });
+  }
   if (ctx.anonymousId && !row.anonymousId) {
     set.anonymousId = ctx.anonymousId;
     nextAnonymousId = ctx.anonymousId;
@@ -518,14 +596,23 @@ async function mergeContacts(
   }
 
   // (vii) FOLD properties: survivor wins over losers; then the call's patch wins
-  // last. timezone = survivor ?? loser; firstSeenAt = least.
+  // last. timezone = survivor ?? loser; firstSeenAt = least. DEEP_MERGE_KEYS
+  // (e.g. `discord`) are sub-object-merged at each fold layer (foldLayer) so a
+  // loser/survivor/patch that carries only a subset of the nested object's
+  // fields doesn't clobber the rest — matching mergePropertiesSql's exception.
   let foldedProps: Record<string, unknown> = {};
   for (const loser of losers) {
-    foldedProps = { ...foldedProps, ...((loser.properties ?? {}) as object) };
+    foldedProps = foldLayer(
+      foldedProps,
+      (loser.properties ?? {}) as Record<string, unknown>,
+    );
   }
-  foldedProps = { ...foldedProps, ...((survivor.properties ?? {}) as object) };
+  foldedProps = foldLayer(
+    foldedProps,
+    (survivor.properties ?? {}) as Record<string, unknown>,
+  );
   if (ctx.hasPatch) {
-    foldedProps = { ...foldedProps, ...ctx.patch };
+    foldedProps = foldLayer(foldedProps, ctx.patch);
   }
   // §2.1: an explicit null in the call's patch clears a key — drop null-valued
   // keys from the folded result (matching mergePropertiesSql's strip-nulls).
@@ -562,6 +649,16 @@ async function mergeContacts(
     const next = ctx.anonymousId ?? fromLoser;
     if (next) survivorSet.anonymousId = next;
   }
+  // discord_id lands on the survivor (from the call or a loser), but it is
+  // NEVER the canonical key — so it is intentionally NOT folded into
+  // newSurvivorKey below and a discord-only merge does no history re-point. The
+  // losers are soft-deleted FIRST (below) so the partial-unique discord_id index
+  // is freed before this copy.
+  if (!survivor.discordId) {
+    const fromLoser = losers.find((l) => l.discordId)?.discordId;
+    const next = ctx.discordId ?? fromLoser;
+    if (next) survivorSet.discordId = next;
+  }
 
   // (viii) Soft-delete the losers FIRST — frees their external_id/email/
   // anonymous_id from the partial-unique indexes (WHERE deleted_at IS NULL) —
@@ -953,6 +1050,20 @@ async function recordMergeAliases(
       reason: "merge",
     });
   }
+  // discord_id is a resolvable key, so a stale loser snowflake must still
+  // resolve to the survivor after the soft-delete takes the loser out of
+  // findByKey's direct lookup. Additive — it never conflicts with the
+  // external/anonymous id-fallback alias below (a discord-only loser produces
+  // BOTH this discord alias AND the id→external alias).
+  if (loser.discordId) {
+    aliasRows.push({
+      contactId: survivorId,
+      aliasKind: "discord",
+      aliasValue: loser.discordId,
+      fromContactId: loser.id,
+      reason: "merge",
+    });
+  }
   // When the loser had neither external_id nor anonymous_id, its CANONICAL key
   // (`external_id ?? anonymous_id ?? id`) was its row id — and that key has
   // circulated (Hatchet payloads, outbound `userId`s, `hs_t` tokens). Alias it
@@ -1002,6 +1113,7 @@ export async function upsertContact(opts: {
   externalId?: string;
   email?: string;
   anonymousId?: string;
+  discordId?: string;
   properties?: Record<string, unknown>;
 }): Promise<{
   id: string;
@@ -1015,6 +1127,7 @@ export async function upsertContact(opts: {
     userId: opts.externalId,
     email: opts.email,
     anonymousId: opts.anonymousId,
+    discordId: opts.discordId,
     contactProperties: opts.properties,
   });
 }