@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.
@@ -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;AA+B1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;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,EAY9D,CAAC;AAaF,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAiDD,yFAAyF;AACzF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAkU5G"}
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"}
@@ -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, or look one address up.",
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.var.emit({
220
- action: EmailAuditActions.suppressionsRead,
221
- outcome: "success",
222
- actorType: "control-plane",
223
- actorId: who.subject,
224
- resourceType: "email_suppression",
225
- resourceId: null,
226
- metadata: {
227
- connectionId: who.connectionId,
228
- reason: query.reason ?? null,
229
- lookup: Boolean(query.email),
230
- active: query.active ?? null,
231
- returned: page.items.length,
232
- paged: Boolean(query.cursor)
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 for ${email} with expiresAt ${expiresAt.toISOString()} at ${now.toISOString()}`
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: `${email} is already suppressed as a ${current.reason}, which this route may not overwrite.`,
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} for ${email}`
304
+ detail: `refused manual suppression over an existing ${current.reason}`
265
305
  });
266
306
  await suppress(db, {
267
307
  email,
@@ -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 signed claims embed a long destination URL, so no link we
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 optional `?reason=` on the unsubscribe callback — supplied by the app's own preferences flow.
15
- * The bound is a ceiling, not the storage limit: the handler still truncates to 200 characters before
16
- * writing, so every real value keeps behaving exactly as it did and only an absurd one is refused.
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 UnsubscribeQuery: z.ZodObject<{
19
- reason: z.ZodOptional<z.ZodString>;
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 UnsubscribeQuery = z.output<typeof UnsubscribeQuery>;
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
- * `email` is an exact-match lookup rather than a search, and that is the point: answering "is this one
60
- * address blocked" should not require paging a list of every other person who ever unsubscribed. A
61
- * prefix or substring search would turn the endpoint into a way to enumerate the list a page at a time
62
- * while looking like a lookup.
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.$strip>;
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;AAErE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;iBAQqD,CAAC;AACnF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAoDjE;;;;;;;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;;;;;;;;;;;;;;iBAmB8E,CAAC;AAC7G,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,wGAAwG;AACxG,eAAO,MAAM,iBAAiB;;iBAI+D,CAAC;AAC9F,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,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"}
@@ -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 signed claims embed a long destination URL, so no link we
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 signed callback token from the path, optionally with the open-pixel `.png` suffix.") }).describe("The path parameter carrying a click/open/unsubscribe callback token.");
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 optional `?reason=` on the unsubscribe callback — supplied by the app's own preferences flow.
14
- * The bound is a ceiling, not the storage limit: the handler still truncates to 200 characters before
15
- * writing, so every real value keeps behaving exactly as it did and only an absurd one is refused.
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 UnsubscribeQuery = z.object({ reason: z.string().max(2e3).optional().describe("Why the recipient opted out; truncated to 200 characters before it is stored.") }).describe("The optional query parameters accepted by the unsubscribe callback.");
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
- * `email` is an exact-match lookup rather than a search, and that is the point: answering "is this one
67
- * address blocked" should not require paging a list of every other person who ever unsubscribed. A
68
- * prefix or substring search would turn the endpoint into a way to enumerate the list a page at a time
69
- * while looking like a lookup.
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, which address to look up, and where to resume.");
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, UnsubscribeQuery, UnsuppressRequest };
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 (signing
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.
@@ -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 (signing
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.9.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,UAAU,CAAC"}
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.9.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.9.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.17.0",
46
- "@pithy-sh/secrets": "^0.6.5",
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"
@@ -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. Nothing is sealed under this key at rest:
59
- // it signs, and a signature expires with its link.
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
  });