@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.
@@ -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
+ }
@@ -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).
@@ -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
- } = await resolveOrCreateContact({
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
- return requireApiKey(c, next);
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");
@@ -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.