@pithy-sh/email 0.9.0 → 0.10.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/dist/crypto/signingKey.d.ts.map +1 -1
- package/dist/crypto/token.d.ts +43 -11
- package/dist/crypto/token.d.ts.map +1 -1
- package/dist/crypto/token.js +158 -55
- package/dist/http/callbacks.d.ts +8 -3
- package/dist/http/callbacks.d.ts.map +1 -1
- package/dist/http/callbacks.js +67 -12
- package/dist/http/guards.d.ts.map +1 -1
- package/dist/http/guards.js +9 -0
- package/dist/http/routes.d.ts +8 -4
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +61 -21
- package/dist/http/schemas.d.ts +32 -13
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +33 -13
- package/dist/templates/engine.d.ts +1 -1
- package/dist/templates/engine.js +1 -1
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.d.ts.map +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +3 -3
- package/src/crypto/signingKey.ts +4 -2
- package/src/crypto/token.ts +225 -92
- package/src/http/callbacks.ts +100 -32
- package/src/http/guards.ts +9 -0
- package/src/http/routes.ts +93 -28
- package/src/http/schemas.ts +54 -22
- package/src/templates/engine.ts +1 -1
- package/src/version.generated.ts +1 -1
package/src/http/routes.ts
CHANGED
|
@@ -41,7 +41,14 @@ import {
|
|
|
41
41
|
EmailSuppressResponse,
|
|
42
42
|
EmailUnsuppressResponse,
|
|
43
43
|
} from "./responses";
|
|
44
|
-
import {
|
|
44
|
+
import {
|
|
45
|
+
JobIdParam,
|
|
46
|
+
JobsQuery,
|
|
47
|
+
SuppressionLookupRequest,
|
|
48
|
+
SuppressionsQuery,
|
|
49
|
+
SuppressRequest,
|
|
50
|
+
UnsuppressRequest,
|
|
51
|
+
} from "./schemas";
|
|
45
52
|
import { jobDetailView, jobListView, suppressionView } from "./view";
|
|
46
53
|
|
|
47
54
|
/**
|
|
@@ -51,6 +58,7 @@ import { jobDetailView, jobListView, suppressionView } from "./view";
|
|
|
51
58
|
* GET /email/jobs/:id → one job in full (control-plane: email:jobs:read) param
|
|
52
59
|
* POST /email/jobs/:id/retry → queue it again (control-plane: email:jobs:retry) param
|
|
53
60
|
* GET /email/suppressions → who we won't mail (control-plane: email:suppressions:read) query
|
|
61
|
+
* POST /email/suppressions/lookup → is this one blocked (control-plane: email:suppressions:read) json
|
|
54
62
|
* POST /email/suppressions → block an address (control-plane: email:suppressions:write) json
|
|
55
63
|
* POST /email/suppressions/remove → unblock one (control-plane: email:suppressions:delete) json
|
|
56
64
|
*
|
|
@@ -71,10 +79,13 @@ import { jobDetailView, jobListView, suppressionView } from "./view";
|
|
|
71
79
|
* parsing every response would spend a validation pass on rows this Worker just read, and would turn a
|
|
72
80
|
* shape mistake into a 500 in production rather than a red build.
|
|
73
81
|
*
|
|
74
|
-
* **
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
82
|
+
* **An address never travels in a URL.** Removal is `POST /suppressions/remove`, not
|
|
83
|
+
* `DELETE /suppressions/:email`, and a lookup is `POST /suppressions/lookup`, not `?email=`. A path or a
|
|
84
|
+
* query string is in every access log, every proxy, every trace, and every referrer between the client
|
|
85
|
+
* and the Worker. The record is personal data whether or not it is a person's current address, so it
|
|
86
|
+
* travels in a body. Testers' `POST /remove` is the same call made for the same reason, and
|
|
87
|
+
* `addressedParameters` in `@pithy-sh/core/src/openapi/document` fails the kit's build on a route that
|
|
88
|
+
* declares one in its URL.
|
|
78
89
|
*/
|
|
79
90
|
|
|
80
91
|
/** What every route this capability mounts declares: its path, its strategy, and the scope it checks. */
|
|
@@ -100,6 +111,12 @@ export const EMAIL_ADMIN_ROUTES: readonly EmailRouteDeclaration[] = [
|
|
|
100
111
|
{ method: "GET", path: "/jobs/:id", strategy: "control-plane", scope: EMAIL_JOBS_READ_SCOPE },
|
|
101
112
|
{ method: "POST", path: "/jobs/:id/retry", strategy: "control-plane", scope: EMAIL_JOBS_RETRY_SCOPE },
|
|
102
113
|
{ method: "GET", path: "/suppressions", strategy: "control-plane", scope: EMAIL_SUPPRESSIONS_READ_SCOPE },
|
|
114
|
+
{
|
|
115
|
+
method: "POST",
|
|
116
|
+
path: "/suppressions/lookup",
|
|
117
|
+
strategy: "control-plane",
|
|
118
|
+
scope: EMAIL_SUPPRESSIONS_READ_SCOPE,
|
|
119
|
+
},
|
|
103
120
|
{ method: "POST", path: "/suppressions", strategy: "control-plane", scope: EMAIL_SUPPRESSIONS_WRITE_SCOPE },
|
|
104
121
|
{
|
|
105
122
|
method: "POST",
|
|
@@ -182,6 +199,33 @@ function caller(c: Context<PithyHonoEnv>): ControlPlaneContext {
|
|
|
182
199
|
return context;
|
|
183
200
|
}
|
|
184
201
|
|
|
202
|
+
/** What one read of the suppression list records about itself. The rows never go in. */
|
|
203
|
+
interface SuppressionsReadMetadata {
|
|
204
|
+
reason: string | null;
|
|
205
|
+
lookup: boolean;
|
|
206
|
+
active: boolean | null;
|
|
207
|
+
returned: number;
|
|
208
|
+
paged: boolean;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* Audit a read of the suppression list. The heaviest read in the capability: this database is global, so
|
|
213
|
+
* a page of it is a page of every environment's bounces, complaints, and opt-outs. Audited with whether
|
|
214
|
+
* it was a lookup or a walk, because those are very different events.
|
|
215
|
+
*/
|
|
216
|
+
async function auditSuppressionsRead(c: Context<PithyHonoEnv>, metadata: SuppressionsReadMetadata): Promise<void> {
|
|
217
|
+
const who = caller(c);
|
|
218
|
+
await c.var.emit({
|
|
219
|
+
action: EmailAuditActions.suppressionsRead,
|
|
220
|
+
outcome: "success",
|
|
221
|
+
actorType: "control-plane",
|
|
222
|
+
actorId: who.subject,
|
|
223
|
+
resourceType: "email_suppression",
|
|
224
|
+
resourceId: null,
|
|
225
|
+
metadata: { connectionId: who.connectionId, ...metadata },
|
|
226
|
+
});
|
|
227
|
+
}
|
|
228
|
+
|
|
185
229
|
/** Register the email management sub-router. Composed alongside the public callbacks. */
|
|
186
230
|
export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
|
|
187
231
|
const base = options.basePath;
|
|
@@ -320,7 +364,7 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
|
|
|
320
364
|
app.get(
|
|
321
365
|
`${base}/suppressions`,
|
|
322
366
|
describeRoute({
|
|
323
|
-
summary: "Page through the suppression list
|
|
367
|
+
summary: "Page through the suppression list.",
|
|
324
368
|
verification: "control-plane",
|
|
325
369
|
scopes: [EMAIL_SUPPRESSIONS_READ_SCOPE],
|
|
326
370
|
responses: { 200: EmailSuppressionsResponse },
|
|
@@ -329,28 +373,49 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
|
|
|
329
373
|
validate("query", SuppressionsQuery),
|
|
330
374
|
async (c) => {
|
|
331
375
|
const query = c.req.valid("query");
|
|
332
|
-
const who = caller(c);
|
|
333
376
|
const now = clock();
|
|
334
377
|
const page = await listSuppressions(suppressions(c), { ...query, now });
|
|
335
378
|
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
379
|
+
await auditSuppressionsRead(c, {
|
|
380
|
+
reason: query.reason ?? null,
|
|
381
|
+
lookup: false,
|
|
382
|
+
active: query.active ?? null,
|
|
383
|
+
returned: page.items.length,
|
|
384
|
+
paged: Boolean(query.cursor),
|
|
385
|
+
});
|
|
386
|
+
|
|
387
|
+
return c.json({
|
|
388
|
+
suppressions: page.items.map((row) => suppressionView(row, now)),
|
|
389
|
+
nextCursor: page.nextCursor,
|
|
390
|
+
} satisfies EmailSuppressionsResponse);
|
|
391
|
+
},
|
|
392
|
+
);
|
|
393
|
+
|
|
394
|
+
app.post(
|
|
395
|
+
`${base}/suppressions/lookup`,
|
|
396
|
+
describeRoute({
|
|
397
|
+
summary: "Look one address up on the suppression list.",
|
|
398
|
+
verification: "control-plane",
|
|
399
|
+
scopes: [EMAIL_SUPPRESSIONS_READ_SCOPE],
|
|
400
|
+
responses: { 200: EmailSuppressionsResponse },
|
|
401
|
+
}),
|
|
402
|
+
requireControlPlane(EMAIL_SUPPRESSIONS_READ_SCOPE),
|
|
403
|
+
validate("json", SuppressionLookupRequest),
|
|
404
|
+
async (c) => {
|
|
405
|
+
const input = c.req.valid("json");
|
|
406
|
+
const now = clock();
|
|
407
|
+
// `listSuppressions` matches the normalized key exactly, and `email` is unique, so this is the
|
|
408
|
+
// row or none: the listing's envelope, so a client renders it with the schema it already holds.
|
|
409
|
+
const page = await listSuppressions(suppressions(c), { email: input.email, now });
|
|
410
|
+
|
|
411
|
+
// The address stays out of the trail: the event records that one address was asked about and
|
|
412
|
+
// whether it was found, as the listing's lookup always did.
|
|
413
|
+
await auditSuppressionsRead(c, {
|
|
414
|
+
reason: null,
|
|
415
|
+
lookup: true,
|
|
416
|
+
active: null,
|
|
417
|
+
returned: page.items.length,
|
|
418
|
+
paged: false,
|
|
354
419
|
});
|
|
355
420
|
|
|
356
421
|
return c.json({
|
|
@@ -396,17 +461,17 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
|
|
|
396
461
|
message: "That expiry has already passed, so it would not block anything.",
|
|
397
462
|
action:
|
|
398
463
|
"Give a future instant, or omit `expiresAt` to block permanently. To lift an existing block, use the remove route — it requires `email:suppressions:delete`.",
|
|
399
|
-
detail: `refused suppression
|
|
464
|
+
detail: `refused suppression with expiresAt ${expiresAt.toISOString()} at ${now.toISOString()}`,
|
|
400
465
|
});
|
|
401
466
|
}
|
|
402
467
|
|
|
403
468
|
const current = (await listSuppressions(db, { email, limit: 1 })).items[0];
|
|
404
469
|
if (current && current.reason !== "manual") {
|
|
405
470
|
throw new ConflictError({
|
|
406
|
-
message:
|
|
471
|
+
message: `That address is already suppressed as a ${current.reason}, which this route may not overwrite.`,
|
|
407
472
|
action:
|
|
408
473
|
"Lift it with the remove route, which requires `email:suppressions:delete` — undoing a bounce, a complaint, or someone's own opt-out is a separate decision.",
|
|
409
|
-
detail: `refused manual suppression over an existing ${current.reason}
|
|
474
|
+
detail: `refused manual suppression over an existing ${current.reason}`,
|
|
410
475
|
});
|
|
411
476
|
}
|
|
412
477
|
|
package/src/http/schemas.ts
CHANGED
|
@@ -22,7 +22,7 @@ import { EmailJobStatus, SuppressionReason, TemplateCategory } from "../data/enu
|
|
|
22
22
|
|
|
23
23
|
/**
|
|
24
24
|
* The characters a callback token path segment may contain: the base64url alphabet, plus `.` — the
|
|
25
|
-
* token's own
|
|
25
|
+
* token's own segment separator, and the `.png` suffix mail clients append to an
|
|
26
26
|
* open-pixel URL (which `handleOpen` strips before verifying). Deliberately not a strict base64url
|
|
27
27
|
* check: that would 400 every tracking pixel.
|
|
28
28
|
*/
|
|
@@ -30,7 +30,7 @@ const TOKEN_SEGMENT = /^[A-Za-z0-9._-]+$/;
|
|
|
30
30
|
|
|
31
31
|
/**
|
|
32
32
|
* The `:token` path parameter every callback route carries. A shape and size bound only — the ceiling
|
|
33
|
-
* is generous enough for a click token whose
|
|
33
|
+
* is generous enough for a click token whose sealed claims embed a long destination URL, so no link we
|
|
34
34
|
* mint can exceed it, while an unbounded segment can no longer reach the verifier.
|
|
35
35
|
*/
|
|
36
36
|
export const CallbackTokenParam = z
|
|
@@ -40,26 +40,40 @@ export const CallbackTokenParam = z
|
|
|
40
40
|
.min(1)
|
|
41
41
|
.max(4096)
|
|
42
42
|
.regex(TOKEN_SEGMENT)
|
|
43
|
-
.describe("The
|
|
43
|
+
.describe("The sealed callback token from the path, optionally with the open-pixel `.png` suffix."),
|
|
44
44
|
})
|
|
45
45
|
.describe("The path parameter carrying a click/open/unsubscribe callback token.");
|
|
46
46
|
export type CallbackTokenParam = z.output<typeof CallbackTokenParam>;
|
|
47
47
|
|
|
48
|
+
/** One form field as a client may send it: a value, or a repeated field's values. Anything else reads as absent. */
|
|
49
|
+
const FormField = z
|
|
50
|
+
.union([z.string(), z.array(z.string())])
|
|
51
|
+
.optional()
|
|
52
|
+
.catch(undefined);
|
|
53
|
+
|
|
48
54
|
/**
|
|
49
|
-
* The
|
|
50
|
-
*
|
|
51
|
-
*
|
|
55
|
+
* The form body of an unsubscribe `POST`: what a mail client's one-click unsubscribe sends (RFC 8058 fixes it to
|
|
56
|
+
* `List-Unsubscribe=One-Click`), what the confirmation page's button sends, and what the app's own preferences flow
|
|
57
|
+
* sends with a `reason`.
|
|
58
|
+
*
|
|
59
|
+
* **Nothing in it can refuse the opt-out.** Every field is optional, a repeated field or one of the wrong type reads
|
|
60
|
+
* as absent or as its first value, and an over-long reason is truncated by the handler rather than refused. The
|
|
61
|
+
* token is the only gate; a body is never a reason somebody stays subscribed.
|
|
62
|
+
*
|
|
63
|
+
* The reason travels in the body because it is the recipient's own words, and a query string is written to every
|
|
64
|
+
* request log between the client and the Worker. The route reads no query at all.
|
|
52
65
|
*/
|
|
53
|
-
export const
|
|
66
|
+
export const UnsubscribeForm = z
|
|
54
67
|
.object({
|
|
55
|
-
|
|
56
|
-
.
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
68
|
+
"List-Unsubscribe": FormField.describe(
|
|
69
|
+
"`One-Click` from a mail client's RFC 8058 one-click unsubscribe. Accepted and not otherwise read.",
|
|
70
|
+
),
|
|
71
|
+
reason: FormField.describe(
|
|
72
|
+
"Why the recipient opted out; the first value is kept, truncated to 200 characters before it is stored.",
|
|
73
|
+
),
|
|
60
74
|
})
|
|
61
|
-
.describe("The optional
|
|
62
|
-
export type
|
|
75
|
+
.describe("The optional form fields an unsubscribe POST accepts.");
|
|
76
|
+
export type UnsubscribeForm = z.output<typeof UnsubscribeForm>;
|
|
63
77
|
|
|
64
78
|
/**
|
|
65
79
|
* Where the next page starts. Opaque, and a malformed one is a first page rather than a 400 — the
|
|
@@ -157,19 +171,16 @@ export type JobsQuery = z.output<typeof JobsQuery>;
|
|
|
157
171
|
/**
|
|
158
172
|
* The suppression list query.
|
|
159
173
|
*
|
|
160
|
-
*
|
|
161
|
-
*
|
|
162
|
-
*
|
|
163
|
-
*
|
|
174
|
+
* **No address, and an unknown key is refused.** A query string is written to every request log between
|
|
175
|
+
* the client and the Worker, so looking one address up is {@link SuppressionLookupRequest}, a `POST`
|
|
176
|
+
* with the address in its body. Strict rather than stripping, so a client still sending `?email=` is
|
|
177
|
+
* told so with a 400 instead of being handed the whole list as though it were the match.
|
|
164
178
|
*/
|
|
165
179
|
export const SuppressionsQuery = z
|
|
166
180
|
.object({
|
|
167
181
|
reason: SuppressionReason.optional().describe(
|
|
168
182
|
"Filter to one reason — hard bounce, complaint, unsubscribe, manual.",
|
|
169
183
|
),
|
|
170
|
-
email: AddressFilter.optional().describe(
|
|
171
|
-
"Look one address up, exactly. Answers `is this person blocked` without disclosing anybody else.",
|
|
172
|
-
),
|
|
173
184
|
active: z
|
|
174
185
|
.enum(["true", "false"])
|
|
175
186
|
.describe("`true` or `false`.")
|
|
@@ -181,7 +192,10 @@ export const SuppressionsQuery = z
|
|
|
181
192
|
cursor: Cursor,
|
|
182
193
|
limit: Limit,
|
|
183
194
|
})
|
|
184
|
-
.
|
|
195
|
+
.strict()
|
|
196
|
+
.describe(
|
|
197
|
+
"The suppression-list query: what to filter by and where to resume. To look one address up, POST it to `/suppressions/lookup`.",
|
|
198
|
+
);
|
|
185
199
|
export type SuppressionsQuery = z.output<typeof SuppressionsQuery>;
|
|
186
200
|
|
|
187
201
|
/**
|
|
@@ -213,6 +227,24 @@ export const SuppressRequest = z
|
|
|
213
227
|
.describe("Add one address to the global suppression list, as a manual block.");
|
|
214
228
|
export type SuppressRequest = z.output<typeof SuppressRequest>;
|
|
215
229
|
|
|
230
|
+
/**
|
|
231
|
+
* Look one address up.
|
|
232
|
+
*
|
|
233
|
+
* An exact match rather than a search, and that is the point: answering "is this one address blocked"
|
|
234
|
+
* should not require paging a list of every other person who ever unsubscribed, and a prefix or substring
|
|
235
|
+
* search would enumerate the list a page at a time while looking like a lookup. A body because a query
|
|
236
|
+
* string is written to every request log between the client and the Worker.
|
|
237
|
+
*/
|
|
238
|
+
export const SuppressionLookupRequest = z
|
|
239
|
+
.object({
|
|
240
|
+
email: AddressFilter.describe(
|
|
241
|
+
"The address to look up, matched exactly against the stored key. Answers `is this person blocked` without disclosing anybody else.",
|
|
242
|
+
),
|
|
243
|
+
})
|
|
244
|
+
.strict()
|
|
245
|
+
.describe("Look one address up on the global suppression list.");
|
|
246
|
+
export type SuppressionLookupRequest = z.output<typeof SuppressionLookupRequest>;
|
|
247
|
+
|
|
216
248
|
/** Unblock an address — the undo of {@link SuppressRequest}, and of a bounce, complaint, or opt-out. */
|
|
217
249
|
export const UnsuppressRequest = z
|
|
218
250
|
.object({
|
package/src/templates/engine.ts
CHANGED
|
@@ -19,7 +19,7 @@ import { type EmailTheme, widthPx } from "./theme";
|
|
|
19
19
|
* evals at request time (CLAUDE.md §Email: "precompiled, no runtime compile/eval"). Rendering is then
|
|
20
20
|
* pure string substitution.
|
|
21
21
|
*
|
|
22
|
-
* Tracking is applied here, not in the template: callback tokens are minted ahead of render (
|
|
22
|
+
* Tracking is applied here, not in the template: callback tokens are minted ahead of render (sealing
|
|
23
23
|
* is async; Handlebars helpers are not) and the resulting URLs are placed into the render context.
|
|
24
24
|
* Click tracking rewrites the declared link locations; open tracking injects a pixel; and an **elective**
|
|
25
25
|
* template gets an unsubscribe link, which a marketing template additionally cannot render without.
|
package/src/version.generated.ts
CHANGED