@pithy-sh/email 0.8.2 → 0.10.0

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.
Files changed (62) hide show
  1. package/README.md +2 -0
  2. package/dist/bounce/handler.d.ts +22 -2
  3. package/dist/bounce/handler.d.ts.map +1 -1
  4. package/dist/bounce/handler.js +60 -17
  5. package/dist/capability.d.ts +12 -0
  6. package/dist/capability.d.ts.map +1 -1
  7. package/dist/capability.js +25 -15
  8. package/dist/crypto/signingKey.d.ts.map +1 -1
  9. package/dist/crypto/token.d.ts +43 -11
  10. package/dist/crypto/token.d.ts.map +1 -1
  11. package/dist/crypto/token.js +158 -55
  12. package/dist/http/callbacks.d.ts +8 -3
  13. package/dist/http/callbacks.d.ts.map +1 -1
  14. package/dist/http/callbacks.js +67 -12
  15. package/dist/http/guards.d.ts.map +1 -1
  16. package/dist/http/guards.js +9 -0
  17. package/dist/http/routes.d.ts +8 -4
  18. package/dist/http/routes.d.ts.map +1 -1
  19. package/dist/http/routes.js +67 -21
  20. package/dist/http/schemas.d.ts +41 -13
  21. package/dist/http/schemas.d.ts.map +1 -1
  22. package/dist/http/schemas.js +38 -15
  23. package/dist/jobs/read.d.ts +12 -9
  24. package/dist/jobs/read.d.ts.map +1 -1
  25. package/dist/jobs/read.js +6 -5
  26. package/dist/migrations/0002_job_filters.d.ts +15 -0
  27. package/dist/migrations/0002_job_filters.d.ts.map +1 -0
  28. package/dist/migrations/0002_job_filters.js +25 -0
  29. package/dist/send/enqueue.d.ts +26 -3
  30. package/dist/send/enqueue.d.ts.map +1 -1
  31. package/dist/send/enqueue.js +25 -2
  32. package/dist/send/errorMapping.d.ts +15 -20
  33. package/dist/send/errorMapping.d.ts.map +1 -1
  34. package/dist/send/errorMapping.js +33 -27
  35. package/dist/send/runSend.d.ts +2 -2
  36. package/dist/send/runSend.d.ts.map +1 -1
  37. package/dist/send/runSend.js +1 -1
  38. package/dist/send/suppression.d.ts +4 -0
  39. package/dist/send/suppression.d.ts.map +1 -1
  40. package/dist/send/suppression.js +4 -0
  41. package/dist/templates/engine.d.ts +1 -1
  42. package/dist/templates/engine.js +1 -1
  43. package/dist/version.generated.d.ts +1 -1
  44. package/dist/version.generated.d.ts.map +1 -1
  45. package/dist/version.generated.js +1 -1
  46. package/package.json +3 -3
  47. package/src/bounce/handler.ts +84 -32
  48. package/src/capability.ts +47 -27
  49. package/src/crypto/signingKey.ts +4 -2
  50. package/src/crypto/token.ts +225 -92
  51. package/src/http/callbacks.ts +100 -32
  52. package/src/http/guards.ts +9 -0
  53. package/src/http/routes.ts +96 -28
  54. package/src/http/schemas.ts +75 -24
  55. package/src/jobs/read.ts +14 -9
  56. package/src/migrations/0002_job_filters.ts +35 -0
  57. package/src/send/enqueue.ts +52 -5
  58. package/src/send/errorMapping.ts +45 -38
  59. package/src/send/runSend.ts +6 -7
  60. package/src/send/suppression.ts +13 -0
  61. package/src/templates/engine.ts +1 -1
  62. package/src/version.generated.ts +1 -1
package/README.md CHANGED
@@ -10,6 +10,8 @@ pithy add email
10
10
 
11
11
  **Documentation: [pithy.sh/docs/capabilities/email](https://pithy.sh/docs/capabilities/email).** Overview, adding it, using it, and the reference: the job model, send modes, templates.
12
12
 
13
+ **A per-message sender.** `enqueue` sends every message as `fromAddress` and `fromName`, and refuses a `from` with `email/invalid_payload`. `enqueueAs(addresses)` is how a capability declares the addresses it sends as: bound once, at compose, it accepts `from: { address, name? }` for those addresses and refuses any other. It is a convention that keeps a capability to its own addresses, not a security boundary: any code in the Worker can call it, and what limits sending is Cloudflare, which sends only from domains onboarded onto Email Service. The sender is stored on the job. A send Email Service refuses because the domain is not onboarded or not verified fails the job with the domain named in `error`, and is never retried as another sender.
14
+
13
15
  _Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
14
16
 
15
17
  ## Consent
@@ -20,6 +20,15 @@ export interface InboundOutcome {
20
20
  jobId?: string;
21
21
  /** Whether the address was added to the suppression list. */
22
22
  suppressed: boolean;
23
+ /** Each part left undone because the database it writes to was not given, in the order they were reached. */
24
+ skipped: InboundSkip[];
25
+ }
26
+ /** One part of applying a classification that did not run, and the binding it needed. */
27
+ export interface InboundSkip {
28
+ /** `job` is the job lookup, its bounce marking and its event; `suppression` is the suppression-list write. */
29
+ part: "job" | "suppression";
30
+ /** The Worker binding that part writes through. */
31
+ binding: "DB" | "EMAIL_SUPPRESSIONS";
23
32
  }
24
33
  /**
25
34
  * Apply a classification's side effects. Suppression is written to the **shared** suppression database
@@ -27,8 +36,19 @@ export interface InboundOutcome {
27
36
  * database. Pure of any MIME parsing — unit-testable. Note the single inbound worker only reaches its
28
37
  * own app DB, so a job-row update is best-effort (the originating job may live in another environment),
29
38
  * whereas the suppression — the safety-critical part — is always global.
39
+ *
40
+ * Each part runs on the database it needs and no other: a missing app database skips the job, a missing
41
+ * suppression database skips the suppression, and each skip is reported in `skipped` rather than thrown.
42
+ */
43
+ export declare function applyInbound(db: EmailDatabase | undefined, suppressionDb: EmailSuppressionDatabase | undefined, c: InboundClassification, now: Date, environment?: string): Promise<InboundOutcome>;
44
+ /**
45
+ * Build the inbound-email handler for the `Capability.email` seam. Reads `DB` + `EMAIL_SUPPRESSIONS` from env.
46
+ *
47
+ * It never throws. `createEntrypoint` runs every capability's handler in turn, so a throw here would stop the ones
48
+ * after it, and a throw out of `email()` is a delivery failure the sender sees. A failure is logged with its error
49
+ * and the handler returns. It classifies before it touches a binding: a message it will not act on needs neither
50
+ * database, and each part of a bounce runs on the binding it needs, with a part whose binding is missing logged at
51
+ * warn rather than thrown.
30
52
  */
31
- export declare function applyInbound(db: EmailDatabase, suppressionDb: EmailSuppressionDatabase, c: InboundClassification, now: Date, environment?: string): Promise<InboundOutcome>;
32
- /** Build the inbound-email handler for the `Capability.email` seam. Reads `DB` + `EMAIL_SUPPRESSIONS` from env. */
33
53
  export declare function createBounceHandler(): CapabilityEmailHandler;
34
54
  //# sourceMappingURL=handler.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/bounce/handler.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAGvF,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAG9B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAmB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;;GAMG;AAEH,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,KAAK,EAAE,OAAO,CAAC;IACf,+BAA+B;IAC/B,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACpC,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,aAAa,EACjB,aAAa,EAAE,wBAAwB,EACvC,CAAC,EAAE,qBAAqB,EACxB,GAAG,EAAE,IAAI,EACT,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,cAAc,CAAC,CA0DzB;AAED,mHAAmH;AACnH,wBAAgB,mBAAmB,IAAI,sBAAsB,CAuB5D"}
1
+ {"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/bounce/handler.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAIvF,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAG9B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAmB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;;GAMG;AAEH,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,KAAK,EAAE,OAAO,CAAC;IACf,+BAA+B;IAC/B,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IACpC,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,UAAU,EAAE,OAAO,CAAC;IACpB,6GAA6G;IAC7G,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAED,yFAAyF;AACzF,MAAM,WAAW,WAAW;IAC1B,8GAA8G;IAC9G,IAAI,EAAE,KAAK,GAAG,aAAa,CAAC;IAC5B,mDAAmD;IACnD,OAAO,EAAE,IAAI,GAAG,oBAAoB,CAAC;CACtC;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,aAAa,GAAG,SAAS,EAC7B,aAAa,EAAE,wBAAwB,GAAG,SAAS,EACnD,CAAC,EAAE,qBAAqB,EACxB,GAAG,EAAE,IAAI,EACT,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,cAAc,CAAC,CAiEzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,sBAAsB,CAyC5D"}
@@ -6,6 +6,7 @@ import { suppress } from "../send/suppression.js";
6
6
  import { classifyInbound } from "./classify.js";
7
7
  import { normalizeAddress } from "@pithy-sh/core/src/address/address";
8
8
  import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
9
+ import { createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
9
10
  import PostalMime from "postal-mime";
10
11
  //#region src/bounce/handler.ts
11
12
  /**
@@ -14,14 +15,23 @@ import PostalMime from "postal-mime";
14
15
  * database. Pure of any MIME parsing — unit-testable. Note the single inbound worker only reaches its
15
16
  * own app DB, so a job-row update is best-effort (the originating job may live in another environment),
16
17
  * whereas the suppression — the safety-critical part — is always global.
18
+ *
19
+ * Each part runs on the database it needs and no other: a missing app database skips the job, a missing
20
+ * suppression database skips the suppression, and each skip is reported in `skipped` rather than thrown.
17
21
  */
18
22
  async function applyInbound(db, suppressionDb, c, now, environment) {
19
23
  if (c.type === "ignore" || c.type === "auto_reply") return {
20
24
  acted: false,
21
25
  type: c.type,
22
- suppressed: false
26
+ suppressed: false,
27
+ skipped: []
23
28
  };
24
- const job = c.originalMessageId ? await db.selectFrom("pithyEmailJobs").select([
29
+ const skipped = [];
30
+ if (db === void 0) skipped.push({
31
+ part: "job",
32
+ binding: "DB"
33
+ });
34
+ const job = c.originalMessageId && db ? await db.selectFrom("pithyEmailJobs").select([
25
35
  "id",
26
36
  "toAddress",
27
37
  "status",
@@ -30,7 +40,11 @@ async function applyInbound(db, suppressionDb, c, now, environment) {
30
40
  const recipient = c.recipient ? normalizeAddress(c.recipient) : job ? normalizeAddress(job.toAddress) : void 0;
31
41
  const isSuppressing = c.type === "hard" || c.type === "complaint";
32
42
  let suppressed = false;
33
- if (recipient && isSuppressing) {
43
+ if (recipient && isSuppressing && suppressionDb === void 0) skipped.push({
44
+ part: "suppression",
45
+ binding: "EMAIL_SUPPRESSIONS"
46
+ });
47
+ else if (recipient && isSuppressing && suppressionDb) {
34
48
  await suppress(suppressionDb, {
35
49
  email: recipient,
36
50
  reason: c.type === "complaint" ? "complaint" : "hard_bounce",
@@ -40,7 +54,7 @@ async function applyInbound(db, suppressionDb, c, now, environment) {
40
54
  }, now);
41
55
  suppressed = true;
42
56
  }
43
- if (job) {
57
+ if (job && db) {
44
58
  await db.updateTable("pithyEmailJobs").set({
45
59
  bounceCode: c.code ?? null,
46
60
  bounceType: c.type,
@@ -59,25 +73,54 @@ async function applyInbound(db, suppressionDb, c, now, environment) {
59
73
  acted: suppressed || Boolean(job),
60
74
  type: c.type,
61
75
  jobId: job?.id,
62
- suppressed
76
+ suppressed,
77
+ skipped
63
78
  };
64
79
  }
65
- /** Build the inbound-email handler for the `Capability.email` seam. Reads `DB` + `EMAIL_SUPPRESSIONS` from env. */
80
+ /**
81
+ * Build the inbound-email handler for the `Capability.email` seam. Reads `DB` + `EMAIL_SUPPRESSIONS` from env.
82
+ *
83
+ * It never throws. `createEntrypoint` runs every capability's handler in turn, so a throw here would stop the ones
84
+ * after it, and a throw out of `email()` is a delivery failure the sender sees. A failure is logged with its error
85
+ * and the handler returns. It classifies before it touches a binding: a message it will not act on needs neither
86
+ * database, and each part of a bounce runs on the binding it needs, with a part whose binding is missing logged at
87
+ * warn rather than thrown.
88
+ */
66
89
  function createBounceHandler() {
67
90
  return async (message, env) => {
68
- const raw = await new Response(message.raw).text();
69
- const parsed = await PostalMime.parse(raw);
70
- const headers = {};
71
- for (const header of parsed.headers) headers[header.key.toLowerCase()] = header.value;
72
- const classification = classifyInbound({
73
- contentType: headers["content-type"],
74
- autoSubmitted: headers["auto-submitted"],
75
- autoReplyHeader: "x-autoreply" in headers || "x-autorespond" in headers,
76
- raw
91
+ const environment = typeof env.ENVIRONMENT === "string" ? env.ENVIRONMENT : void 0;
92
+ const log = createWorkerLogger({
93
+ name: "email",
94
+ fields: { env: environment ?? "unknown" }
77
95
  });
78
- const bindings = env;
79
- await applyInbound(emailDatabase(bindings.DB), emailSuppressionDatabase(bindings.EMAIL_SUPPRESSIONS), classification, /* @__PURE__ */ new Date(), bindings.ENVIRONMENT);
96
+ try {
97
+ const raw = await new Response(message.raw).text();
98
+ const parsed = await PostalMime.parse(raw);
99
+ const headers = {};
100
+ for (const header of parsed.headers) headers[header.key.toLowerCase()] = header.value;
101
+ const classification = classifyInbound({
102
+ contentType: headers["content-type"],
103
+ autoSubmitted: headers["auto-submitted"],
104
+ autoReplyHeader: "x-autoreply" in headers || "x-autorespond" in headers,
105
+ raw
106
+ });
107
+ if (classification.type === "ignore" || classification.type === "auto_reply") return;
108
+ const { DB: db, EMAIL_SUPPRESSIONS: suppressions } = env;
109
+ const outcome = await applyInbound(isD1(db) ? emailDatabase(db) : void 0, isD1(suppressions) ? emailSuppressionDatabase(suppressions) : void 0, classification, /* @__PURE__ */ new Date(), environment);
110
+ for (const { part, binding } of outcome.skipped) log.warn(`email ${part === "job" ? "bounce not recorded on its job" : "address not suppressed"} — no ${binding} binding`, {
111
+ binding,
112
+ skipped: part,
113
+ type: classification.type,
114
+ action: `Bind \`${binding}\` in this Worker's wrangler.jsonc.`
115
+ });
116
+ } catch (error) {
117
+ log.error("email inbound handling failed", { error });
118
+ }
80
119
  };
81
120
  }
121
+ /** Whether a binding is there to open: a D1 binding is an object, and an absent one is `undefined`. */
122
+ function isD1(binding) {
123
+ return typeof binding === "object" && binding !== null;
124
+ }
82
125
  //#endregion
83
126
  export { applyInbound, createBounceHandler };
@@ -118,6 +118,18 @@ export interface EmailCapability extends Capability {
118
118
  * `EnqueueDeps` or name the email bindings themselves.
119
119
  */
120
120
  enqueue: (env: EmailEnqueueEnv, input: EnqueueInput) => Promise<EnqueueResult>;
121
+ /**
122
+ * `enqueue`, able to send as the addresses a composing capability declares and no others.
123
+ *
124
+ * The one way a per-message `from` is accepted. `enqueue` declares none, so an override passed to it is
125
+ * refused; a capability that receives mail at its own addresses binds this once, at compose, with exactly
126
+ * those addresses, and an override outside them is refused at enqueue. `@pithy-sh/support` binds its
127
+ * `inboundAddresses` and `reply.replyToAddress`.
128
+ *
129
+ * A convention that keeps each capability to its own addresses, not a security boundary: trusted Worker code
130
+ * can call this with any list. What limits sending is Cloudflare, which sends only from onboarded domains.
131
+ */
132
+ enqueueAs: (claimed: readonly string[]) => (env: EmailEnqueueEnv, input: EnqueueInput) => Promise<EnqueueResult>;
121
133
  /**
122
134
  * The suppression list, from a request env — **it is the adopter's database, and this is how they open
123
135
  * it**.
@@ -1 +1 @@
1
- {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAK7F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EACL,KAAK,wBAAwB,EAM9B,MAAM,eAAe,CAAC;AAOvB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAI1D,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAgB,MAAM,gBAAgB,CAAC;AACrF,OAAO,EAAE,KAAK,cAAc,EAAsB,MAAM,sBAAsB,CAAC;AAE/E,OAAO,EAAe,KAAK,UAAU,EAAgB,MAAM,mBAAmB,CAAC;AAI/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,EAAE,EAAE,UAAU,CAAC;IACf;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,UAAU,CAAC;CACjC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,kGAAkG;AAClG,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiC8B,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D,2FAA2F;AAC3F,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,WAAW,EAAE,eAAe,CAAC;IAC7B,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,WAAW,EAAE,mBAAmB,CAAC;IACjC;;;;;OAKG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/E;;;;;;;;;;;;;OAaG;IACH,YAAY,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,wBAAwB,CAAC;IACjE;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,MAAM,cAAc,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CA0P/D;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
1
+ {"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAK7F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EACL,KAAK,wBAAwB,EAM9B,MAAM,eAAe,CAAC;AAQvB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAI1D,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAgB,MAAM,gBAAgB,CAAC;AACrF,OAAO,EAAE,KAAK,cAAc,EAAsB,MAAM,sBAAsB,CAAC;AAE/E,OAAO,EAAe,KAAK,UAAU,EAAgB,MAAM,mBAAmB,CAAC;AAI/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,EAAE,EAAE,UAAU,CAAC;IACf;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,UAAU,CAAC;CACjC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,kGAAkG;AAClG,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiC8B,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D,2FAA2F;AAC3F,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,WAAW,EAAE,eAAe,CAAC;IAC7B,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,WAAW,EAAE,mBAAmB,CAAC;IACjC;;;;;OAKG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/E;;;;;;;;;;OAUG;IACH,SAAS,EAAE,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,KAAK,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IACjH;;;;;;;;;;;;;OAaG;IACH,YAAY,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,wBAAwB,CAAC;IACjE;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,MAAM,cAAc,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAiQ/D;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
@@ -12,6 +12,7 @@ import { emailSenderBinding } from "./send/senderBinding.js";
12
12
  import { registerEmailAdminRoutes } from "./http/routes.js";
13
13
  import { email_0001_init } from "./migrations/0001_init.js";
14
14
  import { email_0001_suppressions } from "./migrations/0001_suppressions.js";
15
+ import { email_0002_job_filters } from "./migrations/0002_job_filters.js";
15
16
  import { EMAIL_PROCESSING } from "./processing/activities.js";
16
17
  import { DevMailDelivery } from "./provision/devDelivery.js";
17
18
  import { emailHostCatalogs } from "./provision/hostCatalogs.js";
@@ -140,7 +141,7 @@ function email(config) {
140
141
  if (Array.isArray(locales)) supportedLocales = locales.filter((tag) => typeof tag === "string");
141
142
  }
142
143
  },
143
- ciPermissions: ["email:routing"],
144
+ inboundRouting: { addresses: [] },
144
145
  requiredBindings: [
145
146
  {
146
147
  type: "d1",
@@ -160,7 +161,10 @@ function email(config) {
160
161
  binding: "DB",
161
162
  tables: emailTables,
162
163
  migrationOrder: 200,
163
- migrations: { "0001_init": email_0001_init }
164
+ migrations: {
165
+ "0001_init": email_0001_init,
166
+ "0002_job_filters": email_0002_job_filters
167
+ }
164
168
  },
165
169
  emailSuppressions: {
166
170
  binding: "EMAIL_SUPPRESSIONS",
@@ -264,19 +268,24 @@ function email(config) {
264
268
  if (composed === void 0) return void 0;
265
269
  return (charge) => composed.charge(env, charge);
266
270
  };
267
- const enqueue = (env, input) => enqueueEmail({
268
- db: emailDatabase(env.DB),
269
- fromAddress: resolved.fromAddress,
270
- fromName: resolved.fromName,
271
- theme,
272
- layersFor: (locale) => layersFor(locale),
273
- sender: emailSenderBinding(env),
274
- suppressionDb: env.EMAIL_SUPPRESSIONS ? emailSuppressionDatabase(env.EMAIL_SUPPRESSIONS) : void 0,
275
- meter: chargeFor(env),
276
- consent: composedConsent(composition, env),
277
- now: /* @__PURE__ */ new Date(),
278
- newId: () => crypto.randomUUID()
279
- }, input);
271
+ const enqueueAs = (claimed) => {
272
+ const claimedFrom = Object.freeze([...claimed]);
273
+ return (env, input) => enqueueEmail({
274
+ db: emailDatabase(env.DB),
275
+ fromAddress: resolved.fromAddress,
276
+ fromName: resolved.fromName,
277
+ claimedFrom,
278
+ theme,
279
+ layersFor: (locale) => layersFor(locale),
280
+ sender: emailSenderBinding(env),
281
+ suppressionDb: env.EMAIL_SUPPRESSIONS ? emailSuppressionDatabase(env.EMAIL_SUPPRESSIONS) : void 0,
282
+ meter: chargeFor(env),
283
+ consent: composedConsent(composition, env),
284
+ now: /* @__PURE__ */ new Date(),
285
+ newId: () => crypto.randomUUID()
286
+ }, input);
287
+ };
288
+ const enqueue = enqueueAs([]);
280
289
  return Object.assign(capability, {
281
290
  emailConfig: {
282
291
  fromAddress: resolved.fromAddress,
@@ -287,6 +296,7 @@ function email(config) {
287
296
  theme
288
297
  },
289
298
  enqueue,
299
+ enqueueAs,
290
300
  suppressions,
291
301
  hostCatalogs: () => emailHostCatalogs(supportedLocales, (locale) => layersFor(locale))
292
302
  });
@@ -1 +1 @@
1
- {"version":3,"file":"signingKey.d.ts","sourceRoot":"","sources":["../../src/crypto/signingKey.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAG1E;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,0BAA4C,CAAC;AAExF,gHAAgH;AAChH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;CAqC/B,CAAC;AAEH;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,eAAe,CAAC,CAAC,OAAO,oBAAoB,CAAC,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAAC,CAGxF"}
1
+ {"version":3,"file":"signingKey.d.ts","sourceRoot":"","sources":["../../src/crypto/signingKey.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAG1E;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,0BAA4C,CAAC;AAExF,gHAAgH;AAChH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;CAuC/B,CAAC;AAEH;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,eAAe,CAAC,CAAC,OAAO,oBAAoB,CAAC,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAAC,CAGxF"}
@@ -1,15 +1,44 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
  import { z } from "zod";
4
+ /**
5
+ * Sealed callback tokens. Click, open, and unsubscribe links carry one of these, and a link is written to every
6
+ * request log between a mail client and the Worker: Cloudflare's, Workers observability and tail, a mail scanner, a
7
+ * proxy. So a token says nothing to anyone who holds it. Its claims (which job, which recipient, where a click goes,
8
+ * which campaign) are sealed with AES-256-GCM, which both hides them and makes them tamper-proof: a changed byte
9
+ * fails the tag, and nothing is acted on before the tag verifies.
10
+ *
11
+ * Each token's sealing key is derived with HKDF-SHA256 from one version of the **rotatable** link-signing key in
12
+ * `@pithy-sh/secrets`, under the label {@link SEAL_LABEL} and a random salt the token carries. One secret, one
13
+ * rotation, and a fresh key per token, so no volume of mail brings two tokens near a shared key and IV. Every token names the key version
14
+ * (`kid`) it was sealed under, so a link in a months-old email still opens against the retained version set after a
15
+ * rotation, and is rejected once that version is pruned.
16
+ *
17
+ * A token also names the origin it was minted for (`aud`), and only that origin may act on it. A link points at the
18
+ * environment that minted it, and the key is per environment; the claim keeps a key misconfigured as shared from
19
+ * letting a staging token act on production's routes.
20
+ *
21
+ * ## Two formats on read, one on write
22
+ *
23
+ * - **`3.<kid>.<sealed>`**, minted by {@link mintToken}: `kid` base64url, `sealed` the 16-byte salt, the 12-byte
24
+ * IV, then the ciphertext and tag, base64url. The kid is bound as authenticated data, so a token moved to another
25
+ * version fails.
26
+ * - **`<payload>.<signature>`**, the signed format before it: base64url JSON with `v: 2` and an HMAC-SHA-256
27
+ * signature. Its payload decodes on sight, recipient included, so nothing mints it. It is still read, because
28
+ * mail already sent carries it, and it is accepted only until its own `exp`: `LINK_TTL_DAYS` from when it was
29
+ * sent, 90 days by default. The last one expires that long after the first deploy that stopped minting them,
30
+ * and the reader can be deleted then.
31
+ */
32
+ /** The HKDF label a sealing key is derived under. Versioned, so a change to the format is a change of key. */
33
+ export declare const SEAL_LABEL = "pithy/email/link-seal/3";
4
34
  export declare const TokenKind: z.ZodEnum<{
5
35
  click: "click";
6
36
  open: "open";
7
37
  unsubscribe: "unsubscribe";
8
38
  }>;
9
39
  export type TokenKind = z.output<typeof TokenKind>;
10
- /** The signed claims a callback token carries. `kid`/`exp`/`v`/`aud` are set by `mintToken`; the rest are caller claims. */
40
+ /** The claims a callback token carries. `kid`/`exp`/`v`/`aud` are set by `mintToken`; the rest are caller claims. */
11
41
  export declare const CallbackToken: z.ZodObject<{
12
- v: z.ZodLiteral<2>;
13
42
  kid: z.ZodString;
14
43
  aud: z.ZodString;
15
44
  kind: z.ZodEnum<{
@@ -23,8 +52,13 @@ export declare const CallbackToken: z.ZodObject<{
23
52
  destination: z.ZodOptional<z.ZodString>;
24
53
  linkLabel: z.ZodOptional<z.ZodString>;
25
54
  campaignId: z.ZodOptional<z.ZodString>;
55
+ v: z.ZodLiteral<3>;
26
56
  }, z.core.$strip>;
27
57
  export type CallbackToken = z.output<typeof CallbackToken>;
58
+ /** The claims a verified token hands back, whichever format it arrived in. */
59
+ export type VerifiedCallbackToken = Omit<CallbackToken, "v"> & {
60
+ v: 2 | 3;
61
+ };
28
62
  /** The caller-supplied claims for a token — everything except the fields `mintToken` fills in. */
29
63
  export type TokenClaims = Omit<CallbackToken, "v" | "kid" | "exp" | "aud">;
30
64
  /**
@@ -37,9 +71,8 @@ export type TokenClaims = Omit<CallbackToken, "v" | "kid" | "exp" | "aud">;
37
71
  */
38
72
  export declare function tokenAudience(url: string): string;
39
73
  /**
40
- * Mint a signed token. The claims plus `kid`/`exp`/`v` are JSON-encoded and base64url-packed, then
41
- * HMAC-SHA-256 signed with `key`. The token is `<payload>.<signature>`; `kid` rides inside the signed
42
- * payload so the verifier knows which key to check without trusting an unsigned header.
74
+ * Mint a sealed token: the claims plus `v`/`kid`/`aud`/`exp`, JSON-encoded and sealed with AES-256-GCM under the key
75
+ * derived from `key`. Nothing in the result decodes to a claim.
43
76
  */
44
77
  export declare function mintToken(claims: TokenClaims, options: {
45
78
  key: string;
@@ -49,11 +82,10 @@ export declare function mintToken(claims: TokenClaims, options: {
49
82
  audience: string;
50
83
  }): Promise<string>;
51
84
  /**
52
- * Verify a token against the valid signing-key version set (`@pithy-sh/secrets`' `getVersions` shape)
53
- * and return its claims. Rejects — as `email/invalid_token` — a malformed token, an unknown/pruned
54
- * `kid`, a bad signature (constant-time via `crypto.subtle.verify`), a token minted for another origin,
55
- * or an expired token. The order is deliberate: structure, then signature, then audience, then expiry,
56
- * so a forged token never reaches a claim check.
85
+ * Verify a token against the valid key version set (`@pithy-sh/secrets`' `getVersions` shape) and return its claims.
86
+ * Rejects — as `email/invalid_token` — a malformed token, an unknown or pruned `kid`, a token whose seal or signature
87
+ * does not verify, a token minted for another origin, or an expired token. The order is deliberate: structure, then
88
+ * the cryptographic check, then audience, then expiry, so a forged token never reaches a claim check.
57
89
  *
58
90
  * `audience` is **required**, and is the URL the token arrived on — the request's own. A verifier that
59
91
  * could omit it would be a verifier that accepts every origin, which is the hole the claim closes.
@@ -65,5 +97,5 @@ export declare function mintToken(claims: TokenClaims, options: {
65
97
  */
66
98
  export declare function verifyToken(token: string, keys: {
67
99
  versions: Record<string, string>;
68
- }, now: Date, audience: string): Promise<CallbackToken>;
100
+ }, now: Date, audience: string): Promise<VerifiedCallbackToken>;
69
101
  //# sourceMappingURL=token.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/crypto/token.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB,eAAO,MAAM,SAAS;;;;EAE8F,CAAC;AACrH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD,4HAA4H;AAC5H,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;iBA2BmE,CAAC;AAC9F,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,kGAAkG;AAClG,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC,CAAC;AAE3E;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMjD;AAuBD;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE;IACP,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,IAAI,CAAC;IAChB,6GAA6G;IAC7G,QAAQ,EAAE,MAAM,CAAC;CAClB,GACA,OAAO,CAAC,MAAM,CAAC,CAajB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EAC1C,GAAG,EAAE,IAAI,EACT,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAqDxB"}
1
+ {"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/crypto/token.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,8GAA8G;AAC9G,eAAO,MAAM,UAAU,4BAA4B,CAAC;AAiBpD,eAAO,MAAM,SAAS;;;;EAE8F,CAAC;AACrH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AA2BnD,qHAAqH;AACrH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;iBASmE,CAAC;AAC9F,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAU3D,8EAA8E;AAC9E,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC,GAAG;IAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;CAAE,CAAC;AAE5E,kGAAkG;AAClG,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC,CAAC;AAE3E;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMjD;AA4DD;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE;IACP,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,IAAI,CAAC;IAChB,6GAA6G;IAC7G,QAAQ,EAAE,MAAM,CAAC;CAClB,GACA,OAAO,CAAC,MAAM,CAAC,CAwBjB;AA0ED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EAC1C,GAAG,EAAE,IAAI,EACT,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,CAAC,CAuBhC"}