@hogsend/engine 0.36.0 → 0.36.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.36.0",
3
+ "version": "0.36.1",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -42,14 +42,14 @@
42
42
  "svix": "^1.95.1",
43
43
  "winston": "^3.19.0",
44
44
  "zod": "^4.4.3",
45
- "@hogsend/core": "^0.36.0",
46
- "@hogsend/db": "^0.36.0",
47
- "@hogsend/email": "^0.36.0",
48
- "@hogsend/plugin-posthog": "^0.36.0",
49
- "@hogsend/plugin-resend": "^0.36.0"
45
+ "@hogsend/core": "^0.36.1",
46
+ "@hogsend/db": "^0.36.1",
47
+ "@hogsend/email": "^0.36.1",
48
+ "@hogsend/plugin-posthog": "^0.36.1",
49
+ "@hogsend/plugin-resend": "^0.36.1"
50
50
  },
51
51
  "optionalDependencies": {
52
- "@hogsend/plugin-postmark": "^0.36.0"
52
+ "@hogsend/plugin-postmark": "^0.36.1"
53
53
  },
54
54
  "devDependencies": {
55
55
  "@types/node": "^22.15.3",
@@ -34,6 +34,23 @@ export class PublishableAnonymousMergeError extends Error {
34
34
  }
35
35
  }
36
36
 
37
+ /**
38
+ * Thrown by {@link resolveOrCreateContact}'s engine-internal `contactId` pin when
39
+ * the pinned subject row no longer exists and no merge-alias chain leads to a live
40
+ * survivor (the subject was hard-deleted). The internal re-emit is then dropped
41
+ * (ingestEvent returns `{ stored: false }`, logs `identity.provenance.lost`) rather
42
+ * than value-resolving — a value fall-back could mint the very phantom twin the
43
+ * pin exists to prevent. Reachable ONLY for a hard-deleted/unfollowable subject.
44
+ */
45
+ export class ContactProvenanceLostError extends Error {
46
+ constructor(public readonly contactId: string) {
47
+ super(
48
+ `contact provenance lost: no live contact or survivor for ${contactId}`,
49
+ );
50
+ this.name = "ContactProvenanceLostError";
51
+ }
52
+ }
53
+
37
54
  /**
38
55
  * The transaction handle drizzle hands to a `db.transaction(cb)` callback. It
39
56
  * exposes the same `.select/.insert/.update/.execute/.query` surface as the
@@ -211,6 +228,93 @@ async function findByKey(tx: Tx, key: ResolveKey): Promise<ContactRow | null> {
211
228
  return null;
212
229
  }
213
230
 
231
+ /**
232
+ * ENGINE-INTERNAL provenance pin (see {@link resolveOrCreateContact}'s
233
+ * `contactId`). Resolve to the EXACT subject row by its unforgeable uuid PK and
234
+ * fold there — never value-probing, never minting. Serializes on the row PK via
235
+ * `FOR UPDATE`, so a concurrent collide-MERGE that soft-deletes this row as a
236
+ * loser blocks on / is observed by this pin (rather than racing the mismatched
237
+ * `external:value` vs `anonymous:value` advisory locks). If the row was merged
238
+ * away (soft-deleted), follow the server-authored merge-alias chain to the live
239
+ * SURVIVOR by row id — independent of alias kind/value, closing the post-merge
240
+ * anon-alias residual. A hard-deleted/unfollowable subject throws
241
+ * {@link ContactProvenanceLostError} (the caller drops the event, never mints).
242
+ */
243
+ async function resolveByContactId(
244
+ tx: Tx,
245
+ contactId: string,
246
+ ctx: { patch: Record<string, unknown>; hasPatch: boolean },
247
+ ): Promise<{
248
+ id: string;
249
+ resolvedKey: string;
250
+ created: boolean;
251
+ linked: boolean;
252
+ merged: boolean;
253
+ }> {
254
+ let row: ContactRow | null =
255
+ (
256
+ await tx
257
+ .select()
258
+ .from(contacts)
259
+ .where(eq(contacts.id, contactId))
260
+ .for("update")
261
+ .limit(1)
262
+ )[0] ?? null;
263
+ if (!row || row.deletedAt) {
264
+ row = await followToSurvivor(tx, contactId);
265
+ }
266
+ if (!row) throw new ContactProvenanceLostError(contactId);
267
+ const set: Record<string, unknown> = {
268
+ lastSeenAt: new Date(),
269
+ updatedAt: new Date(),
270
+ };
271
+ if (ctx.hasPatch) set.properties = mergePropertiesSql(ctx.patch);
272
+ await tx.update(contacts).set(set).where(eq(contacts.id, row.id));
273
+ return {
274
+ id: row.id,
275
+ resolvedKey: contactKey(row),
276
+ created: false,
277
+ linked: false,
278
+ merged: false,
279
+ };
280
+ }
281
+
282
+ /**
283
+ * Follow the server-authored merge-alias chain from a (soft-deleted loser)
284
+ * `contacts.id` to the live SURVIVOR row, re-locking each hop `FOR UPDATE`.
285
+ * Bounded (merge-of-a-merge) to a small cap. Keyed on `from_contact_id` — the
286
+ * unforgeable row id, never a value — so an attacker-plantable key can never
287
+ * steer it. Returns the live survivor or null (hard-deleted / chain broken).
288
+ */
289
+ async function followToSurvivor(
290
+ tx: Tx,
291
+ lostId: string,
292
+ ): Promise<ContactRow | null> {
293
+ let cursor = lostId;
294
+ for (let i = 0; i < 8; i++) {
295
+ const alias = (
296
+ await tx
297
+ .select({ contactId: contactAliases.contactId })
298
+ .from(contactAliases)
299
+ .where(eq(contactAliases.fromContactId, cursor))
300
+ .limit(1)
301
+ )[0];
302
+ if (!alias?.contactId) return null;
303
+ const survivor: ContactRow | undefined = (
304
+ await tx
305
+ .select()
306
+ .from(contacts)
307
+ .where(eq(contacts.id, alias.contactId))
308
+ .for("update")
309
+ .limit(1)
310
+ )[0];
311
+ if (!survivor) return null;
312
+ if (!survivor.deletedAt) return survivor;
313
+ cursor = alias.contactId;
314
+ }
315
+ return null;
316
+ }
317
+
214
318
  /**
215
319
  * Top-level property keys whose object value is DEEP-merged (one level) rather
216
320
  * than wholly replaced. The §2.1 shallow `||` contract clobbers a top-level key
@@ -374,6 +478,21 @@ export async function resolveOrCreateContact(opts: {
374
478
  * secret-key path NEVER sets this, so its behavior is byte-for-byte unchanged.
375
479
  */
376
480
  restrictToAnonymous?: boolean;
481
+ /**
482
+ * ENGINE-INTERNAL provenance — the subject contact's UNFORGEABLE row id
483
+ * (`contacts.id`, a server-minted uuid). Set ONLY by engine-internal re-emit
484
+ * sites that already resolved the subject (ingestEvent's downstream re-ingests,
485
+ * the feed mark/clear re-ingests, journey/bucket re-emits). When present (and
486
+ * uuid-shaped, and not a clamped publishable write), the resolver PINS to that
487
+ * exact row — never value-resolving, never minting — so an internal event whose
488
+ * `userId` is a contact's own canonical key (its anonymous_id/id round-tripping)
489
+ * folds back into that contact instead of minting a phantom `external_id` twin.
490
+ * NEVER settable from a request body: the public `/v1/events`/`/v1/contacts`/
491
+ * `/v1/feed` Zod schemas omit it and their handlers build the resolve call
492
+ * literally, so an attacker cannot forge provenance. Mutually exclusive with
493
+ * `restrictToAnonymous`.
494
+ */
495
+ contactId?: string;
377
496
  }): Promise<{
378
497
  id: string;
379
498
  /**
@@ -409,6 +528,7 @@ export async function resolveOrCreateContact(opts: {
409
528
  const email = opts.email ? normalizeEmail(opts.email) : undefined;
410
529
  const anonymousId = opts.anonymousId?.trim() || undefined;
411
530
  const discordId = opts.discordId?.trim() || undefined;
531
+ const contactId = opts.contactId?.trim() || undefined;
412
532
  // §Phase 1 GAP-1: the publishable clamp only bites an ANON-ONLY write (the
413
533
  // only shape a token-less pk_ key can produce — the gate 403s any
414
534
  // email/userId without a verified userToken before we get here). An identified
@@ -437,6 +557,18 @@ export async function resolveOrCreateContact(opts: {
437
557
  const hasPatch = Object.keys(patch).length > 0;
438
558
 
439
559
  return db.transaction(async (tx) => {
560
+ // (−1) ENGINE-INTERNAL PROVENANCE PIN. A uuid-shaped `contactId` from a
561
+ // trusted internal re-emit pins resolution to that exact row (no value-key
562
+ // probe, no mint), so a contact's own canonical key round-tripping back as a
563
+ // `userId` folds into it instead of minting a phantom `external_id` twin.
564
+ // Gated on `!restrictToAnonymous` (mutually exclusive with the publishable
565
+ // clamp — a clamped pk_ write can never carry provenance) so it is never an
566
+ // attacker-reachable path. Runs BEFORE the value-key advisory locks: the pin
567
+ // serializes on the concrete row PK via `FOR UPDATE`, not on value locks.
568
+ if (contactId && UUID_REGEX.test(contactId) && !restrictToAnonymous) {
569
+ return resolveByContactId(tx, contactId, { patch, hasPatch });
570
+ }
571
+
440
572
  // (0) Advisory locks per key — serialize concurrent resolves on the same
441
573
  // identity so the INSERT race can't mint duplicates. Sorted to keep a stable
442
574
  // acquisition order across callers (deadlock-safe).
@@ -16,7 +16,10 @@ import {
16
16
  getAnalytics,
17
17
  getAnalyticsEventMirror,
18
18
  } from "./analytics-singleton.js";
19
- import { resolveOrCreateContact } from "./contacts.js";
19
+ import {
20
+ ContactProvenanceLostError,
21
+ resolveOrCreateContact,
22
+ } from "./contacts.js";
20
23
  import type { Logger } from "./logger.js";
21
24
 
22
25
  export interface IngestEvent {
@@ -26,6 +29,16 @@ export interface IngestEvent {
26
29
  userEmail?: string;
27
30
  /** D1: future anonymous→identified path. Threaded into the resolver. */
28
31
  anonymousId?: string;
32
+ /**
33
+ * ENGINE-INTERNAL provenance — the subject contact's unforgeable row id
34
+ * (`contacts.id`). Set ONLY by engine-internal re-emit sites that already
35
+ * resolved the subject (this fn's own downstream re-ingests, the feed
36
+ * mark/clear re-ingests). Pins the resolver to that exact row so a contact's
37
+ * own canonical key round-tripping as `userId` folds back in instead of minting
38
+ * a phantom `external_id` twin. NEVER set from a request body (the public route
39
+ * schemas omit it); the public/publishable boundary cannot forge it.
40
+ */
41
+ contactId?: string;
29
42
  /**
30
43
  * Discord user id (snowflake). Resolves a `discord`-keyed contact (a later
31
44
  * per-member link merges it into the email contact).
@@ -185,21 +198,46 @@ export async function ingestEvent(opts: {
185
198
  // `contacts.properties` (D2 split) and returns BOTH the canonical contact id
186
199
  // AND its resolved string key (external_id ?? anonymous_id ?? contact.id —
187
200
  // risk 1/6), so no second read-back of the contact row is needed.
201
+ let resolved: Awaited<ReturnType<typeof resolveOrCreateContact>>;
202
+ try {
203
+ resolved = await resolveOrCreateContact({
204
+ db,
205
+ userId: event.userId,
206
+ email: event.userEmail || undefined,
207
+ anonymousId: event.anonymousId,
208
+ discordId: event.discordId,
209
+ // ENGINE-INTERNAL provenance pin (never from a request body — public route
210
+ // schemas omit it). Pins to the subject's own row so an internal re-emit
211
+ // whose userId is the contact's canonical key folds in, not a phantom twin.
212
+ contactId: event.contactId,
213
+ contactProperties: event.contactProperties,
214
+ restrictToAnonymous: opts.restrictToAnonymous,
215
+ });
216
+ } catch (err) {
217
+ // Provenance pin pointed at a hard-deleted/unfollowable subject: drop the
218
+ // internal re-emit (do NOT value-fall-back — that could mint the very twin
219
+ // the pin prevents). Reachable only for a hard-deleted subject.
220
+ if (err instanceof ContactProvenanceLostError) {
221
+ logger.warn("identity.provenance.lost — dropping internal re-emit", {
222
+ event: event.event,
223
+ contactId: err.contactId,
224
+ source: event.source ?? null,
225
+ });
226
+ return {
227
+ stored: false,
228
+ exits: [],
229
+ contactKey: event.userId ?? event.anonymousId ?? err.contactId,
230
+ };
231
+ }
232
+ throw err;
233
+ }
188
234
  const {
189
235
  id: contactId,
190
236
  resolvedKey,
191
237
  mergedKeys,
192
238
  mergedIdentifiedKeys,
193
239
  merged,
194
- } = await resolveOrCreateContact({
195
- db,
196
- userId: event.userId,
197
- email: event.userEmail || undefined,
198
- anonymousId: event.anonymousId,
199
- discordId: event.discordId,
200
- contactProperties: event.contactProperties,
201
- restrictToAnonymous: opts.restrictToAnonymous,
202
- });
240
+ } = resolved;
203
241
 
204
242
  // Caller-supplied event time (backfill/replay). Coerced to a Date; undefined
205
243
  // falls back to the `occurred_at` DB default (ingest instant).
@@ -327,6 +365,11 @@ export async function ingestEvent(opts: {
327
365
  userId: resolvedKey,
328
366
  userEmail: event.userEmail ?? "",
329
367
  properties: serializableProperties,
368
+ // ENGINE-INTERNAL provenance: the resolved subject row id, so a journey
369
+ // enrolling on this event can re-emit for the SAME subject by row id
370
+ // (folds, never mints a twin). Additive/optional — consumers ignoring it
371
+ // are unaffected.
372
+ contactId,
330
373
  }),
331
374
  checkExits(db, registry, hatchet, logger, {
332
375
  userId: resolvedKey,
@@ -49,6 +49,7 @@ function emitMarkEvents(
49
49
  eventType: string;
50
50
  feedId: string;
51
51
  recipientKey: string;
52
+ contactId?: string;
52
53
  },
53
54
  ): Promise<unknown> {
54
55
  return Promise.allSettled(
@@ -60,6 +61,11 @@ function emitMarkEvents(
60
61
  // recipientKey IS the canonical contact key — pass it as userId so
61
62
  // the resolver lands on the SAME contact.
62
63
  userId: args.recipientKey,
64
+ // ENGINE-INTERNAL provenance (server-derived, never from the body):
65
+ // pin to the recipient's own contact row so an anon visitor's mark
66
+ // re-ingest folds in by row id instead of minting a phantom
67
+ // external_id=<anonId> twin that would 403-lock their own feed.
68
+ contactId: args.contactId,
63
69
  eventProperties: { feedItemId: r.id, feedId: args.feedId },
64
70
  idempotencyKey: `inapp:${args.feedId}:${r.id}:${args.eventType}`,
65
71
  source: "inapp",
@@ -407,7 +413,13 @@ export const feedRouter = new OpenAPIHono<AppEnv>()
407
413
  // absorbed by `user_events.idempotencyKey`), so the journey fires once.
408
414
  await emitMarkEvents(
409
415
  { db, registry, hatchet, logger, analytics },
410
- { ids: updated, eventType, feedId, recipientKey: rec.recipientKey },
416
+ {
417
+ ids: updated,
418
+ eventType,
419
+ feedId,
420
+ recipientKey: rec.recipientKey,
421
+ contactId: rec.contactId,
422
+ },
411
423
  );
412
424
 
413
425
  return c.json({ updated: updated.length }, 200);
@@ -443,6 +455,9 @@ export const feedRouter = new OpenAPIHono<AppEnv>()
443
455
  event: {
444
456
  event: "inapp.feed_cleared",
445
457
  userId: rec.recipientKey,
458
+ // ENGINE-INTERNAL provenance — fold into the recipient's own contact
459
+ // row by id, never mint a phantom twin (see emitMarkEvents).
460
+ contactId: rec.contactId,
446
461
  eventProperties: { feedId },
447
462
  idempotencyKey: `inapp:${feedId}:all:inapp.feed_cleared`,
448
463
  source: "inapp",
@@ -451,7 +466,13 @@ export const feedRouter = new OpenAPIHono<AppEnv>()
451
466
  } else {
452
467
  await emitMarkEvents(
453
468
  { db, registry, hatchet, logger, analytics },
454
- { ids: updated, eventType, feedId, recipientKey: rec.recipientKey },
469
+ {
470
+ ids: updated,
471
+ eventType,
472
+ feedId,
473
+ recipientKey: rec.recipientKey,
474
+ contactId: rec.contactId,
475
+ },
455
476
  );
456
477
  }
457
478
 
@@ -13,7 +13,7 @@ import {
13
13
  } from "../../lib/user-token.js";
14
14
 
15
15
  export type FeedRecipient =
16
- | { ok: true; recipientKey: string }
16
+ | { ok: true; recipientKey: string; contactId?: string }
17
17
  | { ok: false; status: 400 | 403; error: string };
18
18
 
19
19
  export interface FeedRecipientParams {
@@ -71,18 +71,17 @@ export async function resolveFeedRecipient(
71
71
  }
72
72
  throw err;
73
73
  }
74
- return { ok: true, recipientKey: await canonicalKey(db, { userId }) };
74
+ const ck = await canonicalKey(db, { userId });
75
+ return { ok: true, recipientKey: ck.recipientKey, contactId: ck.contactId };
75
76
  }
76
77
 
77
78
  // 2. Secret key: trust userId/email directly.
78
79
  if (!publishable && (params.userId || params.email)) {
79
- return {
80
- ok: true,
81
- recipientKey: await canonicalKey(db, {
82
- userId: params.userId,
83
- email: params.email,
84
- }),
85
- };
80
+ const ck = await canonicalKey(db, {
81
+ userId: params.userId,
82
+ email: params.email,
83
+ });
84
+ return { ok: true, recipientKey: ck.recipientKey, contactId: ck.contactId };
86
85
  }
87
86
 
88
87
  // 3. Publishable anon: its raw anon id IS its recipientKey (no resolver — see
@@ -100,7 +99,27 @@ export async function resolveFeedRecipient(
100
99
  error: "anonymousId is not addressable",
101
100
  };
102
101
  }
103
- return { ok: true, recipientKey: params.anonymousId };
102
+ // Surface the anon contact's row id (when it exists) as engine-internal
103
+ // provenance. The feed's OWN mark/clear re-ingests (emitMarkEvents,
104
+ // inapp.feed_cleared) re-ingest keyed `userId: recipientKey` = this raw anon
105
+ // id; threading the row id makes them fold into THIS contact by id instead of
106
+ // minting a phantom `external_id=<anonId>` twin — the twin that then trips
107
+ // collidesWithIdentified and 403-locks the visitor out of their own feed.
108
+ const anonRow = await db
109
+ .select({ id: contacts.id })
110
+ .from(contacts)
111
+ .where(
112
+ and(
113
+ eq(contacts.anonymousId, params.anonymousId),
114
+ isNull(contacts.deletedAt),
115
+ ),
116
+ )
117
+ .limit(1);
118
+ return {
119
+ ok: true,
120
+ recipientKey: params.anonymousId,
121
+ contactId: anonRow[0]?.id,
122
+ };
104
123
  }
105
124
 
106
125
  // 4. No identity → fail-closed.
@@ -163,7 +182,7 @@ async function collidesWithIdentified(
163
182
  async function canonicalKey(
164
183
  db: Database,
165
184
  ident: { userId?: string; email?: string },
166
- ): Promise<string> {
185
+ ): Promise<{ recipientKey: string; contactId?: string }> {
167
186
  if (ident.email) {
168
187
  const email = normalizeEmail(ident.email);
169
188
  const rows = await db
@@ -171,13 +190,14 @@ async function canonicalKey(
171
190
  .from(contacts)
172
191
  .where(and(eq(contacts.email, email), isNull(contacts.deletedAt)))
173
192
  .limit(1);
174
- if (rows[0]) return contactKey(rows[0]);
175
- return email;
193
+ if (rows[0])
194
+ return { recipientKey: contactKey(rows[0]), contactId: rows[0].id };
195
+ return { recipientKey: email };
176
196
  }
177
197
  if (ident.userId) {
178
198
  const row = await resolveContact({ db, id: ident.userId });
179
- if (row) return contactKey(row);
180
- return ident.userId;
199
+ if (row) return { recipientKey: contactKey(row), contactId: row.id };
200
+ return { recipientKey: ident.userId };
181
201
  }
182
- return "";
202
+ return { recipientKey: "" };
183
203
  }