@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
|
@@ -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
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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
|
|
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 {
|
|
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 =
|
|
155
|
+
const guard = gatePublishableIdentity(c, body, env.BETTER_AUTH_SECRET);
|
|
143
156
|
if (guard) return guard;
|
|
144
157
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
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 {
|
|
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 } =
|
|
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 =
|
|
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
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
//
|
|
102
|
-
//
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
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
|
-
|
|
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,
|