@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
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAKrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAEjF,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;
|
|
1
|
+
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAKrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAEjF,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAsC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,yGAAyG;AACzG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,qBAAqB,EAkB9D,CAAC;AAaF,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AA4ED,yFAAyF;AACzF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAuV5G"}
|
package/dist/http/routes.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
import { emailDatabase, emailSuppressionDatabase } from "../data/tables.js";
|
|
4
4
|
import { listSuppressions, suppress, unsuppress } from "../send/suppression.js";
|
|
5
|
-
import { JobIdParam, JobsQuery, SuppressRequest, SuppressionsQuery, UnsuppressRequest } from "./schemas.js";
|
|
5
|
+
import { JobIdParam, JobsQuery, SuppressRequest, SuppressionLookupRequest, SuppressionsQuery, UnsuppressRequest } from "./schemas.js";
|
|
6
6
|
import { EMAIL_JOBS_READ_SCOPE, EMAIL_JOBS_RETRY_SCOPE, EMAIL_SUPPRESSIONS_DELETE_SCOPE, EMAIL_SUPPRESSIONS_READ_SCOPE, EMAIL_SUPPRESSIONS_WRITE_SCOPE } from "./guards.js";
|
|
7
7
|
import { EmailAuditActions } from "../audit/actions.js";
|
|
8
8
|
import { getJob, listJobs } from "../jobs/read.js";
|
|
@@ -50,6 +50,12 @@ const EMAIL_ADMIN_ROUTES = [
|
|
|
50
50
|
strategy: "control-plane",
|
|
51
51
|
scope: EMAIL_SUPPRESSIONS_READ_SCOPE
|
|
52
52
|
},
|
|
53
|
+
{
|
|
54
|
+
method: "POST",
|
|
55
|
+
path: "/suppressions/lookup",
|
|
56
|
+
strategy: "control-plane",
|
|
57
|
+
scope: EMAIL_SUPPRESSIONS_READ_SCOPE
|
|
58
|
+
},
|
|
53
59
|
{
|
|
54
60
|
method: "POST",
|
|
55
61
|
path: "/suppressions",
|
|
@@ -102,6 +108,26 @@ function caller(c) {
|
|
|
102
108
|
});
|
|
103
109
|
return context;
|
|
104
110
|
}
|
|
111
|
+
/**
|
|
112
|
+
* Audit a read of the suppression list. The heaviest read in the capability: this database is global, so
|
|
113
|
+
* a page of it is a page of every environment's bounces, complaints, and opt-outs. Audited with whether
|
|
114
|
+
* it was a lookup or a walk, because those are very different events.
|
|
115
|
+
*/
|
|
116
|
+
async function auditSuppressionsRead(c, metadata) {
|
|
117
|
+
const who = caller(c);
|
|
118
|
+
await c.var.emit({
|
|
119
|
+
action: EmailAuditActions.suppressionsRead,
|
|
120
|
+
outcome: "success",
|
|
121
|
+
actorType: "control-plane",
|
|
122
|
+
actorId: who.subject,
|
|
123
|
+
resourceType: "email_suppression",
|
|
124
|
+
resourceId: null,
|
|
125
|
+
metadata: {
|
|
126
|
+
connectionId: who.connectionId,
|
|
127
|
+
...metadata
|
|
128
|
+
}
|
|
129
|
+
});
|
|
130
|
+
}
|
|
105
131
|
/** Register the email management sub-router. Composed alongside the public callbacks. */
|
|
106
132
|
function registerEmailAdminRoutes(options) {
|
|
107
133
|
const base = options.basePath;
|
|
@@ -204,33 +230,47 @@ function registerEmailAdminRoutes(options) {
|
|
|
204
230
|
});
|
|
205
231
|
});
|
|
206
232
|
app.get(`${base}/suppressions`, describeRoute({
|
|
207
|
-
summary: "Page through the suppression list
|
|
233
|
+
summary: "Page through the suppression list.",
|
|
208
234
|
verification: "control-plane",
|
|
209
235
|
scopes: [EMAIL_SUPPRESSIONS_READ_SCOPE],
|
|
210
236
|
responses: { 200: EmailSuppressionsResponse }
|
|
211
237
|
}), requireControlPlane(EMAIL_SUPPRESSIONS_READ_SCOPE), validate("query", SuppressionsQuery), async (c) => {
|
|
212
238
|
const query = c.req.valid("query");
|
|
213
|
-
const who = caller(c);
|
|
214
239
|
const now = clock();
|
|
215
240
|
const page = await listSuppressions(suppressions(c), {
|
|
216
241
|
...query,
|
|
217
242
|
now
|
|
218
243
|
});
|
|
219
|
-
await c
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
244
|
+
await auditSuppressionsRead(c, {
|
|
245
|
+
reason: query.reason ?? null,
|
|
246
|
+
lookup: false,
|
|
247
|
+
active: query.active ?? null,
|
|
248
|
+
returned: page.items.length,
|
|
249
|
+
paged: Boolean(query.cursor)
|
|
250
|
+
});
|
|
251
|
+
return c.json({
|
|
252
|
+
suppressions: page.items.map((row) => suppressionView(row, now)),
|
|
253
|
+
nextCursor: page.nextCursor
|
|
254
|
+
});
|
|
255
|
+
});
|
|
256
|
+
app.post(`${base}/suppressions/lookup`, describeRoute({
|
|
257
|
+
summary: "Look one address up on the suppression list.",
|
|
258
|
+
verification: "control-plane",
|
|
259
|
+
scopes: [EMAIL_SUPPRESSIONS_READ_SCOPE],
|
|
260
|
+
responses: { 200: EmailSuppressionsResponse }
|
|
261
|
+
}), requireControlPlane(EMAIL_SUPPRESSIONS_READ_SCOPE), validate("json", SuppressionLookupRequest), async (c) => {
|
|
262
|
+
const input = c.req.valid("json");
|
|
263
|
+
const now = clock();
|
|
264
|
+
const page = await listSuppressions(suppressions(c), {
|
|
265
|
+
email: input.email,
|
|
266
|
+
now
|
|
267
|
+
});
|
|
268
|
+
await auditSuppressionsRead(c, {
|
|
269
|
+
reason: null,
|
|
270
|
+
lookup: true,
|
|
271
|
+
active: null,
|
|
272
|
+
returned: page.items.length,
|
|
273
|
+
paged: false
|
|
234
274
|
});
|
|
235
275
|
return c.json({
|
|
236
276
|
suppressions: page.items.map((row) => suppressionView(row, now)),
|
|
@@ -252,16 +292,16 @@ function registerEmailAdminRoutes(options) {
|
|
|
252
292
|
if (expiresAt && expiresAt.getTime() <= now.getTime()) throw new ValidationError({
|
|
253
293
|
message: "That expiry has already passed, so it would not block anything.",
|
|
254
294
|
action: "Give a future instant, or omit `expiresAt` to block permanently. To lift an existing block, use the remove route — it requires `email:suppressions:delete`.",
|
|
255
|
-
detail: `refused suppression
|
|
295
|
+
detail: `refused suppression with expiresAt ${expiresAt.toISOString()} at ${now.toISOString()}`
|
|
256
296
|
});
|
|
257
297
|
const current = (await listSuppressions(db, {
|
|
258
298
|
email,
|
|
259
299
|
limit: 1
|
|
260
300
|
})).items[0];
|
|
261
301
|
if (current && current.reason !== "manual") throw new ConflictError({
|
|
262
|
-
message:
|
|
302
|
+
message: `That address is already suppressed as a ${current.reason}, which this route may not overwrite.`,
|
|
263
303
|
action: "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.",
|
|
264
|
-
detail: `refused manual suppression over an existing ${current.reason}
|
|
304
|
+
detail: `refused manual suppression over an existing ${current.reason}`
|
|
265
305
|
});
|
|
266
306
|
await suppress(db, {
|
|
267
307
|
email,
|
package/dist/http/schemas.d.ts
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
import { z } from "zod";
|
|
4
4
|
/**
|
|
5
5
|
* The `:token` path parameter every callback route carries. A shape and size bound only — the ceiling
|
|
6
|
-
* is generous enough for a click token whose
|
|
6
|
+
* is generous enough for a click token whose sealed claims embed a long destination URL, so no link we
|
|
7
7
|
* mint can exceed it, while an unbounded segment can no longer reach the verifier.
|
|
8
8
|
*/
|
|
9
9
|
export declare const CallbackTokenParam: z.ZodObject<{
|
|
@@ -11,14 +11,22 @@ export declare const CallbackTokenParam: z.ZodObject<{
|
|
|
11
11
|
}, z.core.$strip>;
|
|
12
12
|
export type CallbackTokenParam = z.output<typeof CallbackTokenParam>;
|
|
13
13
|
/**
|
|
14
|
-
* The
|
|
15
|
-
*
|
|
16
|
-
*
|
|
14
|
+
* The form body of an unsubscribe `POST`: what a mail client's one-click unsubscribe sends (RFC 8058 fixes it to
|
|
15
|
+
* `List-Unsubscribe=One-Click`), what the confirmation page's button sends, and what the app's own preferences flow
|
|
16
|
+
* sends with a `reason`.
|
|
17
|
+
*
|
|
18
|
+
* **Nothing in it can refuse the opt-out.** Every field is optional, a repeated field or one of the wrong type reads
|
|
19
|
+
* as absent or as its first value, and an over-long reason is truncated by the handler rather than refused. The
|
|
20
|
+
* token is the only gate; a body is never a reason somebody stays subscribed.
|
|
21
|
+
*
|
|
22
|
+
* The reason travels in the body because it is the recipient's own words, and a query string is written to every
|
|
23
|
+
* request log between the client and the Worker. The route reads no query at all.
|
|
17
24
|
*/
|
|
18
|
-
export declare const
|
|
19
|
-
|
|
25
|
+
export declare const UnsubscribeForm: z.ZodObject<{
|
|
26
|
+
"List-Unsubscribe": z.ZodCatch<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
|
|
27
|
+
reason: z.ZodCatch<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
|
|
20
28
|
}, z.core.$strip>;
|
|
21
|
-
export type
|
|
29
|
+
export type UnsubscribeForm = z.output<typeof UnsubscribeForm>;
|
|
22
30
|
/**
|
|
23
31
|
* The `:id` of one job.
|
|
24
32
|
*
|
|
@@ -56,10 +64,10 @@ export type JobsQuery = z.output<typeof JobsQuery>;
|
|
|
56
64
|
/**
|
|
57
65
|
* The suppression list query.
|
|
58
66
|
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
67
|
+
* **No address, and an unknown key is refused.** A query string is written to every request log between
|
|
68
|
+
* the client and the Worker, so looking one address up is {@link SuppressionLookupRequest}, a `POST`
|
|
69
|
+
* with the address in its body. Strict rather than stripping, so a client still sending `?email=` is
|
|
70
|
+
* told so with a 400 instead of being handed the whole list as though it were the match.
|
|
63
71
|
*/
|
|
64
72
|
export declare const SuppressionsQuery: z.ZodObject<{
|
|
65
73
|
reason: z.ZodOptional<z.ZodEnum<{
|
|
@@ -68,14 +76,13 @@ export declare const SuppressionsQuery: z.ZodObject<{
|
|
|
68
76
|
manual: "manual";
|
|
69
77
|
unsubscribe: "unsubscribe";
|
|
70
78
|
}>>;
|
|
71
|
-
email: z.ZodOptional<z.ZodString>;
|
|
72
79
|
active: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
|
|
73
80
|
false: "false";
|
|
74
81
|
true: "true";
|
|
75
82
|
}>, z.ZodTransform<boolean, "false" | "true">>>;
|
|
76
83
|
cursor: z.ZodOptional<z.ZodString>;
|
|
77
84
|
limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
|
|
78
|
-
}, z.core.$
|
|
85
|
+
}, z.core.$strict>;
|
|
79
86
|
export type SuppressionsQuery = z.output<typeof SuppressionsQuery>;
|
|
80
87
|
/**
|
|
81
88
|
* Block an address by hand.
|
|
@@ -93,6 +100,18 @@ export declare const SuppressRequest: z.ZodObject<{
|
|
|
93
100
|
expiresAt: z.ZodOptional<z.ZodISODateTime>;
|
|
94
101
|
}, z.core.$strip>;
|
|
95
102
|
export type SuppressRequest = z.output<typeof SuppressRequest>;
|
|
103
|
+
/**
|
|
104
|
+
* Look one address up.
|
|
105
|
+
*
|
|
106
|
+
* An exact match rather than a search, and that is the point: answering "is this one address blocked"
|
|
107
|
+
* should not require paging a list of every other person who ever unsubscribed, and a prefix or substring
|
|
108
|
+
* search would enumerate the list a page at a time while looking like a lookup. A body because a query
|
|
109
|
+
* string is written to every request log between the client and the Worker.
|
|
110
|
+
*/
|
|
111
|
+
export declare const SuppressionLookupRequest: z.ZodObject<{
|
|
112
|
+
email: z.ZodString;
|
|
113
|
+
}, z.core.$strict>;
|
|
114
|
+
export type SuppressionLookupRequest = z.output<typeof SuppressionLookupRequest>;
|
|
96
115
|
/** Unblock an address — the undo of {@link SuppressRequest}, and of a bounce, complaint, or opt-out. */
|
|
97
116
|
export declare const UnsuppressRequest: z.ZodObject<{
|
|
98
117
|
email: z.ZodString;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0BxB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;iBASoD,CAAC;AACpF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;
|
|
1
|
+
{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0BxB;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;iBASoD,CAAC;AACpF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAQrE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe;;;iBASwC,CAAC;AACrE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAoD/D;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU;;iBAS2C,CAAC;AACnE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAErD,yBAAyB;AACzB,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;iBAmBkF,CAAC;AACzG,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;kBAmB3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe;;;;iBAgBqD,CAAC;AAClF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;;kBAO6B,CAAC;AACnE,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEjF,wGAAwG;AACxG,eAAO,MAAM,iBAAiB;;iBAI+D,CAAC;AAC9F,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC"}
|
package/dist/http/schemas.js
CHANGED
|
@@ -5,16 +5,28 @@ import { z } from "zod";
|
|
|
5
5
|
import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
|
|
6
6
|
/**
|
|
7
7
|
* The `:token` path parameter every callback route carries. A shape and size bound only — the ceiling
|
|
8
|
-
* is generous enough for a click token whose
|
|
8
|
+
* is generous enough for a click token whose sealed claims embed a long destination URL, so no link we
|
|
9
9
|
* mint can exceed it, while an unbounded segment can no longer reach the verifier.
|
|
10
10
|
*/
|
|
11
|
-
const CallbackTokenParam = z.object({ token: z.string().min(1).max(4096).regex(/^[A-Za-z0-9._-]+$/).describe("The
|
|
11
|
+
const CallbackTokenParam = z.object({ token: z.string().min(1).max(4096).regex(/^[A-Za-z0-9._-]+$/).describe("The sealed callback token from the path, optionally with the open-pixel `.png` suffix.") }).describe("The path parameter carrying a click/open/unsubscribe callback token.");
|
|
12
|
+
/** One form field as a client may send it: a value, or a repeated field's values. Anything else reads as absent. */
|
|
13
|
+
const FormField = z.union([z.string(), z.array(z.string())]).optional().catch(void 0);
|
|
12
14
|
/**
|
|
13
|
-
* The
|
|
14
|
-
*
|
|
15
|
-
*
|
|
15
|
+
* The form body of an unsubscribe `POST`: what a mail client's one-click unsubscribe sends (RFC 8058 fixes it to
|
|
16
|
+
* `List-Unsubscribe=One-Click`), what the confirmation page's button sends, and what the app's own preferences flow
|
|
17
|
+
* sends with a `reason`.
|
|
18
|
+
*
|
|
19
|
+
* **Nothing in it can refuse the opt-out.** Every field is optional, a repeated field or one of the wrong type reads
|
|
20
|
+
* as absent or as its first value, and an over-long reason is truncated by the handler rather than refused. The
|
|
21
|
+
* token is the only gate; a body is never a reason somebody stays subscribed.
|
|
22
|
+
*
|
|
23
|
+
* The reason travels in the body because it is the recipient's own words, and a query string is written to every
|
|
24
|
+
* request log between the client and the Worker. The route reads no query at all.
|
|
16
25
|
*/
|
|
17
|
-
const
|
|
26
|
+
const UnsubscribeForm = z.object({
|
|
27
|
+
"List-Unsubscribe": FormField.describe("`One-Click` from a mail client's RFC 8058 one-click unsubscribe. Accepted and not otherwise read."),
|
|
28
|
+
reason: FormField.describe("Why the recipient opted out; the first value is kept, truncated to 200 characters before it is stored.")
|
|
29
|
+
}).describe("The optional form fields an unsubscribe POST accepts.");
|
|
18
30
|
/**
|
|
19
31
|
* Where the next page starts. Opaque, and a malformed one is a first page rather than a 400 — the
|
|
20
32
|
* decode lives in `@pithy-sh/core/src/data/cursor` and collapses every failure mode to the same
|
|
@@ -63,18 +75,17 @@ const JobsQuery = z.object({
|
|
|
63
75
|
/**
|
|
64
76
|
* The suppression list query.
|
|
65
77
|
*
|
|
66
|
-
*
|
|
67
|
-
*
|
|
68
|
-
*
|
|
69
|
-
*
|
|
78
|
+
* **No address, and an unknown key is refused.** A query string is written to every request log between
|
|
79
|
+
* the client and the Worker, so looking one address up is {@link SuppressionLookupRequest}, a `POST`
|
|
80
|
+
* with the address in its body. Strict rather than stripping, so a client still sending `?email=` is
|
|
81
|
+
* told so with a 400 instead of being handed the whole list as though it were the match.
|
|
70
82
|
*/
|
|
71
83
|
const SuppressionsQuery = z.object({
|
|
72
84
|
reason: SuppressionReason.optional().describe("Filter to one reason — hard bounce, complaint, unsubscribe, manual."),
|
|
73
|
-
email: AddressFilter.optional().describe("Look one address up, exactly. Answers `is this person blocked` without disclosing anybody else."),
|
|
74
85
|
active: z.enum(["true", "false"]).describe("`true` or `false`.").transform((value) => value === "true").optional().describe("`true` for the blocks in force now, `false` for the ones whose expiry has passed. Judged as each row's `active` is. Both when absent."),
|
|
75
86
|
cursor: Cursor,
|
|
76
87
|
limit: Limit
|
|
77
|
-
}).describe("The suppression-list query: what to filter by
|
|
88
|
+
}).strict().describe("The suppression-list query: what to filter by and where to resume. To look one address up, POST it to `/suppressions/lookup`.");
|
|
78
89
|
/**
|
|
79
90
|
* Block an address by hand.
|
|
80
91
|
*
|
|
@@ -90,7 +101,16 @@ const SuppressRequest = z.object({
|
|
|
90
101
|
detail: z.string().min(1).max(200).optional().describe("Why you are blocking it, in your own words. Stored verbatim on the row and in the audit trail."),
|
|
91
102
|
expiresAt: z.iso.datetime().optional().describe("When the block lifts, as an ISO-8601 instant. **Must be in the future** — checked in the handler against its injected clock rather than here, because a schema reading the wall clock would ignore the clock the route was given. Absent blocks permanently; a time-boxed block expires on its own rather than waiting for somebody to remember it. A past instant is refused because the send path decides purely on `expiresAt <= now`, so backdating one is exactly equivalent to lifting the block — an act this route's scope deliberately does not confer.")
|
|
92
103
|
}).describe("Add one address to the global suppression list, as a manual block.");
|
|
104
|
+
/**
|
|
105
|
+
* Look one address up.
|
|
106
|
+
*
|
|
107
|
+
* An exact match rather than a search, and that is the point: answering "is this one address blocked"
|
|
108
|
+
* should not require paging a list of every other person who ever unsubscribed, and a prefix or substring
|
|
109
|
+
* search would enumerate the list a page at a time while looking like a lookup. A body because a query
|
|
110
|
+
* string is written to every request log between the client and the Worker.
|
|
111
|
+
*/
|
|
112
|
+
const SuppressionLookupRequest = z.object({ email: AddressFilter.describe("The address to look up, matched exactly against the stored key. Answers `is this person blocked` without disclosing anybody else.") }).strict().describe("Look one address up on the global suppression list.");
|
|
93
113
|
/** Unblock an address — the undo of {@link SuppressRequest}, and of a bounce, complaint, or opt-out. */
|
|
94
114
|
const UnsuppressRequest = z.object({ email: AddressFilter.describe("The address to unblock, matched exactly against the stored key.") }).describe("Remove one address from the global suppression list, re-opening sending to it.");
|
|
95
115
|
//#endregion
|
|
96
|
-
export { CallbackTokenParam, JobIdParam, JobsQuery, SuppressRequest, SuppressionsQuery,
|
|
116
|
+
export { CallbackTokenParam, JobIdParam, JobsQuery, SuppressRequest, SuppressionLookupRequest, SuppressionsQuery, UnsubscribeForm, UnsuppressRequest };
|
|
@@ -10,7 +10,7 @@ import { type EmailTheme } from "./theme";
|
|
|
10
10
|
* evals at request time (CLAUDE.md §Email: "precompiled, no runtime compile/eval"). Rendering is then
|
|
11
11
|
* pure string substitution.
|
|
12
12
|
*
|
|
13
|
-
* Tracking is applied here, not in the template: callback tokens are minted ahead of render (
|
|
13
|
+
* Tracking is applied here, not in the template: callback tokens are minted ahead of render (sealing
|
|
14
14
|
* is async; Handlebars helpers are not) and the resulting URLs are placed into the render context.
|
|
15
15
|
* Click tracking rewrites the declared link locations; open tracking injects a pixel; and an **elective**
|
|
16
16
|
* template gets an unsubscribe link, which a marketing template additionally cannot render without.
|
package/dist/templates/engine.js
CHANGED
|
@@ -15,7 +15,7 @@ import Handlebars from "handlebars";
|
|
|
15
15
|
* evals at request time (CLAUDE.md §Email: "precompiled, no runtime compile/eval"). Rendering is then
|
|
16
16
|
* pure string substitution.
|
|
17
17
|
*
|
|
18
|
-
* Tracking is applied here, not in the template: callback tokens are minted ahead of render (
|
|
18
|
+
* Tracking is applied here, not in the template: callback tokens are minted ahead of render (sealing
|
|
19
19
|
* is async; Handlebars helpers are not) and the resulting URLs are placed into the render context.
|
|
20
20
|
* Click tracking rewrites the declared link locations; open tracking injects a pixel; and an **elective**
|
|
21
21
|
* template gets an unsubscribe link, which a marketing template additionally cannot render without.
|
|
@@ -3,5 +3,5 @@
|
|
|
3
3
|
/** This package's npm name — the join key against a release feed. */
|
|
4
4
|
export declare const PACKAGE_NAME = "@pithy-sh/email";
|
|
5
5
|
/** This package's version, stamped from its own package.json at generation time. */
|
|
6
|
-
export declare const PACKAGE_VERSION = "0.
|
|
6
|
+
export declare const PACKAGE_VERSION = "0.10.1";
|
|
7
7
|
//# sourceMappingURL=version.generated.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,oBAAoB,CAAC;AAE9C,oFAAoF;AACpF,eAAO,MAAM,eAAe,
|
|
1
|
+
{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,oBAAoB,CAAC;AAE9C,oFAAoF;AACpF,eAAO,MAAM,eAAe,WAAW,CAAC"}
|
|
@@ -4,6 +4,6 @@
|
|
|
4
4
|
/** This package's npm name — the join key against a release feed. */
|
|
5
5
|
const PACKAGE_NAME = "@pithy-sh/email";
|
|
6
6
|
/** This package's version, stamped from its own package.json at generation time. */
|
|
7
|
-
const PACKAGE_VERSION = "0.
|
|
7
|
+
const PACKAGE_VERSION = "0.10.1";
|
|
8
8
|
//#endregion
|
|
9
9
|
export { PACKAGE_NAME, PACKAGE_VERSION };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pithy-sh/email",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.1",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -42,8 +42,8 @@
|
|
|
42
42
|
"postal-mime": "^3.0.0"
|
|
43
43
|
},
|
|
44
44
|
"peerDependencies": {
|
|
45
|
-
"@pithy-sh/core": "^0.
|
|
46
|
-
"@pithy-sh/secrets": "^0.6.
|
|
45
|
+
"@pithy-sh/core": "^0.19.0",
|
|
46
|
+
"@pithy-sh/secrets": "^0.6.7",
|
|
47
47
|
"hono": "^4.13.2",
|
|
48
48
|
"kysely": "^0.29.0",
|
|
49
49
|
"zod": "^4.4.0"
|
package/src/crypto/signingKey.ts
CHANGED
|
@@ -55,8 +55,10 @@ export const emailSigningRegistry = defineSecretRegistry({
|
|
|
55
55
|
// **A rotation keeps the previous key for as long as a link lives (#602).** A link is minted into mail
|
|
56
56
|
// nobody can recall and stays valid for `LINK_TTL_DAYS` — 90 by default — so a key retired sooner breaks
|
|
57
57
|
// an unsubscribe that was valid when it was sent. A host that raises `LINK_TTL_DAYS` wants a longer
|
|
58
|
-
// overlap than this, declared in the project's own registry.
|
|
59
|
-
//
|
|
58
|
+
// overlap than this, declared in the project's own registry. Each link is sealed under a key derived from
|
|
59
|
+
// this one, and a link outlives its expiry in every log that recorded it: a leaked version, retired or
|
|
60
|
+
// not, opens every logged link sealed under it. Rotating moves new links to a new version; it does not
|
|
61
|
+
// reseal the old ones.
|
|
60
62
|
overlap: { days: 90, minimumDays: 90 },
|
|
61
63
|
},
|
|
62
64
|
});
|