@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.
@@ -10,6 +10,9 @@ const apiKeySchema = z.object({
10
10
  name: z.string(),
11
11
  keyPrefix: z.string(),
12
12
  scopes: z.array(z.string()),
13
+ // Per-key browser Origin allowlist for publishable (pk_) keys; null for
14
+ // secret keys.
15
+ allowedOrigins: z.array(z.string()).nullable(),
13
16
  createdBy: z.string().nullable(),
14
17
  lastUsedAt: z.string().nullable(),
15
18
  revokedAt: z.string().nullable(),
@@ -55,14 +58,35 @@ const createKeyRoute = createRoute({
55
58
  body: {
56
59
  content: {
57
60
  "application/json": {
58
- schema: z.object({
59
- name: z.string().min(1).max(100),
60
- scopes: z
61
- .array(z.enum(["read", "journey-admin", "full-admin", "ingest"]))
62
- .min(1)
63
- .default(["read"]),
64
- expiresAt: z.string().datetime().optional(),
65
- }),
61
+ schema: z
62
+ .object({
63
+ name: z.string().min(1).max(100),
64
+ scopes: z
65
+ .array(
66
+ z.enum([
67
+ "read",
68
+ "journey-admin",
69
+ "full-admin",
70
+ "ingest",
71
+ "ingest-public",
72
+ ]),
73
+ )
74
+ .min(1)
75
+ .default(["read"]),
76
+ expiresAt: z.string().datetime().optional(),
77
+ // Mint a PUBLISHABLE (pk_) browser key: forces scope
78
+ // `["ingest-public"]` and requires a non-empty `allowedOrigins`.
79
+ publishable: z.boolean().optional().default(false),
80
+ allowedOrigins: z.array(z.string().url()).optional(),
81
+ })
82
+ .refine(
83
+ (b) => !b.publishable || (b.allowedOrigins?.length ?? 0) > 0,
84
+ {
85
+ message:
86
+ "publishable keys require at least one allowedOrigins entry",
87
+ path: ["allowedOrigins"],
88
+ },
89
+ ),
66
90
  },
67
91
  },
68
92
  },
@@ -77,6 +101,7 @@ const createKeyRoute = createRoute({
77
101
  key: z.string(),
78
102
  keyPrefix: z.string(),
79
103
  scopes: z.array(z.string()),
104
+ allowedOrigins: z.array(z.string()).nullable(),
80
105
  expiresAt: z.string().nullable(),
81
106
  createdAt: z.string(),
82
107
  }),
@@ -117,6 +142,7 @@ function serializeKey(row: typeof apiKeys.$inferSelect) {
117
142
  name: row.name,
118
143
  keyPrefix: row.keyPrefix,
119
144
  scopes: row.scopes as string[],
145
+ allowedOrigins: row.allowedOrigins ?? null,
120
146
  createdBy: row.createdBy,
121
147
  lastUsedAt: row.lastUsedAt?.toISOString() ?? null,
122
148
  revokedAt: row.revokedAt?.toISOString() ?? null,
@@ -159,7 +185,15 @@ export const apiKeysRouter = new OpenAPIHono<AppEnv>()
159
185
  const body = c.req.valid("json");
160
186
  const actor = c.get("apiKey");
161
187
 
162
- const { key, prefix, hash } = generateApiKey();
188
+ const { key, prefix, hash } = generateApiKey({
189
+ publishable: body.publishable,
190
+ });
191
+
192
+ // A publishable (pk_) key is FORCED to exactly `["ingest-public"]` —
193
+ // regardless of any submitted `scopes` — so it can never carry
194
+ // `ingest`/`full-admin` (non-negotiable: no escalation). Secret keys keep
195
+ // their submitted scopes and a null allowlist (path untouched).
196
+ const scopes = body.publishable ? ["ingest-public"] : body.scopes;
163
197
 
164
198
  const [created] = await db
165
199
  .insert(apiKeys)
@@ -167,7 +201,8 @@ export const apiKeysRouter = new OpenAPIHono<AppEnv>()
167
201
  name: body.name,
168
202
  keyPrefix: prefix,
169
203
  keyHash: hash,
170
- scopes: body.scopes,
204
+ scopes,
205
+ allowedOrigins: body.publishable ? (body.allowedOrigins ?? null) : null,
171
206
  createdBy: actor?.name ?? null,
172
207
  expiresAt: body.expiresAt ? new Date(body.expiresAt) : null,
173
208
  })
@@ -182,6 +217,7 @@ export const apiKeysRouter = new OpenAPIHono<AppEnv>()
182
217
  key,
183
218
  keyPrefix: prefix,
184
219
  scopes: created.scopes as string[],
220
+ allowedOrigins: created.allowedOrigins ?? null,
185
221
  expiresAt: created.expiresAt?.toISOString() ?? null,
186
222
  createdAt: created.createdAt.toISOString(),
187
223
  },
@@ -2,6 +2,7 @@ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
2
  import type { AppEnv } from "../../app.js";
3
3
  import {
4
4
  findContacts,
5
+ PublishableAnonymousMergeError,
5
6
  resolveContact,
6
7
  resolveOrCreateContact,
7
8
  serializeContact,
@@ -10,7 +11,11 @@ import {
10
11
  import { emitOutbound } from "../../lib/outbound.js";
11
12
  import { applyListMembership } from "../../lib/preferences.js";
12
13
  import { errorSchema } from "../../lib/schemas.js";
13
- import { listMembershipError, requireIdentity } from "../_shared.js";
14
+ import {
15
+ gatePublishableIdentity,
16
+ listMembershipError,
17
+ requireIdentity,
18
+ } from "../_shared.js";
14
19
 
15
20
  // The public, serialized contact shape (§2.5). `externalId` is nullable (D1 —
16
21
  // email-only / anonymous contacts) and timestamps are ISO strings.
@@ -45,6 +50,9 @@ const upsertRoute = createRoute({
45
50
  anonymousId: z.string().min(1).max(200).optional(),
46
51
  properties: z.record(z.string(), z.unknown()).optional(),
47
52
  lists: z.record(z.string(), z.boolean()).optional(),
53
+ // Publishable-key identity assertion (§Phase 1). Ignored on the
54
+ // secret-key path.
55
+ userToken: z.string().optional(),
48
56
  }),
49
57
  },
50
58
  },
@@ -67,6 +75,11 @@ const upsertRoute = createRoute({
67
75
  content: { "application/json": { schema: errorSchema } },
68
76
  description: "Missing recipient or unmanageable list membership",
69
77
  },
78
+ 403: {
79
+ content: { "application/json": { schema: errorSchema } },
80
+ description:
81
+ "Publishable key attempted to act on another identity without a verified userToken",
82
+ },
70
83
  },
71
84
  });
72
85
 
@@ -136,21 +149,34 @@ const deleteRoute = createRoute({
136
149
 
137
150
  export const contactsRouter = new OpenAPIHono<AppEnv>()
138
151
  .openapi(upsertRoute, async (c) => {
139
- const { db, hatchet, logger } = c.get("container");
152
+ const { db, hatchet, logger, env } = c.get("container");
140
153
  const body = c.req.valid("json");
141
154
 
142
- const guard = requireIdentity(c, body);
155
+ const guard = gatePublishableIdentity(c, body, env.BETTER_AUTH_SECRET);
143
156
  if (guard) return guard;
144
157
 
145
- const { id, created, linked, merged } = await resolveOrCreateContact({
146
- db,
147
- userId: body.userId,
148
- email: body.email,
149
- // §4: 2nd-precedence resolver key (zero-merge stitch). Identity is still
150
- // enforced via `requireIdentity` (email/userId) above.
151
- anonymousId: body.anonymousId,
152
- contactProperties: body.properties,
153
- });
158
+ let resolved: Awaited<ReturnType<typeof resolveOrCreateContact>>;
159
+ try {
160
+ resolved = await resolveOrCreateContact({
161
+ db,
162
+ userId: body.userId,
163
+ email: body.email,
164
+ // §4: 2nd-precedence resolver key (zero-merge stitch).
165
+ anonymousId: body.anonymousId,
166
+ contactProperties: body.properties,
167
+ // §Phase 1 GAP-1: a publishable (pk_) browser upsert is anon-clamped —
168
+ // its browser-readable `anonymousId` may NOT attach to / merge / poison
169
+ // an already-identified victim contact. Secret-key upserts are never
170
+ // clamped.
171
+ restrictToAnonymous: c.get("publishable") === true,
172
+ });
173
+ } catch (err) {
174
+ if (err instanceof PublishableAnonymousMergeError) {
175
+ return c.json({ error: err.message }, 403);
176
+ }
177
+ throw err;
178
+ }
179
+ const { id, created, linked, merged } = resolved;
154
180
 
155
181
  // INTENT-LAYER outbound emit (decision #3): fire `contact.created` on a real
156
182
  // creation, `contact.updated` only when an existing contact was linked/merged
@@ -1,9 +1,10 @@
1
1
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
2
  import type { AppEnv } from "../../app.js";
3
+ import { PublishableAnonymousMergeError } from "../../lib/contacts.js";
3
4
  import { ingestEvent } from "../../lib/ingestion.js";
4
5
  import { applyListMembership } from "../../lib/preferences.js";
5
6
  import { errorSchema } from "../../lib/schemas.js";
6
- import { listMembershipError, requireIdentity } from "../_shared.js";
7
+ import { gatePublishableIdentity, listMembershipError } from "../_shared.js";
7
8
 
8
9
  const eventRequestSchema = z.object({
9
10
  name: z.string().min(1),
@@ -22,6 +23,10 @@ const eventRequestSchema = z.object({
22
23
  lists: z.record(z.string(), z.boolean()).optional(),
23
24
  idempotencyKey: z.string().optional(),
24
25
  timestamp: z.string().datetime().optional(),
26
+ // Publishable-key identity assertion (§Phase 1). A pk_ key is anon-only
27
+ // unless it presents a server-minted `userToken` proving the claimed `userId`.
28
+ // Ignored on the secret-key path (which uses `requireIdentity`).
29
+ userToken: z.string().optional(),
25
30
  });
26
31
 
27
32
  const eventResponseSchema = z.object({
@@ -70,48 +75,72 @@ const eventRoute = createRoute({
70
75
  content: { "application/json": { schema: errorSchema } },
71
76
  description: "Missing recipient or unmanageable list membership",
72
77
  },
78
+ 403: {
79
+ content: { "application/json": { schema: errorSchema } },
80
+ description:
81
+ "Publishable key attempted to act on another identity without a verified userToken",
82
+ },
73
83
  },
74
84
  });
75
85
 
76
86
  export const eventsRouter = new OpenAPIHono<AppEnv>().openapi(
77
87
  eventRoute,
78
88
  async (c) => {
79
- const { db, registry, hatchet, logger, analytics } = c.get("container");
89
+ const { db, registry, hatchet, logger, analytics, env } =
90
+ c.get("container");
80
91
  const body = c.req.valid("json");
81
92
 
82
- const guard = requireIdentity(c, body);
93
+ const guard = gatePublishableIdentity(c, body, env.BETTER_AUTH_SECRET);
83
94
  if (guard) return guard;
84
95
 
85
96
  // The `Idempotency-Key` header wins over the body field (§2.5).
86
97
  const headerKey = c.req.header("idempotency-key");
87
98
  const idempotencyKey = headerKey ?? body.idempotencyKey;
88
99
 
89
- const result = await ingestEvent({
90
- db,
91
- registry,
92
- hatchet,
93
- logger,
94
- // §5.3: thread the active analytics provider so a collide-MERGE / key-flip
95
- // fires the provider-neutral `mergeIdentities` stitch. Absent ⇒ no-op.
96
- analytics,
97
- event: {
98
- event: body.name,
99
- userId: body.userId,
100
- userEmail: body.email,
101
- // §4: 2nd-precedence resolver key — lets the contact's canonical key
102
- // equal the browser anon id (zero-merge stitch). Identity is still
103
- // enforced via `requireIdentity` (email/userId) above.
104
- anonymousId: body.anonymousId,
105
- eventProperties: body.eventProperties ?? {},
106
- contactProperties: body.contactProperties,
107
- idempotencyKey,
108
- // §2.5: caller-supplied event time (backfill/replay). The validated ISO
109
- // string is coerced to a Date inside ingestEvent.
110
- occurredAt: body.timestamp,
111
- // Public data-plane ingest (the `@hogsend/client` SDK / your app code).
112
- source: "api",
113
- },
114
- });
100
+ let result: Awaited<ReturnType<typeof ingestEvent>>;
101
+ try {
102
+ result = await ingestEvent({
103
+ db,
104
+ registry,
105
+ hatchet,
106
+ logger,
107
+ // §5.3: thread the active analytics provider so a collide-MERGE /
108
+ // key-flip fires the provider-neutral `mergeIdentities` stitch.
109
+ analytics,
110
+ // §Phase 1 GAP-1: a publishable (pk_) browser write is anon-clamped —
111
+ // its browser-readable `anonymousId` may NOT attach to / merge / poison
112
+ // an already-identified victim contact. Secret-key ingest is never
113
+ // clamped.
114
+ restrictToAnonymous: c.get("publishable") === true,
115
+ event: {
116
+ event: body.name,
117
+ userId: body.userId,
118
+ userEmail: body.email,
119
+ // §4: 2nd-precedence resolver key — lets the contact's canonical key
120
+ // equal the browser anon id (zero-merge stitch).
121
+ anonymousId: body.anonymousId,
122
+ eventProperties: body.eventProperties ?? {},
123
+ contactProperties: body.contactProperties,
124
+ idempotencyKey,
125
+ // §2.5: caller-supplied event time (backfill/replay). The validated
126
+ // ISO string is coerced to a Date inside ingestEvent.
127
+ occurredAt: body.timestamp,
128
+ // Provenance derived from the authenticated key CLASS, never the
129
+ // request body (so it can't be spoofed): a publishable (pk_) key is
130
+ // always an in-app surface interaction from @hogsend/js; a secret key
131
+ // is the server-side data plane. "inapp" still fans out to PostHog
132
+ // (the loop-guard only special-cases "posthog").
133
+ source: c.get("publishable") === true ? "inapp" : "api",
134
+ },
135
+ });
136
+ } catch (err) {
137
+ // A publishable anon write that resolved to an identified victim contact
138
+ // (or would drive a merge) is rejected at the resolver — surface as 403.
139
+ if (err instanceof PublishableAnonymousMergeError) {
140
+ return c.json({ error: err.message }, 403);
141
+ }
142
+ throw err;
143
+ }
115
144
 
116
145
  // Lists applied AFTER ingest so the contact exists (§2.5 lists ordering).
117
146
  // `applyListMembership` writes `email_preferences` independently of the
@@ -123,7 +152,18 @@ export const eventsRouter = new OpenAPIHono<AppEnv>().openapi(
123
152
  // status and (b) tempt a client to retry, re-ingesting the event. Surface it
124
153
  // as a `listsError` warning on the 202 instead.
125
154
  let listsError: string | undefined;
126
- if (body.lists && Object.keys(body.lists).length > 0) {
155
+ // §Phase 1 GAP-2 (defense in depth): a publishable caller reaching here has
156
+ // no token-less email/userId (the gate 403'd it) — but assert it explicitly
157
+ // so a future change that lets `anonymousId` carry a list write can't
158
+ // silently write `email_preferences` for a victim. `applyListMembership`
159
+ // needs a resolvable email anyway; a publishable list write is a no-op.
160
+ const publishableListWrite =
161
+ c.get("publishable") === true && (body.email || body.userId);
162
+ if (
163
+ !publishableListWrite &&
164
+ body.lists &&
165
+ Object.keys(body.lists).length > 0
166
+ ) {
127
167
  try {
128
168
  await applyListMembership({
129
169
  db,