@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.
- package/README.md +2 -0
- package/dist/bounce/handler.d.ts +22 -2
- package/dist/bounce/handler.d.ts.map +1 -1
- package/dist/bounce/handler.js +60 -17
- package/dist/capability.d.ts +12 -0
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +25 -15
- 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 +67 -21
- package/dist/http/schemas.d.ts +41 -13
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +38 -15
- package/dist/jobs/read.d.ts +12 -9
- package/dist/jobs/read.d.ts.map +1 -1
- package/dist/jobs/read.js +6 -5
- package/dist/migrations/0002_job_filters.d.ts +15 -0
- package/dist/migrations/0002_job_filters.d.ts.map +1 -0
- package/dist/migrations/0002_job_filters.js +25 -0
- package/dist/send/enqueue.d.ts +26 -3
- package/dist/send/enqueue.d.ts.map +1 -1
- package/dist/send/enqueue.js +25 -2
- package/dist/send/errorMapping.d.ts +15 -20
- package/dist/send/errorMapping.d.ts.map +1 -1
- package/dist/send/errorMapping.js +33 -27
- package/dist/send/runSend.d.ts +2 -2
- package/dist/send/runSend.d.ts.map +1 -1
- package/dist/send/runSend.js +1 -1
- package/dist/send/suppression.d.ts +4 -0
- package/dist/send/suppression.d.ts.map +1 -1
- package/dist/send/suppression.js +4 -0
- 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/bounce/handler.ts +84 -32
- package/src/capability.ts +47 -27
- 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 +96 -28
- package/src/http/schemas.ts +75 -24
- package/src/jobs/read.ts +14 -9
- package/src/migrations/0002_job_filters.ts +35 -0
- package/src/send/enqueue.ts +52 -5
- package/src/send/errorMapping.ts +45 -38
- package/src/send/runSend.ts +6 -7
- package/src/send/suppression.ts +13 -0
- package/src/templates/engine.ts +1 -1
- 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
|
package/dist/bounce/handler.d.ts
CHANGED
|
@@ -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;
|
|
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"}
|
package/dist/bounce/handler.js
CHANGED
|
@@ -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
|
|
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
|
-
/**
|
|
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
|
|
69
|
-
const
|
|
70
|
-
|
|
71
|
-
|
|
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
|
-
|
|
79
|
-
|
|
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 };
|
package/dist/capability.d.ts
CHANGED
|
@@ -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**.
|
package/dist/capability.d.ts.map
CHANGED
|
@@ -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;
|
|
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"}
|
package/dist/capability.js
CHANGED
|
@@ -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
|
-
|
|
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: {
|
|
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
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
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;;;;;;;;;;;;;;;;;;;;;;;
|
|
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"}
|
package/dist/crypto/token.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
41
|
-
*
|
|
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
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
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<
|
|
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;
|
|
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"}
|