@hogsend/engine 0.35.1 → 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 +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 +189 -0
- package/src/lib/feed.ts +233 -0
- package/src/lib/ingestion.ts +62 -9
- 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 +524 -0
- package/src/routes/feed/recipient.ts +203 -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/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
|
@@ -16,7 +16,10 @@ import {
|
|
|
16
16
|
getAnalytics,
|
|
17
17
|
getAnalyticsEventMirror,
|
|
18
18
|
} from "./analytics-singleton.js";
|
|
19
|
-
import {
|
|
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).
|
|
@@ -166,6 +179,15 @@ export async function ingestEvent(opts: {
|
|
|
166
179
|
* no mirror.
|
|
167
180
|
*/
|
|
168
181
|
eventMirror?: AnalyticsEventMirrorConfig;
|
|
182
|
+
/**
|
|
183
|
+
* PUBLISHABLE (browser, pk_) safety clamp (§Phase 1 GAP-1). Threaded into the
|
|
184
|
+
* identity resolve so an anon-only browser write cannot attach to / merge /
|
|
185
|
+
* poison an already-identified victim contact via the browser-readable
|
|
186
|
+
* `anonymousId`. Only the public-data-plane event route sets this; every
|
|
187
|
+
* server-side ingest path (webhooks, connectors, journeys) leaves it false, so
|
|
188
|
+
* their behavior is unchanged.
|
|
189
|
+
*/
|
|
190
|
+
restrictToAnonymous?: boolean;
|
|
169
191
|
}): Promise<IngestResult> {
|
|
170
192
|
const { db, registry, hatchet, logger, event, analytics, eventMirror } = opts;
|
|
171
193
|
|
|
@@ -176,20 +198,46 @@ export async function ingestEvent(opts: {
|
|
|
176
198
|
// `contacts.properties` (D2 split) and returns BOTH the canonical contact id
|
|
177
199
|
// AND its resolved string key (external_id ?? anonymous_id ?? contact.id —
|
|
178
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
|
+
}
|
|
179
234
|
const {
|
|
180
235
|
id: contactId,
|
|
181
236
|
resolvedKey,
|
|
182
237
|
mergedKeys,
|
|
183
238
|
mergedIdentifiedKeys,
|
|
184
239
|
merged,
|
|
185
|
-
} =
|
|
186
|
-
db,
|
|
187
|
-
userId: event.userId,
|
|
188
|
-
email: event.userEmail || undefined,
|
|
189
|
-
anonymousId: event.anonymousId,
|
|
190
|
-
discordId: event.discordId,
|
|
191
|
-
contactProperties: event.contactProperties,
|
|
192
|
-
});
|
|
240
|
+
} = resolved;
|
|
193
241
|
|
|
194
242
|
// Caller-supplied event time (backfill/replay). Coerced to a Date; undefined
|
|
195
243
|
// falls back to the `occurred_at` DB default (ingest instant).
|
|
@@ -317,6 +365,11 @@ export async function ingestEvent(opts: {
|
|
|
317
365
|
userId: resolvedKey,
|
|
318
366
|
userEmail: event.userEmail ?? "",
|
|
319
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,
|
|
320
373
|
}),
|
|
321
374
|
checkExits(db, registry, hatchet, logger, {
|
|
322
375
|
userId: resolvedKey,
|
|
@@ -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
|
+
}
|
|
@@ -8,6 +8,10 @@ export interface ApiKeyContext {
|
|
|
8
8
|
id: string;
|
|
9
9
|
name: string;
|
|
10
10
|
scopes: string[];
|
|
11
|
+
// Set ONLY by `requirePublishableOrIngest` for a publishable (pk_) key — the
|
|
12
|
+
// per-key browser Origin allowlist. `requireApiKey` (the secret path) never
|
|
13
|
+
// populates it, so its behavior is unchanged.
|
|
14
|
+
allowedOrigins?: string[] | null;
|
|
11
15
|
}
|
|
12
16
|
|
|
13
17
|
const SCOPE_HIERARCHY: Record<string, number> = {
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
import { apiKeys } from "@hogsend/db";
|
|
2
|
+
import { and, eq, isNull } from "drizzle-orm";
|
|
3
|
+
import { createMiddleware } from "hono/factory";
|
|
4
|
+
import type { AppEnv } from "../app.js";
|
|
5
|
+
import { hashApiKey } from "../lib/api-key-hash.js";
|
|
6
|
+
import { hasScope, requireApiKey } from "./api-key.js";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Data-plane guard for the BROWSER-REACHABLE subset of `/v1` (POST /events, the
|
|
10
|
+
* contacts upsert, GET /lists, list subscribe/unsubscribe, GET /lists/preferences).
|
|
11
|
+
*
|
|
12
|
+
* Accepts EITHER credential class:
|
|
13
|
+
*
|
|
14
|
+
* - SECRET key (anything NOT prefixed `pk_`): delegates to the UNCHANGED
|
|
15
|
+
* `requireApiKey` (legacy ADMIN_API_KEY + 60s cache + expiry), then applies
|
|
16
|
+
* the same `requireScope("ingest")` check inline. This path is
|
|
17
|
+
* byte-for-byte behaviorally identical to the existing
|
|
18
|
+
* `requireApiKey` → `requireScope("ingest")` stack.
|
|
19
|
+
*
|
|
20
|
+
* - PUBLISHABLE key (`pk_` bearer): its own UNCACHED DB lookup (the secret
|
|
21
|
+
* cache does not carry `allowed_origins`). Requires scope `ingest-public`
|
|
22
|
+
* and REJECTS any pk_ token that somehow also carries `ingest`/`full-admin`
|
|
23
|
+
* (defence in depth — a prefix never implies privilege). Enforces the
|
|
24
|
+
* per-key Origin allowlist FAIL-CLOSED (no/empty allowlist ⇒ reject; Origin
|
|
25
|
+
* not in the allowlist ⇒ reject), then sets `publishable = true`.
|
|
26
|
+
*
|
|
27
|
+
* A pk_ key therefore cannot reach any route this guard is not mounted on, and
|
|
28
|
+
* cannot pass `requireScope("ingest")` anywhere else (its `["ingest-public"]`
|
|
29
|
+
* scope is neither `ingest` nor `full-admin`).
|
|
30
|
+
*/
|
|
31
|
+
export const requirePublishableOrIngest = createMiddleware<AppEnv>(
|
|
32
|
+
async (c, next) => {
|
|
33
|
+
const header = c.req.header("authorization");
|
|
34
|
+
const provided = header?.startsWith("Bearer ")
|
|
35
|
+
? header.slice(7)
|
|
36
|
+
: undefined;
|
|
37
|
+
|
|
38
|
+
if (!provided) {
|
|
39
|
+
return c.json({ error: "Unauthorized" }, 401);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
// SECRET path: NOT a pk_ token → behave EXACTLY like the existing data-plane
|
|
43
|
+
// guard. Delegate to the unchanged `requireApiKey` (so the legacy
|
|
44
|
+
// ADMIN_API_KEY + cache + expiry logic stays in ONE place), then apply the
|
|
45
|
+
// same `requireScope("ingest")` check inline. `requireApiKey` only calls its
|
|
46
|
+
// `next` on a successful auth — if it 401s it never runs the inner check, so
|
|
47
|
+
// `authed` stays false and we return whatever response it produced.
|
|
48
|
+
if (!provided.startsWith("pk_")) {
|
|
49
|
+
let authed = false;
|
|
50
|
+
const res = await requireApiKey(c, async () => {
|
|
51
|
+
authed = true;
|
|
52
|
+
});
|
|
53
|
+
if (!authed) {
|
|
54
|
+
// requireApiKey short-circuited (401/expired) — return its response.
|
|
55
|
+
return res;
|
|
56
|
+
}
|
|
57
|
+
const apiKey = c.get("apiKey");
|
|
58
|
+
if (!apiKey || !hasScope(apiKey.scopes, "ingest")) {
|
|
59
|
+
return c.json({ error: "Forbidden: insufficient scope" }, 403);
|
|
60
|
+
}
|
|
61
|
+
return next();
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
// PUBLISHABLE path: pk_ token. Own DB lookup — `requireApiKey`'s cache does
|
|
65
|
+
// not carry `allowed_origins`, and pk_ traffic is browser-Origin-gated and
|
|
66
|
+
// lower-volume, so correctness over the 60s cache.
|
|
67
|
+
const { db } = c.get("container");
|
|
68
|
+
const keyHash = hashApiKey(provided);
|
|
69
|
+
const rows = await db
|
|
70
|
+
.select()
|
|
71
|
+
.from(apiKeys)
|
|
72
|
+
.where(and(eq(apiKeys.keyHash, keyHash), isNull(apiKeys.revokedAt)))
|
|
73
|
+
.limit(1);
|
|
74
|
+
const key = rows[0];
|
|
75
|
+
if (!key) {
|
|
76
|
+
return c.json({ error: "Unauthorized" }, 401);
|
|
77
|
+
}
|
|
78
|
+
if (key.expiresAt && key.expiresAt < new Date()) {
|
|
79
|
+
return c.json({ error: "API key expired" }, 401);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
const scopes = key.scopes as string[];
|
|
83
|
+
// A pk_ key MUST be exactly a publishable key. Reject a pk_-prefixed token
|
|
84
|
+
// that somehow carries `ingest`/`full-admin` — the mint route forces
|
|
85
|
+
// `["ingest-public"]`, but never trust the prefix alone to imply privilege.
|
|
86
|
+
if (
|
|
87
|
+
!scopes.includes("ingest-public") ||
|
|
88
|
+
scopes.includes("ingest") ||
|
|
89
|
+
scopes.includes("full-admin")
|
|
90
|
+
) {
|
|
91
|
+
return c.json({ error: "Forbidden: insufficient scope" }, 403);
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
// Per-key Origin allowlist — FAIL-CLOSED. No allowlist (null/empty), no
|
|
95
|
+
// Origin header, or an Origin not in the allowlist ⇒ reject.
|
|
96
|
+
const allowed = key.allowedOrigins ?? [];
|
|
97
|
+
const origin = c.req.header("origin");
|
|
98
|
+
if (allowed.length === 0 || !origin || !allowed.includes(origin)) {
|
|
99
|
+
return c.json({ error: "Forbidden: origin not allowed" }, 403);
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
c.set("apiKey", {
|
|
103
|
+
id: key.id,
|
|
104
|
+
name: key.name,
|
|
105
|
+
scopes,
|
|
106
|
+
allowedOrigins: allowed,
|
|
107
|
+
});
|
|
108
|
+
c.set("publishable", true);
|
|
109
|
+
|
|
110
|
+
// Best-effort last-used bump (mirror requireApiKey's fire-and-forget).
|
|
111
|
+
db.update(apiKeys)
|
|
112
|
+
.set({ lastUsedAt: new Date() })
|
|
113
|
+
.where(eq(apiKeys.id, key.id))
|
|
114
|
+
.then(() => {})
|
|
115
|
+
.catch(() => {});
|
|
116
|
+
|
|
117
|
+
return next();
|
|
118
|
+
},
|
|
119
|
+
);
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { createMiddleware } from "hono/factory";
|
|
2
2
|
import type { AppEnv } from "../app.js";
|
|
3
|
-
import { requireApiKey } from "./api-key.js";
|
|
3
|
+
import { hasScope, requireApiKey } from "./api-key.js";
|
|
4
4
|
|
|
5
5
|
// Authorizes admin routes via EITHER an API key (Bearer header, the
|
|
6
6
|
// programmatic/CLI path) OR a Better-Auth session (cookie, the Studio path).
|
|
@@ -11,7 +11,23 @@ import { requireApiKey } from "./api-key.js";
|
|
|
11
11
|
export const requireAdmin = createMiddleware<AppEnv>(async (c, next) => {
|
|
12
12
|
const header = c.req.header("authorization");
|
|
13
13
|
if (header?.startsWith("Bearer ")) {
|
|
14
|
-
|
|
14
|
+
// Authenticate the key, then REQUIRE `full-admin` scope. Without this,
|
|
15
|
+
// ANY valid non-revoked key reaches the entire admin surface — including a
|
|
16
|
+
// PUBLISHABLE (pk_/ingest-public) key embedded in browser JS, which could
|
|
17
|
+
// then mint a full-admin secret. `requireApiKey` only runs its `next` on a
|
|
18
|
+
// successful auth (else it returns 401/expired), so use a flag to surface
|
|
19
|
+
// its short-circuit response; otherwise apply the scope gate.
|
|
20
|
+
let authed = false;
|
|
21
|
+
const res = await requireApiKey(c, async () => {
|
|
22
|
+
authed = true;
|
|
23
|
+
});
|
|
24
|
+
if (!authed) return res;
|
|
25
|
+
|
|
26
|
+
const apiKey = c.get("apiKey");
|
|
27
|
+
if (!apiKey || !hasScope(apiKey.scopes, "full-admin")) {
|
|
28
|
+
return c.json({ error: "Forbidden: insufficient scope" }, 403);
|
|
29
|
+
}
|
|
30
|
+
return next();
|
|
15
31
|
}
|
|
16
32
|
|
|
17
33
|
const { auth } = c.get("container");
|
package/src/routes/_shared.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { Context } from "hono";
|
|
2
|
+
import { InvalidUserTokenError, verifyUserToken } from "../lib/user-token.js";
|
|
2
3
|
|
|
3
4
|
/**
|
|
4
5
|
* The data-plane identity guard shared by `/v1/contacts`, `/v1/events`,
|
|
@@ -21,6 +22,66 @@ export function requireIdentity(
|
|
|
21
22
|
return null;
|
|
22
23
|
}
|
|
23
24
|
|
|
25
|
+
/**
|
|
26
|
+
* The publishable-key identity gate, shared by every browser-reachable handler
|
|
27
|
+
* (events ingest, contacts upsert, list subscribe/unsubscribe).
|
|
28
|
+
*
|
|
29
|
+
* - SECRET key (`!c.get("publishable")`): defers to the UNCHANGED
|
|
30
|
+
* `requireIdentity` — identical 400 wording, identical behavior.
|
|
31
|
+
*
|
|
32
|
+
* - PUBLISHABLE key: a token-less pk_ key may act ONLY on its own anon id.
|
|
33
|
+
* - No claimed identity (`email`/`userId` both absent) → allowed (the
|
|
34
|
+
* secure anon-only default). Returns `null`.
|
|
35
|
+
* - A claimed identity REQUIRES a verified `userToken` proving the
|
|
36
|
+
* `userId`. Reject with 403 when: no `userToken`; `email` is asserted
|
|
37
|
+
* (no email arm exists in v1 — a token only binds a userId); or the
|
|
38
|
+
* token's `userId` does not match the claimed `userId`.
|
|
39
|
+
*
|
|
40
|
+
* Returns a `Response` to `return`, or `null` to proceed.
|
|
41
|
+
*/
|
|
42
|
+
export function gatePublishableIdentity(
|
|
43
|
+
c: Context,
|
|
44
|
+
body: { email?: string; userId?: string; userToken?: string },
|
|
45
|
+
secret: string,
|
|
46
|
+
opts?: { field?: "email" | "to" },
|
|
47
|
+
) {
|
|
48
|
+
if (!c.get("publishable")) {
|
|
49
|
+
return requireIdentity(c, body, opts);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
// Publishable. No claimed identity → anon-only, allowed (the secure default).
|
|
53
|
+
if (!body.email && !body.userId) return null;
|
|
54
|
+
|
|
55
|
+
// Claimed identity REQUIRES a verified userToken binding the userId.
|
|
56
|
+
if (!body.userToken) {
|
|
57
|
+
return c.json(
|
|
58
|
+
{
|
|
59
|
+
error:
|
|
60
|
+
"publishable key cannot act on another identity without a userToken",
|
|
61
|
+
},
|
|
62
|
+
403,
|
|
63
|
+
);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
try {
|
|
67
|
+
const payload = verifyUserToken({ token: body.userToken, secret });
|
|
68
|
+
// A token binds ONLY a userId (v1 has no email arm). Reject any asserted
|
|
69
|
+
// email, and require the claimed userId to match the token's userId.
|
|
70
|
+
if (body.email || (body.userId && body.userId !== payload.userId)) {
|
|
71
|
+
return c.json(
|
|
72
|
+
{ error: "userToken does not authorize this identity" },
|
|
73
|
+
403,
|
|
74
|
+
);
|
|
75
|
+
}
|
|
76
|
+
return null;
|
|
77
|
+
} catch (err) {
|
|
78
|
+
if (err instanceof InvalidUserTokenError) {
|
|
79
|
+
return c.json({ error: "Invalid userToken" }, 403);
|
|
80
|
+
}
|
|
81
|
+
throw err;
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
|
|
24
85
|
/**
|
|
25
86
|
* Extract a human-readable message from an `applyListMembership` failure,
|
|
26
87
|
* matching the wording every data-plane route used inline.
|