@hogsend/engine 0.35.1 → 0.36.0
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 +7 -7
- package/src/app.ts +22 -1
- package/src/index.ts +48 -0
- package/src/lib/api-key-hash.ts +7 -2
- package/src/lib/banner.ts +71 -0
- package/src/lib/contacts.ts +57 -0
- package/src/lib/feed.ts +233 -0
- package/src/lib/ingestion.ts +10 -0
- package/src/lib/user-token.ts +100 -0
- package/src/middleware/api-key.ts +4 -0
- package/src/middleware/publishable-key.ts +119 -0
- package/src/middleware/require-admin.ts +18 -2
- package/src/routes/_shared.ts +61 -0
- package/src/routes/admin/api-keys.ts +46 -10
- package/src/routes/contacts/index.ts +38 -12
- package/src/routes/events/index.ts +70 -30
- package/src/routes/feed/index.ts +503 -0
- package/src/routes/feed/recipient.ts +183 -0
- package/src/routes/index.ts +65 -7
- package/src/routes/lists/index.ts +126 -6
- package/src/worker.ts +2 -0
- package/src/workflows/send-feed.ts +44 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hogsend/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.36.0",
|
|
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.
|
|
46
|
-
"@hogsend/db": "^0.
|
|
47
|
-
"@hogsend/email": "^0.
|
|
48
|
-
"@hogsend/plugin-posthog": "^0.
|
|
49
|
-
"@hogsend/plugin-resend": "^0.
|
|
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"
|
|
50
50
|
},
|
|
51
51
|
"optionalDependencies": {
|
|
52
|
-
"@hogsend/plugin-postmark": "^0.
|
|
52
|
+
"@hogsend/plugin-postmark": "^0.36.0"
|
|
53
53
|
},
|
|
54
54
|
"devDependencies": {
|
|
55
55
|
"@types/node": "^22.15.3",
|
package/src/app.ts
CHANGED
|
@@ -30,6 +30,11 @@ export type AppEnv = {
|
|
|
30
30
|
user: NonNullable<AuthSession>["user"] | null;
|
|
31
31
|
session: NonNullable<AuthSession>["session"] | null;
|
|
32
32
|
apiKey: ApiKeyContext | undefined;
|
|
33
|
+
// True when the request authenticated with a PUBLISHABLE (pk_) key via
|
|
34
|
+
// `requirePublishableOrIngest`. Publishable-reachable handlers gate their
|
|
35
|
+
// identity logic on this (a pk_ key is anon-only without a verified
|
|
36
|
+
// userToken). Undefined/false for secret-key + session requests.
|
|
37
|
+
publishable?: boolean;
|
|
33
38
|
};
|
|
34
39
|
};
|
|
35
40
|
|
|
@@ -77,7 +82,23 @@ export function createApp(
|
|
|
77
82
|
});
|
|
78
83
|
|
|
79
84
|
app.use("*", secureHeaders());
|
|
80
|
-
app.use(
|
|
85
|
+
app.use(
|
|
86
|
+
"*",
|
|
87
|
+
cors({
|
|
88
|
+
// Reflect the request Origin so a browser can READ the response (needed
|
|
89
|
+
// for pk_ publishable-key ingest from arbitrary first-party origins).
|
|
90
|
+
// This is NOT the security boundary — the per-key Origin allowlist is
|
|
91
|
+
// enforced inside `requirePublishableOrIngest` on the actual (non-
|
|
92
|
+
// preflight) request. A preflight carries no Bearer, so the key class is
|
|
93
|
+
// unknowable here; echoing the Origin lets the browser proceed to the
|
|
94
|
+
// real request, which the guard then accepts or 403s. Returning "*" for an
|
|
95
|
+
// Origin-less request (same-origin / server SDK) preserves today's
|
|
96
|
+
// wildcard behavior. `credentials` stays default-off (pk_ ingest is
|
|
97
|
+
// header-bearer, not cookie-auth), so reflecting the Origin does not widen
|
|
98
|
+
// credentialed/cookie exposure.
|
|
99
|
+
origin: (origin) => origin ?? "*",
|
|
100
|
+
}),
|
|
101
|
+
);
|
|
81
102
|
app.use("*", compress());
|
|
82
103
|
app.use("*", requestId());
|
|
83
104
|
app.use("*", requestLogger);
|
package/src/index.ts
CHANGED
|
@@ -232,6 +232,12 @@ export {
|
|
|
232
232
|
type BatchedBackfillResult,
|
|
233
233
|
runBatchedBackfill,
|
|
234
234
|
} from "./lib/backfill.js";
|
|
235
|
+
// --- On-site banners (thin over sendFeedItem, category `banner:<slot>`) ---
|
|
236
|
+
export {
|
|
237
|
+
type SendBannerOptions,
|
|
238
|
+
type SendBannerResult,
|
|
239
|
+
sendBanner,
|
|
240
|
+
} from "./lib/banner.js";
|
|
235
241
|
// --- Boot output (engine-owned startup banner / structured ready log) ---
|
|
236
242
|
export {
|
|
237
243
|
type ApiReadyInfo,
|
|
@@ -327,6 +333,13 @@ export type {
|
|
|
327
333
|
} from "./lib/email-service-types.js";
|
|
328
334
|
// --- Enrollment guards ---
|
|
329
335
|
export { checkEmailPreferences } from "./lib/enrollment-guards.js";
|
|
336
|
+
// --- In-app feed (sendFeedItem — sibling of sendEmail/sendConnectorAction) ---
|
|
337
|
+
export {
|
|
338
|
+
IN_APP_LIST_ID,
|
|
339
|
+
type SendFeedItemOptions,
|
|
340
|
+
type SendFeedItemResult,
|
|
341
|
+
sendFeedItem,
|
|
342
|
+
} from "./lib/feed.js";
|
|
330
343
|
export { isFrequencyCapped } from "./lib/frequency-cap.js";
|
|
331
344
|
export { addrSpecOf, hostOfFromAddress } from "./lib/from-address.js";
|
|
332
345
|
export { hatchet } from "./lib/hatchet.js";
|
|
@@ -451,6 +464,40 @@ export {
|
|
|
451
464
|
*/
|
|
452
465
|
resolveEmailSendContextByResendId,
|
|
453
466
|
} from "./lib/tracking-events.js";
|
|
467
|
+
/**
|
|
468
|
+
* Publishable-key `userToken` mint/verify helpers.
|
|
469
|
+
*
|
|
470
|
+
* `generateUserToken` is the official SERVER-SIDE mint helper. It signs a
|
|
471
|
+
* short-lived HMAC over a `userId` with `BETTER_AUTH_SECRET`. A publishable
|
|
472
|
+
* (`pk_`) key is anon-only by default; to let an identified browser act on a
|
|
473
|
+
* concrete `userId`, the HOST BACKEND calls this AFTER its own login and hands
|
|
474
|
+
* the result to the browser:
|
|
475
|
+
*
|
|
476
|
+
* ```ts
|
|
477
|
+
* // host server route, AFTER authenticating the user — NEVER expose the secret:
|
|
478
|
+
* import { generateUserToken } from "@hogsend/engine";
|
|
479
|
+
* const userToken = generateUserToken({
|
|
480
|
+
* secret: process.env.BETTER_AUTH_SECRET!,
|
|
481
|
+
* userId: session.user.id,
|
|
482
|
+
* expiresInSeconds: 3600,
|
|
483
|
+
* });
|
|
484
|
+
* // return { userToken } to the browser; the SDK threads it into every
|
|
485
|
+
* // identity-asserting data-plane call (createHogsend({ userToken }) /
|
|
486
|
+
* // <HogsendProvider userToken={...}>). On expiry the SDK calls
|
|
487
|
+
* // config.onUserTokenExpiring() — point that at re-hitting this route.
|
|
488
|
+
* ```
|
|
489
|
+
*
|
|
490
|
+
* SERVER-SIDE ONLY: it uses `node:crypto` and needs `BETTER_AUTH_SECRET`. Do
|
|
491
|
+
* NOT mount it as a route and do NOT call it from a browser (it would leak the
|
|
492
|
+
* signing secret). `verifyUserToken` is the symmetric half the engine wires
|
|
493
|
+
* into every publishable-reachable handler.
|
|
494
|
+
*/
|
|
495
|
+
export {
|
|
496
|
+
generateUserToken,
|
|
497
|
+
InvalidUserTokenError,
|
|
498
|
+
type UserTokenPayload,
|
|
499
|
+
verifyUserToken,
|
|
500
|
+
} from "./lib/user-token.js";
|
|
454
501
|
// --- Outbound webhooks: signing core (Section 1.2) ---
|
|
455
502
|
export {
|
|
456
503
|
generateWebhookSecret,
|
|
@@ -518,3 +565,4 @@ export { importContactsTask } from "./workflows/import-contacts.js";
|
|
|
518
565
|
export { sendCampaignTask } from "./workflows/send-campaign.js";
|
|
519
566
|
// --- Built-in Hatchet workflow tasks ---
|
|
520
567
|
export { sendEmailTask } from "./workflows/send-email.js";
|
|
568
|
+
export { sendFeedTask } from "./workflows/send-feed.js";
|
package/src/lib/api-key-hash.ts
CHANGED
|
@@ -2,13 +2,18 @@ import { createHash, randomBytes } from "node:crypto";
|
|
|
2
2
|
|
|
3
3
|
const PREFIX_LENGTH = 8;
|
|
4
4
|
|
|
5
|
-
export function generateApiKey(): {
|
|
5
|
+
export function generateApiKey(opts?: { publishable?: boolean }): {
|
|
6
6
|
key: string;
|
|
7
7
|
prefix: string;
|
|
8
8
|
hash: string;
|
|
9
9
|
} {
|
|
10
10
|
const raw = randomBytes(32).toString("base64url");
|
|
11
|
-
|
|
11
|
+
// Publishable (browser-safe) keys are minted with the `pk_` class prefix;
|
|
12
|
+
// secret server keys keep `hsk_`. The class lives ENTIRELY in the raw token's
|
|
13
|
+
// prefix — no DB column — so the request guard can branch on the bearer's
|
|
14
|
+
// prefix before any DB work (the CORS preflight carries no bearer, so the
|
|
15
|
+
// class is unknowable at the CORS layer; the guard is the boundary).
|
|
16
|
+
const key = `${opts?.publishable ? "pk_" : "hsk_"}${raw}`;
|
|
12
17
|
const prefix = key.slice(0, PREFIX_LENGTH);
|
|
13
18
|
const hash = hashApiKey(key);
|
|
14
19
|
return { key, prefix, hash };
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
import type { FeedBlock } from "@hogsend/db";
|
|
2
|
+
import { type SendFeedItemResult, sendFeedItem } from "./feed.js";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The banner-category prefix. A banner is just a delivered feed item in a
|
|
6
|
+
* dedicated, per-slot category `banner:<slot>` (NOT the default `in_app` feed),
|
|
7
|
+
* so banners never pollute the notification bell and map onto the SAME
|
|
8
|
+
* recipient-scoped read path (`GET /v1/feed?feedId=banner:<slot>`).
|
|
9
|
+
*/
|
|
10
|
+
export const BANNER_CATEGORY_PREFIX = "banner:";
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Compose the feed category for a banner slot. `banner:<slot>`.
|
|
14
|
+
*/
|
|
15
|
+
export function bannerCategory(slot: string): string {
|
|
16
|
+
return `${BANNER_CATEGORY_PREFIX}${slot}`;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export interface SendBannerOptions {
|
|
20
|
+
recipient: { userId?: string; email?: string; anonymousId?: string };
|
|
21
|
+
/** Banner placement slot (e.g. `"top"`, `"billing"`). Maps to category `banner:<slot>`. */
|
|
22
|
+
slot: string;
|
|
23
|
+
title?: string;
|
|
24
|
+
body?: string;
|
|
25
|
+
blocks?: FeedBlock[];
|
|
26
|
+
actionUrl?: string;
|
|
27
|
+
metadata?: Record<string, unknown>;
|
|
28
|
+
templateKey?: string;
|
|
29
|
+
journeyStateId?: string;
|
|
30
|
+
/** Explicit idempotency key — wins over journey auto-derivation. */
|
|
31
|
+
idempotencyKey?: string;
|
|
32
|
+
/** Disambiguates the exactly-once key across divergent branches. */
|
|
33
|
+
idempotencyLabel?: string;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export type SendBannerResult = SendFeedItemResult;
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Journey-callable on-site banner send — a thin wrapper over {@link sendFeedItem}
|
|
40
|
+
* that pins `type: "banner"` and `category: "banner:<slot>"`. It inherits feed
|
|
41
|
+
* recipient resolution, `in_app` suppression, replay-safe idempotency, and the
|
|
42
|
+
* Redis `feed:<recipientKey>` realtime publish (so banners are realtime too).
|
|
43
|
+
*
|
|
44
|
+
* The dedicated `banner:<slot>` category keeps banners out of the default
|
|
45
|
+
* `in_app` notification feed. The browser reads them via
|
|
46
|
+
* `GET /v1/feed?feedId=banner:<slot>` (the existing route category-filters and
|
|
47
|
+
* recipient-scopes server-side — no new read path).
|
|
48
|
+
*
|
|
49
|
+
* Event story: dismiss/click persist via the feed `/mark` route, whose
|
|
50
|
+
* `inapp.*` emits are INTERNAL feed-state bookkeeping. The consumer-facing
|
|
51
|
+
* journey trigger is the distinct-namespace `banner.dismissed` / `banner.clicked`
|
|
52
|
+
* / `banner.shown` the SDK emits client-side.
|
|
53
|
+
*/
|
|
54
|
+
export async function sendBanner(
|
|
55
|
+
opts: SendBannerOptions,
|
|
56
|
+
): Promise<SendBannerResult> {
|
|
57
|
+
return sendFeedItem({
|
|
58
|
+
recipient: opts.recipient,
|
|
59
|
+
type: "banner",
|
|
60
|
+
category: bannerCategory(opts.slot),
|
|
61
|
+
title: opts.title,
|
|
62
|
+
body: opts.body,
|
|
63
|
+
blocks: opts.blocks,
|
|
64
|
+
actionUrl: opts.actionUrl,
|
|
65
|
+
metadata: opts.metadata,
|
|
66
|
+
templateKey: opts.templateKey,
|
|
67
|
+
journeyStateId: opts.journeyStateId,
|
|
68
|
+
idempotencyKey: opts.idempotencyKey,
|
|
69
|
+
idempotencyLabel: opts.idempotencyLabel,
|
|
70
|
+
});
|
|
71
|
+
}
|
package/src/lib/contacts.ts
CHANGED
|
@@ -13,6 +13,27 @@ import { and, eq, ilike, inArray, isNull, or, sql } from "drizzle-orm";
|
|
|
13
13
|
const UUID_REGEX =
|
|
14
14
|
/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
15
15
|
|
|
16
|
+
/**
|
|
17
|
+
* Thrown by {@link resolveOrCreateContact} when a PUBLISHABLE (browser, pk_) anon
|
|
18
|
+
* write would attach to / merge into / mutate a contact that already carries an
|
|
19
|
+
* IDENTIFIED key (`external_id` or `email`), OR would drive a collide-MERGE.
|
|
20
|
+
*
|
|
21
|
+
* The `anonymousId` (PostHog `get_distinct_id()`) is browser-readable by design,
|
|
22
|
+
* so on the publishable path it is NOT a secret and must never be a merge driver
|
|
23
|
+
* or a path to a victim's identified contact. An anon-only publishable write may
|
|
24
|
+
* only create or update its OWN anonymous-only contact. Handlers translate this
|
|
25
|
+
* to a 403. The secret-key path NEVER sets `restrictToAnonymous`, so its behavior
|
|
26
|
+
* is unchanged.
|
|
27
|
+
*/
|
|
28
|
+
export class PublishableAnonymousMergeError extends Error {
|
|
29
|
+
constructor(
|
|
30
|
+
message = "publishable anonymous write cannot attach to or merge an identified contact",
|
|
31
|
+
) {
|
|
32
|
+
super(message);
|
|
33
|
+
this.name = "PublishableAnonymousMergeError";
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
16
37
|
/**
|
|
17
38
|
* The transaction handle drizzle hands to a `db.transaction(cb)` callback. It
|
|
18
39
|
* exposes the same `.select/.insert/.update/.execute/.query` surface as the
|
|
@@ -341,6 +362,18 @@ export async function resolveOrCreateContact(opts: {
|
|
|
341
362
|
anonymousId?: string;
|
|
342
363
|
discordId?: string;
|
|
343
364
|
contactProperties?: Record<string, unknown>;
|
|
365
|
+
/**
|
|
366
|
+
* PUBLISHABLE (browser, pk_) safety clamp (§Phase 1 GAP-1). When set, an
|
|
367
|
+
* anon-only write (no `userId`/`email`/`discordId`) may ONLY create or update
|
|
368
|
+
* its own anonymous-only contact: it is forbidden from filling-in-linking to,
|
|
369
|
+
* or merging with, any contact that already carries an `external_id`/`email`,
|
|
370
|
+
* and from driving a collide-MERGE — throwing {@link
|
|
371
|
+
* PublishableAnonymousMergeError}. The `anonymousId` is browser-readable
|
|
372
|
+
* (`get_distinct_id()`), so without this clamp a pk_ key could forge events as
|
|
373
|
+
* / poison a victim's identified contact via the anon resolution arm. The
|
|
374
|
+
* secret-key path NEVER sets this, so its behavior is byte-for-byte unchanged.
|
|
375
|
+
*/
|
|
376
|
+
restrictToAnonymous?: boolean;
|
|
344
377
|
}): Promise<{
|
|
345
378
|
id: string;
|
|
346
379
|
/**
|
|
@@ -376,6 +409,16 @@ export async function resolveOrCreateContact(opts: {
|
|
|
376
409
|
const email = opts.email ? normalizeEmail(opts.email) : undefined;
|
|
377
410
|
const anonymousId = opts.anonymousId?.trim() || undefined;
|
|
378
411
|
const discordId = opts.discordId?.trim() || undefined;
|
|
412
|
+
// §Phase 1 GAP-1: the publishable clamp only bites an ANON-ONLY write (the
|
|
413
|
+
// only shape a token-less pk_ key can produce — the gate 403s any
|
|
414
|
+
// email/userId without a verified userToken before we get here). An identified
|
|
415
|
+
// arm (token-authorized userId, or the secret path) is never clamped.
|
|
416
|
+
const restrictToAnonymous =
|
|
417
|
+
opts.restrictToAnonymous === true &&
|
|
418
|
+
!userId &&
|
|
419
|
+
!email &&
|
|
420
|
+
!discordId &&
|
|
421
|
+
!!anonymousId;
|
|
379
422
|
|
|
380
423
|
const keys: ResolveKey[] = [];
|
|
381
424
|
if (userId) keys.push({ kind: "external", value: userId });
|
|
@@ -440,6 +483,14 @@ export async function resolveOrCreateContact(opts: {
|
|
|
440
483
|
// --- CASE: fill-in-link (single existing row) ---
|
|
441
484
|
const single = candidates[0];
|
|
442
485
|
if (candidates.length === 1 && single) {
|
|
486
|
+
// §Phase 1 GAP-1: an anon-only publishable write resolved to an EXISTING
|
|
487
|
+
// contact that already carries an identified key (`external_id`/`email`)
|
|
488
|
+
// is a forge/poison attempt — the browser-readable anonymousId pointed at
|
|
489
|
+
// a victim. Refuse to fill-in-link / mutate it. (Resolving to its OWN
|
|
490
|
+
// anonymous-only contact — no external_id, no email — is allowed.)
|
|
491
|
+
if (restrictToAnonymous && (single.externalId || single.email)) {
|
|
492
|
+
throw new PublishableAnonymousMergeError();
|
|
493
|
+
}
|
|
443
494
|
const { id, resolvedKey, mergedKeys, mergedIdentifiedKeys } =
|
|
444
495
|
await fillInLink(tx, single, {
|
|
445
496
|
userId,
|
|
@@ -461,6 +512,12 @@ export async function resolveOrCreateContact(opts: {
|
|
|
461
512
|
}
|
|
462
513
|
|
|
463
514
|
// --- CASE: collide-MERGE (2-3 distinct rows) ---
|
|
515
|
+
// §Phase 1 GAP-1: an anon-only publishable write must NEVER drive a merge —
|
|
516
|
+
// the browser-readable anonymousId would let an attacker fold two of a
|
|
517
|
+
// victim's contacts together (identity-graph corruption). Refuse.
|
|
518
|
+
if (restrictToAnonymous) {
|
|
519
|
+
throw new PublishableAnonymousMergeError();
|
|
520
|
+
}
|
|
464
521
|
const { id, resolvedKey, mergedKeys, mergedIdentifiedKeys } =
|
|
465
522
|
await mergeContacts(tx, candidates, {
|
|
466
523
|
userId,
|
package/src/lib/feed.ts
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
import { emailPreferences, type FeedBlock, feedItems } from "@hogsend/db";
|
|
2
|
+
import { and, eq } from "drizzle-orm";
|
|
3
|
+
import {
|
|
4
|
+
deriveJourneyKey,
|
|
5
|
+
getJourneyBoundary,
|
|
6
|
+
registerKey,
|
|
7
|
+
} from "../journeys/journey-boundary.js";
|
|
8
|
+
import { getListRegistry } from "../lists/registry-singleton.js";
|
|
9
|
+
import { resolveOrCreateContact, resolveRecipient } from "./contacts.js";
|
|
10
|
+
import { getDb } from "./db.js";
|
|
11
|
+
import { createLogger } from "./logger.js";
|
|
12
|
+
import { getRedis } from "./redis.js";
|
|
13
|
+
|
|
14
|
+
const logger = createLogger(process.env.LOG_LEVEL);
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Reserved list id governing in-app feed suppression (mirrors the built-in
|
|
18
|
+
* `transactional` / `journey` categories). A recipient unsubscribed from
|
|
19
|
+
* `in_app` (or `unsubscribed_all`) gets no feed items.
|
|
20
|
+
*/
|
|
21
|
+
export const IN_APP_LIST_ID = "in_app";
|
|
22
|
+
|
|
23
|
+
export interface SendFeedItemOptions {
|
|
24
|
+
recipient: { userId?: string; email?: string; anonymousId?: string };
|
|
25
|
+
type: string;
|
|
26
|
+
title?: string;
|
|
27
|
+
body?: string;
|
|
28
|
+
blocks?: FeedBlock[];
|
|
29
|
+
actionUrl?: string;
|
|
30
|
+
metadata?: Record<string, unknown>;
|
|
31
|
+
/** Item category (the feed it lands in). Default `"in_app"`. */
|
|
32
|
+
category?: string;
|
|
33
|
+
templateKey?: string;
|
|
34
|
+
journeyStateId?: string;
|
|
35
|
+
/**
|
|
36
|
+
* Explicit idempotency key. A public caller sets it directly; it always wins
|
|
37
|
+
* over the engine's journey auto-derivation. Journey sends leave it unset.
|
|
38
|
+
*/
|
|
39
|
+
idempotencyKey?: string;
|
|
40
|
+
/**
|
|
41
|
+
* Disambiguates the exactly-once key when the SAME feed type is sent more than
|
|
42
|
+
* once in one journey enrollment on divergent branches sharing a nearest wait
|
|
43
|
+
* label. Mirrors `sendEmail()`'s `idempotencyLabel`. Additive and optional.
|
|
44
|
+
*/
|
|
45
|
+
idempotencyLabel?: string;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export interface SendFeedItemResult {
|
|
49
|
+
/** The inserted row id, or `null` when suppressed or idempotent-deduped. */
|
|
50
|
+
feedItemId: string | null;
|
|
51
|
+
/** The resolved canonical recipient key (null only when no recipient given). */
|
|
52
|
+
recipientKey: string | null;
|
|
53
|
+
suppressed: boolean;
|
|
54
|
+
createdAt: string | null;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Journey-callable in-app feed send — the standalone, single-object-in /
|
|
59
|
+
* result-out counterpart to `sendEmail()` / `sendConnectorAction()`. NOT on
|
|
60
|
+
* `JourneyContext` (features are standalone imports).
|
|
61
|
+
*
|
|
62
|
+
* Pipeline: resolve recipient → canonical key → `in_app` suppression check →
|
|
63
|
+
* insert a `feed_items` row (replay-safe idempotency when in a journey) → publish
|
|
64
|
+
* to the Redis realtime channel `feed:<recipientKey>` on the COMMAND singleton.
|
|
65
|
+
*
|
|
66
|
+
* Replay-safety mirrors `sendEmail()`: inside a journey the engine derives a
|
|
67
|
+
* deterministic, branch-stable key off `boundary.runAnchor` (the Hatchet run id,
|
|
68
|
+
* NOT the freshly-minted state id) so a replay re-firing the same logical send
|
|
69
|
+
* re-derives the SAME key and the unique `feed_items.idempotencyKey` index
|
|
70
|
+
* (`onConflictDoNothing`, Layer 2) absorbs the duplicate insert. When eviction is
|
|
71
|
+
* supported, the whole insert+publish runs inside `boundary.memoize` (Layer 1).
|
|
72
|
+
*/
|
|
73
|
+
export async function sendFeedItem(
|
|
74
|
+
opts: SendFeedItemOptions,
|
|
75
|
+
): Promise<SendFeedItemResult> {
|
|
76
|
+
const db = getDb();
|
|
77
|
+
const { recipient } = opts;
|
|
78
|
+
const category = opts.category ?? IN_APP_LIST_ID;
|
|
79
|
+
|
|
80
|
+
// (1) Resolve recipient → canonical key. Throws on a zero-key recipient (same
|
|
81
|
+
// contract as `resolveOrCreateContact`). This is a server/journey-side send —
|
|
82
|
+
// never a browser write — so no `restrictToAnonymous` clamp.
|
|
83
|
+
const { id: contactId, resolvedKey } = await resolveOrCreateContact({
|
|
84
|
+
db,
|
|
85
|
+
userId: recipient.userId,
|
|
86
|
+
email: recipient.email,
|
|
87
|
+
anonymousId: recipient.anonymousId,
|
|
88
|
+
});
|
|
89
|
+
const recipientKey = resolvedKey;
|
|
90
|
+
|
|
91
|
+
// (2) `in_app` suppression check. Suppression is governed by the `in_app` list
|
|
92
|
+
// key regardless of the item's own category. `email_preferences` is
|
|
93
|
+
// `(user_id, email)`-keyed; an anon-only recipient has no pref row → categories
|
|
94
|
+
// = {} → opt-in default → not suppressed (you cannot suppress what has no
|
|
95
|
+
// preference surface yet). `unsubscribed_all` on an identified recipient DOES
|
|
96
|
+
// suppress, consistent with the email mailer's `checkEmailPreferences`.
|
|
97
|
+
let categories: Record<string, boolean> = {};
|
|
98
|
+
const recip = await resolveRecipient({
|
|
99
|
+
db,
|
|
100
|
+
userId: recipient.userId,
|
|
101
|
+
email: recipient.email,
|
|
102
|
+
});
|
|
103
|
+
if (recip) {
|
|
104
|
+
const extId = recip.externalId ?? recip.contactId;
|
|
105
|
+
const rows = await db
|
|
106
|
+
.select()
|
|
107
|
+
.from(emailPreferences)
|
|
108
|
+
.where(
|
|
109
|
+
and(
|
|
110
|
+
eq(emailPreferences.userId, extId),
|
|
111
|
+
eq(emailPreferences.email, recip.email),
|
|
112
|
+
),
|
|
113
|
+
)
|
|
114
|
+
.limit(1);
|
|
115
|
+
const row = rows[0];
|
|
116
|
+
if (row) {
|
|
117
|
+
if (row.unsubscribedAll) {
|
|
118
|
+
return {
|
|
119
|
+
feedItemId: null,
|
|
120
|
+
recipientKey,
|
|
121
|
+
suppressed: true,
|
|
122
|
+
createdAt: null,
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
categories = (row.categories ?? {}) as Record<string, boolean>;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
if (!getListRegistry().isSubscribed(categories, IN_APP_LIST_ID)) {
|
|
129
|
+
return {
|
|
130
|
+
feedItemId: null,
|
|
131
|
+
recipientKey,
|
|
132
|
+
suppressed: true,
|
|
133
|
+
createdAt: null,
|
|
134
|
+
};
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
// (3) Replay-safe idempotency key (mirrors `sendEmail`). The `feed:`-namespaced
|
|
138
|
+
// discriminant realizes the plan's `feedSend:<runAnchor>:<site>:<type>` shape
|
|
139
|
+
// through the SAME branch-stable key engine (one primitive, not a fork).
|
|
140
|
+
const boundary = getJourneyBoundary();
|
|
141
|
+
let key: string | undefined = opts.idempotencyKey;
|
|
142
|
+
if (!key && boundary) {
|
|
143
|
+
const site = opts.idempotencyLabel ?? boundary.currentLabel ?? opts.type;
|
|
144
|
+
key = deriveJourneyKey({
|
|
145
|
+
kind: "send",
|
|
146
|
+
anchor: boundary.runAnchor,
|
|
147
|
+
site,
|
|
148
|
+
discriminant: `feed:${opts.type}`,
|
|
149
|
+
});
|
|
150
|
+
registerKey(boundary, key);
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
const doInsertAndPublish = async (): Promise<SendFeedItemResult> => {
|
|
154
|
+
// (4) Insert. `onConflictDoNothing` on the idempotency unique index (Layer 2,
|
|
155
|
+
// version-independent). A NULL key never conflicts (NULLs distinct) → always
|
|
156
|
+
// inserts.
|
|
157
|
+
const rows = await db
|
|
158
|
+
.insert(feedItems)
|
|
159
|
+
.values({
|
|
160
|
+
recipientKey,
|
|
161
|
+
contactId,
|
|
162
|
+
type: opts.type,
|
|
163
|
+
title: opts.title,
|
|
164
|
+
body: opts.body,
|
|
165
|
+
blocks: opts.blocks,
|
|
166
|
+
actionUrl: opts.actionUrl,
|
|
167
|
+
metadata: opts.metadata,
|
|
168
|
+
journeyStateId: opts.journeyStateId,
|
|
169
|
+
templateKey: opts.templateKey,
|
|
170
|
+
category,
|
|
171
|
+
idempotencyKey: key,
|
|
172
|
+
})
|
|
173
|
+
.onConflictDoNothing({ target: feedItems.idempotencyKey })
|
|
174
|
+
.returning({ id: feedItems.id, createdAt: feedItems.createdAt });
|
|
175
|
+
|
|
176
|
+
const row = rows[0];
|
|
177
|
+
if (!row) {
|
|
178
|
+
// Idempotent dedup (a prior insert with this key won) — no publish, no
|
|
179
|
+
// double.
|
|
180
|
+
return {
|
|
181
|
+
feedItemId: null,
|
|
182
|
+
recipientKey,
|
|
183
|
+
suppressed: false,
|
|
184
|
+
createdAt: null,
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
// (5) Publish on the COMMAND singleton (never `.subscribe()` here — that is
|
|
189
|
+
// the SSE route's dedicated duplicate). Publish failure is non-fatal: the row
|
|
190
|
+
// is persisted, the next poll/fetch sees it.
|
|
191
|
+
try {
|
|
192
|
+
await getRedis().publish(
|
|
193
|
+
`feed:${recipientKey}`,
|
|
194
|
+
JSON.stringify({
|
|
195
|
+
type: "item.new",
|
|
196
|
+
item: {
|
|
197
|
+
id: row.id,
|
|
198
|
+
type: opts.type,
|
|
199
|
+
title: opts.title ?? null,
|
|
200
|
+
body: opts.body ?? null,
|
|
201
|
+
blocks: opts.blocks ?? null,
|
|
202
|
+
actionUrl: opts.actionUrl ?? null,
|
|
203
|
+
metadata: opts.metadata ?? null,
|
|
204
|
+
category,
|
|
205
|
+
status: "unseen",
|
|
206
|
+
createdAt: row.createdAt.toISOString(),
|
|
207
|
+
},
|
|
208
|
+
}),
|
|
209
|
+
);
|
|
210
|
+
} catch (err) {
|
|
211
|
+
logger.warn("feed publish failed", {
|
|
212
|
+
recipientKey,
|
|
213
|
+
error: err instanceof Error ? err.message : String(err),
|
|
214
|
+
});
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
return {
|
|
218
|
+
feedItemId: row.id,
|
|
219
|
+
recipientKey,
|
|
220
|
+
suppressed: false,
|
|
221
|
+
createdAt: row.createdAt.toISOString(),
|
|
222
|
+
};
|
|
223
|
+
};
|
|
224
|
+
|
|
225
|
+
// Layer 1 (eviction-gated, FREE) fast path. When inside a journey on an
|
|
226
|
+
// eviction-capable engine, a replay returns the recorded result WITHOUT
|
|
227
|
+
// re-hitting the DB; Layer 2 (`onConflictDoNothing`) is the version-independent
|
|
228
|
+
// backstop. Outside a journey, run directly.
|
|
229
|
+
if (boundary && key) {
|
|
230
|
+
return boundary.memoize([key], doInsertAndPublish);
|
|
231
|
+
}
|
|
232
|
+
return doInsertAndPublish();
|
|
233
|
+
}
|
package/src/lib/ingestion.ts
CHANGED
|
@@ -166,6 +166,15 @@ export async function ingestEvent(opts: {
|
|
|
166
166
|
* no mirror.
|
|
167
167
|
*/
|
|
168
168
|
eventMirror?: AnalyticsEventMirrorConfig;
|
|
169
|
+
/**
|
|
170
|
+
* PUBLISHABLE (browser, pk_) safety clamp (§Phase 1 GAP-1). Threaded into the
|
|
171
|
+
* identity resolve so an anon-only browser write cannot attach to / merge /
|
|
172
|
+
* poison an already-identified victim contact via the browser-readable
|
|
173
|
+
* `anonymousId`. Only the public-data-plane event route sets this; every
|
|
174
|
+
* server-side ingest path (webhooks, connectors, journeys) leaves it false, so
|
|
175
|
+
* their behavior is unchanged.
|
|
176
|
+
*/
|
|
177
|
+
restrictToAnonymous?: boolean;
|
|
169
178
|
}): Promise<IngestResult> {
|
|
170
179
|
const { db, registry, hatchet, logger, event, analytics, eventMirror } = opts;
|
|
171
180
|
|
|
@@ -189,6 +198,7 @@ export async function ingestEvent(opts: {
|
|
|
189
198
|
anonymousId: event.anonymousId,
|
|
190
199
|
discordId: event.discordId,
|
|
191
200
|
contactProperties: event.contactProperties,
|
|
201
|
+
restrictToAnonymous: opts.restrictToAnonymous,
|
|
192
202
|
});
|
|
193
203
|
|
|
194
204
|
// Caller-supplied event time (backfill/replay). Coerced to a Date; undefined
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import { createHmac, timingSafeEqual } from "node:crypto";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The publishable-key `userToken` — a short-lived HMAC over a `userId`, signed
|
|
5
|
+
* with `BETTER_AUTH_SECRET` (the same trust root as the `hs_t` identity token).
|
|
6
|
+
*
|
|
7
|
+
* Unlike `hs_t` (AES-256-GCM ENCRYPTED, because it can carry an email), this
|
|
8
|
+
* token is SIGNED-NOT-ENCRYPTED: it carries only a `userId` the integrating
|
|
9
|
+
* server already knows and chose to assert, so there is no PII to hide — only
|
|
10
|
+
* integrity (a browser must not be able to forge another person's userId) to
|
|
11
|
+
* guarantee.
|
|
12
|
+
*
|
|
13
|
+
* v1 use: a publishable (pk_) key is ANON-ONLY by default. To act on a concrete
|
|
14
|
+
* `userId`, the browser must present a `userToken` the integrating server minted
|
|
15
|
+
* SERVER-SIDE (v3 ships the mint helper into the SDK / a signing endpoint). In
|
|
16
|
+
* v1 the VERIFY function exists and is wired into every publishable-reachable
|
|
17
|
+
* handler, but with no mint path exposed a pk_ key is effectively anon-only —
|
|
18
|
+
* the secure default, and the point.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
export interface UserTokenPayload {
|
|
22
|
+
userId: string;
|
|
23
|
+
exp: number;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export class InvalidUserTokenError extends Error {
|
|
27
|
+
constructor(message: string) {
|
|
28
|
+
super(message);
|
|
29
|
+
this.name = "InvalidUserTokenError";
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const DEFAULT_EXPIRY_SECONDS = 60 * 60; // 1 hour
|
|
34
|
+
|
|
35
|
+
function sign(secret: string, body: string): string {
|
|
36
|
+
return createHmac("sha256", secret).update(body).digest("base64url");
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* MINT helper — v3. Present but UNUSED by the engine in v1 (publishable keys are
|
|
41
|
+
* anon-only by default). Wired here so v3 can expose a signer (SDK / endpoint)
|
|
42
|
+
* without re-touching the verify path. Produces `<base64url(payload)>.<sig>`.
|
|
43
|
+
*/
|
|
44
|
+
export function generateUserToken(opts: {
|
|
45
|
+
secret: string;
|
|
46
|
+
userId: string;
|
|
47
|
+
expiresInSeconds?: number;
|
|
48
|
+
}): string {
|
|
49
|
+
const payload: UserTokenPayload = {
|
|
50
|
+
userId: opts.userId,
|
|
51
|
+
exp:
|
|
52
|
+
Math.floor(Date.now() / 1000) +
|
|
53
|
+
(opts.expiresInSeconds ?? DEFAULT_EXPIRY_SECONDS),
|
|
54
|
+
};
|
|
55
|
+
const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
|
|
56
|
+
return `${body}.${sign(opts.secret, body)}`;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* VERIFY: parse `<base64url(payload)>.<sig>`, verify the HMAC in constant time,
|
|
61
|
+
* and check expiry. Throws {@link InvalidUserTokenError} on any failure
|
|
62
|
+
* (malformed, bad signature, bad payload shape, expired).
|
|
63
|
+
*/
|
|
64
|
+
export function verifyUserToken(opts: {
|
|
65
|
+
token: string;
|
|
66
|
+
secret: string;
|
|
67
|
+
}): UserTokenPayload {
|
|
68
|
+
const [body, sig] = opts.token.split(".");
|
|
69
|
+
if (!body || !sig) throw new InvalidUserTokenError("Malformed token");
|
|
70
|
+
|
|
71
|
+
const expected = sign(opts.secret, body);
|
|
72
|
+
const a = Buffer.from(sig);
|
|
73
|
+
const b = Buffer.from(expected);
|
|
74
|
+
// Length check first — `timingSafeEqual` throws on a length mismatch.
|
|
75
|
+
if (a.length !== b.length || !timingSafeEqual(a, b)) {
|
|
76
|
+
throw new InvalidUserTokenError("Bad signature");
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
let payload: UserTokenPayload;
|
|
80
|
+
try {
|
|
81
|
+
payload = JSON.parse(Buffer.from(body, "base64url").toString("utf-8"));
|
|
82
|
+
} catch {
|
|
83
|
+
throw new InvalidUserTokenError("Bad token");
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
if (typeof payload.userId !== "string" || typeof payload.exp !== "number") {
|
|
87
|
+
throw new InvalidUserTokenError("Invalid payload shape");
|
|
88
|
+
}
|
|
89
|
+
// Reject an empty `userId` — it would yield an empty `recipientKey` (a falsy
|
|
90
|
+
// value the feed recipient resolver treats as "no contact"), scoping queries to
|
|
91
|
+
// `WHERE recipient_key = ''`. Defensive: a valid signature over `userId: ""`
|
|
92
|
+
// should never authorize a feed read/mark.
|
|
93
|
+
if (payload.userId.length === 0) {
|
|
94
|
+
throw new InvalidUserTokenError("Empty userId");
|
|
95
|
+
}
|
|
96
|
+
if (payload.exp < Math.floor(Date.now() / 1000)) {
|
|
97
|
+
throw new InvalidUserTokenError("Token expired");
|
|
98
|
+
}
|
|
99
|
+
return payload;
|
|
100
|
+
}
|