@pithy-sh/email 0.3.3 → 0.3.5
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/capability.d.ts.map +1 -1
- package/dist/capability.js +3 -2
- package/dist/crypto/signingKey.d.ts +11 -5
- package/dist/crypto/signingKey.d.ts.map +1 -1
- package/dist/crypto/signingKey.js +13 -6
- package/dist/crypto/token.d.ts +27 -7
- package/dist/crypto/token.d.ts.map +1 -1
- package/dist/crypto/token.js +45 -10
- package/dist/data/tables.d.ts +7 -0
- package/dist/data/tables.d.ts.map +1 -1
- package/dist/data/tables.js +8 -1
- package/dist/http/callbacks.d.ts +17 -3
- package/dist/http/callbacks.d.ts.map +1 -1
- package/dist/http/callbacks.js +23 -11
- package/dist/provision/provisionEmail.d.ts +35 -10
- package/dist/provision/provisionEmail.d.ts.map +1 -1
- package/dist/provision/provisionEmail.js +27 -11
- package/dist/provision/resolveEmailConfig.d.ts +2 -2
- package/dist/provision/resolveEmailConfig.d.ts.map +1 -1
- package/dist/provision/resolveEmailConfig.js +3 -0
- package/dist/provision/settingsCheck.d.ts +2 -2
- package/dist/provision/settingsCheck.d.ts.map +1 -1
- package/dist/provision/settingsCheck.js +41 -16
- package/dist/templates/engine.d.ts.map +1 -1
- package/dist/templates/engine.js +2 -1
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/dist/workflows/hostEnv.d.ts +2 -0
- package/dist/workflows/hostEnv.d.ts.map +1 -1
- package/dist/workflows/hostEnv.js +21 -4
- package/dist/workflows/worker.d.ts +4 -1
- package/dist/workflows/worker.d.ts.map +1 -1
- package/package.json +3 -3
- package/src/capability.ts +5 -0
- package/src/crypto/signingKey.ts +33 -9
- package/src/crypto/token.ts +66 -9
- package/src/data/tables.ts +10 -0
- package/src/http/callbacks.ts +45 -11
- package/src/provision/provisionEmail.ts +53 -13
- package/src/provision/resolveEmailConfig.ts +14 -2
- package/src/provision/settingsCheck.ts +51 -19
- package/src/templates/engine.ts +2 -1
- package/src/version.generated.ts +1 -1
- package/src/workflows/hostEnv.ts +27 -5
- package/src/workflows/worker.ts +4 -2
- package/src/workflows/wrangler.jsonc +10 -2
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"resolveEmailConfig.d.ts","sourceRoot":"","sources":["../../src/provision/resolveEmailConfig.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;
|
|
1
|
+
{"version":3,"file":"resolveEmailConfig.d.ts","sourceRoot":"","sources":["../../src/provision/resolveEmailConfig.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,OAAO,KAAK,EACV,aAAa,EACb,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAGtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EAAE,KAAK,eAAe,EAAuB,MAAM,eAAe,CAAC;AAG1E;;;;;;GAMG;AACH,MAAM,WAAW,2BAA4B,SAAQ,oBAAoB;IACvE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,aAAa,EAAE,CAAC;IAC9B,UAAU,EAAE,oBAAoB,EAAE,CAAC;IACnC,qBAAqB,EAAE,uBAAuB,EAAE,CAAC;IACjD,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AA4BD,2GAA2G;AAC3G,eAAO,MAAM,qBAAqB,EAAE,gBAKnC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,QAAW,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiB9F;AAED,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,GAAG,EAAE,kBAAkB,GAAG,KAAK,CAAC;IAChC,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,+GAA+G;IAC/G,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+FAA+F;IAC/F,OAAO,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,KAAK,EAAE,UAAU,CAAC;IAClB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;CAK/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,2BAA2B,EACrC,MAAM,EAAE,iBAAiB,GACxB,2BAA2B,CAuC7B"}
|
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { EMAIL_LINK_SIGNING_KEY, EMAIL_LINK_SIGNING_KEY_BINDING, emailSigningRegistry } from "../crypto/signingKey.js";
|
|
3
4
|
import { emailCatalogVarName } from "../templates/messages.js";
|
|
4
5
|
import { emailRemoteBindings } from "./devDelivery.js";
|
|
5
6
|
import { EMAIL_CAPABILITY, suppressionDatabaseName } from "./provisionEmail.js";
|
|
6
7
|
import { EmailScheduleParams, EmailSendParams } from "../workflows/params.js";
|
|
7
8
|
import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
|
|
9
|
+
import { environmentScope } from "@pithy-sh/core/src/naming/provisionScope";
|
|
8
10
|
import { hostWorkflowsFor, resolveWorkflowHost } from "@pithy-sh/core/src/workflow/host";
|
|
9
11
|
import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
|
|
10
12
|
import { masterKeySecretName } from "@pithy-sh/secrets/src/provision/provisionSecrets";
|
|
@@ -109,6 +111,7 @@ function resolveEmailConfig(template, params) {
|
|
|
109
111
|
databaseNames: { EMAIL_SUPPRESSIONS: suppressionDatabaseName(project) },
|
|
110
112
|
secretsStoreId: storeId,
|
|
111
113
|
masterKeySecretName: masterKeySecretName(project, env),
|
|
114
|
+
secretNames: { [EMAIL_LINK_SIGNING_KEY_BINDING]: environmentScope(project, env).secretEntry(EMAIL_LINK_SIGNING_KEY, emailSigningRegistry[EMAIL_LINK_SIGNING_KEY].scope) },
|
|
112
115
|
vars: {
|
|
113
116
|
EMAIL_THEME: JSON.stringify(theme),
|
|
114
117
|
BASE_URL: baseUrl,
|
|
@@ -21,8 +21,8 @@ import type { EmailTheme } from "../templates/theme";
|
|
|
21
21
|
*
|
|
22
22
|
* ## The account tier asks the three things only the account knows
|
|
23
23
|
*
|
|
24
|
-
* Is the sending domain a zone here, does the suppression database exist, does the signing key have
|
|
25
|
-
*
|
|
24
|
+
* Is the sending domain a zone here, does the suppression database exist, does the signing key have its
|
|
25
|
+
* Secrets Store entry — and is it still in the D1 vault it moved out of. Each costs one Cloudflare call, each is skipped whole when the account cannot be reached, and
|
|
26
26
|
* none of them is inferable from a file in the checkout.
|
|
27
27
|
*
|
|
28
28
|
* Nothing here writes. Every finding names the command, the config key, or the one-time dashboard action
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"settingsCheck.d.ts","sourceRoot":"","sources":["../../src/provision/settingsCheck.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,wCAAwC,CAAC;
|
|
1
|
+
{"version":3,"file":"settingsCheck.d.ts","sourceRoot":"","sources":["../../src/provision/settingsCheck.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,wCAAwC,CAAC;AAMhD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,uGAAuG;AACvG,MAAM,WAAW,kBAAkB;IACjC,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AA2ND,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAK5E"}
|
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
-
import { EMAIL_LINK_SIGNING_KEY } from "../crypto/signingKey.js";
|
|
3
|
+
import { EMAIL_LINK_SIGNING_KEY, EMAIL_LINK_SIGNING_KEY_BINDING, emailSigningRegistry } from "../crypto/signingKey.js";
|
|
4
4
|
import { emailHostEnv } from "../workflows/hostEnv.js";
|
|
5
5
|
import { suppressionDatabaseName } from "./provisionEmail.js";
|
|
6
6
|
import { hostEnvFindings } from "@pithy-sh/core/src/capability/settings";
|
|
7
7
|
import "@pithy-sh/core/src/naming/domains";
|
|
8
|
+
import { environmentScope } from "@pithy-sh/core/src/naming/provisionScope";
|
|
8
9
|
import { checkHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
9
10
|
//#region src/provision/settingsCheck.ts
|
|
10
11
|
/**
|
|
@@ -22,6 +23,7 @@ function stubBindings() {
|
|
|
22
23
|
EMAIL_SUPPRESSIONS: d1,
|
|
23
24
|
SECRETS: d1,
|
|
24
25
|
SECRETS_ENCRYPTION_KEYS: "checked elsewhere",
|
|
26
|
+
[EMAIL_LINK_SIGNING_KEY_BINDING]: "checked elsewhere",
|
|
25
27
|
EMAIL: { send: () => void 0 },
|
|
26
28
|
EMAIL_SENDER: {
|
|
27
29
|
create: () => void 0,
|
|
@@ -124,10 +126,6 @@ function localForAddress(config) {
|
|
|
124
126
|
action: "Set `email({ fromAddress })` to an address on a domain you have onboarded onto Email Service."
|
|
125
127
|
}];
|
|
126
128
|
}
|
|
127
|
-
/** The last declared environment — the one a project-wide remedy is named for. */
|
|
128
|
-
function lastEnvironment(context) {
|
|
129
|
-
return context.environments.at(-1)?.name ?? "prod";
|
|
130
|
-
}
|
|
131
129
|
/** The account half: the zone, the suppression database, and the signing key. */
|
|
132
130
|
async function accountFindings(config, context) {
|
|
133
131
|
const findings = [];
|
|
@@ -143,23 +141,50 @@ async function accountFindings(config, context) {
|
|
|
143
141
|
setting: "EMAIL_SUPPRESSIONS",
|
|
144
142
|
environment: null,
|
|
145
143
|
problem: `No D1 database named ${suppressions} exists on this account.`,
|
|
146
|
-
action:
|
|
144
|
+
action: "Run `pithy email provision`. Nothing is suppressed until it exists."
|
|
147
145
|
});
|
|
148
146
|
for (const environment of context.environments) {
|
|
149
147
|
if (environment.name === "dev") continue;
|
|
150
|
-
|
|
151
|
-
name: "email-link-signing-key",
|
|
152
|
-
environment: environment.name
|
|
153
|
-
})) continue;
|
|
154
|
-
findings.push({
|
|
155
|
-
setting: EMAIL_LINK_SIGNING_KEY,
|
|
156
|
-
environment: environment.name,
|
|
157
|
-
problem: `The link-signing key has no value in ${environment.name}, so no tracking or unsubscribe link can be signed.`,
|
|
158
|
-
action: `Run \`pithy secrets provision --env ${environment.name}\`.`
|
|
159
|
-
});
|
|
148
|
+
findings.push(...await signingKeyFindings(context, environment.name));
|
|
160
149
|
}
|
|
161
150
|
return findings;
|
|
162
151
|
}
|
|
152
|
+
/**
|
|
153
|
+
* Where the link-signing key is in one deployed environment, and where it should not be (#596).
|
|
154
|
+
*
|
|
155
|
+
* **Two stores, two questions, and neither answers the other.** The key is a Secrets Store entry per
|
|
156
|
+
* environment: the one `pithy secrets provision` created, at the name `environmentScope(...).secretEntry`
|
|
157
|
+
* composes from the declaration's own scope. That is the question that says whether a link can be signed.
|
|
158
|
+
*
|
|
159
|
+
* The vault question is the migration. A project provisioned before the move holds the key as a D1 row,
|
|
160
|
+
* which nothing reads now — and which the move cannot carry: the row is sealed under a master key no
|
|
161
|
+
* command can read, and every link minted from it predates the audience claim the verifier requires. So the
|
|
162
|
+
* finding says plainly that those links are gone, and names the command that removes the row once the entry
|
|
163
|
+
* is serving. The path in full is in `docs/commands/secrets.md`.
|
|
164
|
+
*
|
|
165
|
+
* **What this sees:** a row under this registry name. A secret some other declaration moved off D1 has its
|
|
166
|
+
* own check to write, or none; nothing here walks the vault for strays, because the vault cannot be listed.
|
|
167
|
+
*/
|
|
168
|
+
async function signingKeyFindings(context, environment) {
|
|
169
|
+
const findings = [];
|
|
170
|
+
const entry = environmentScope(context.project, environment).secretEntry(EMAIL_LINK_SIGNING_KEY, emailSigningRegistry[EMAIL_LINK_SIGNING_KEY].scope);
|
|
171
|
+
if (!await context.account.storeEntry(entry)) findings.push({
|
|
172
|
+
setting: EMAIL_LINK_SIGNING_KEY,
|
|
173
|
+
environment,
|
|
174
|
+
problem: `The link-signing key has no Secrets Store entry in ${environment}, so no tracking or unsubscribe link can be signed.`,
|
|
175
|
+
action: "Run `pithy secrets provision`."
|
|
176
|
+
});
|
|
177
|
+
if (await context.account.vaultSecret({
|
|
178
|
+
name: "email-link-signing-key",
|
|
179
|
+
environment
|
|
180
|
+
})) findings.push({
|
|
181
|
+
setting: EMAIL_LINK_SIGNING_KEY,
|
|
182
|
+
environment,
|
|
183
|
+
problem: `The link-signing key is still held in ${environment}'s D1 vault, where nothing reads it. Links signed with it before the move no longer verify.`,
|
|
184
|
+
action: `Once the Secrets Store entry is bound and deployed, run \`pithy secrets rm ${EMAIL_LINK_SIGNING_KEY} --env ${environment} --backend d1\`. See docs/commands/secrets.md#moving-a-secret-off-d1.`
|
|
185
|
+
});
|
|
186
|
+
return findings;
|
|
187
|
+
}
|
|
163
188
|
/** Email's settings check, built from one composition's resolved config. Declared on the capability. */
|
|
164
189
|
function emailSettings(config) {
|
|
165
190
|
return {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/templates/engine.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAGrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI/C,OAAO,EAAE,KAAK,aAAa,EAAa,MAAM,YAAY,CAAC;AAE3D,OAAO,EAAE,KAAK,UAAU,EAAW,MAAM,SAAS,CAAC;AAEnD;;;;;;;;;;;;;;;GAeG;AAEH,6GAA6G;AAC7G,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAuH7C,2GAA2G;AAC3G,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,SAAS,EAAE,IAAI,CAAC;IAChB,iDAAiD;IACjD,YAAY,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,gGAAgG;AAChG,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,CAIrD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAE1D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,kEAAkE;AAClE,wBAAgB,aAAa,IAAI,aAAa,EAAE,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,UAAU,EACjB,UAAU,GAAE,UAAoB,GAC/B,MAAM,CASR;AAyDD;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,cAAc,EACzB,UAAU,GAAE,UAAoB,GAC/B,OAAO,CAAC,YAAY,CAAC,
|
|
1
|
+
{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/templates/engine.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAGrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI/C,OAAO,EAAE,KAAK,aAAa,EAAa,MAAM,YAAY,CAAC;AAE3D,OAAO,EAAE,KAAK,UAAU,EAAW,MAAM,SAAS,CAAC;AAEnD;;;;;;;;;;;;;;;GAeG;AAEH,6GAA6G;AAC7G,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAuH7C,2GAA2G;AAC3G,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,SAAS,EAAE,IAAI,CAAC;IAChB,iDAAiD;IACjD,YAAY,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,gGAAgG;AAChG,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,CAIrD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAE1D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,kEAAkE;AAClE,wBAAgB,aAAa,IAAI,aAAa,EAAE,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,UAAU,EACjB,UAAU,GAAE,UAAoB,GAC/B,MAAM,CASR;AAyDD;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,cAAc,EACzB,UAAU,GAAE,UAAoB,GAC/B,OAAO,CAAC,YAAY,CAAC,CA+DvB"}
|
package/dist/templates/engine.js
CHANGED
|
@@ -234,7 +234,8 @@ async function renderEmail(templateId, payload, theme, tracking, translator = EN
|
|
|
234
234
|
}, {
|
|
235
235
|
key: tracking.key,
|
|
236
236
|
kid: tracking.kid,
|
|
237
|
-
expiresAt: tracking.expiresAt
|
|
237
|
+
expiresAt: tracking.expiresAt,
|
|
238
|
+
audience: tracking.baseUrl
|
|
238
239
|
});
|
|
239
240
|
if (tracking.clickTracking) for (const link of entry.def.links) await rewriteLink(context, link.path, link.label, async (destination, label) => {
|
|
240
241
|
const token = await mint("click", {
|
|
@@ -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.3.
|
|
6
|
+
export declare const PACKAGE_VERSION = "0.3.5";
|
|
7
7
|
//# sourceMappingURL=version.generated.d.ts.map
|
|
@@ -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.3.
|
|
7
|
+
const PACKAGE_VERSION = "0.3.5";
|
|
8
8
|
//#endregion
|
|
9
9
|
export { PACKAGE_NAME, PACKAGE_VERSION };
|
|
@@ -11,6 +11,7 @@ export declare const EmailHostEnv: z.ZodObject<{
|
|
|
11
11
|
EMAIL_SUPPRESSIONS: z.ZodType<D1Database, unknown, z.core.$ZodTypeInternals<D1Database, unknown>>;
|
|
12
12
|
SECRETS: z.ZodType<D1Database, unknown, z.core.$ZodTypeInternals<D1Database, unknown>>;
|
|
13
13
|
SECRETS_ENCRYPTION_KEYS: z.ZodUnion<readonly [z.ZodString, z.ZodType<SecretBinding, unknown, z.core.$ZodTypeInternals<SecretBinding, unknown>>]>;
|
|
14
|
+
EMAIL_LINK_SIGNING_KEY: z.ZodUnion<readonly [z.ZodString, z.ZodType<SecretBinding, unknown, z.core.$ZodTypeInternals<SecretBinding, unknown>>]>;
|
|
14
15
|
EMAIL: z.ZodType<EmailSender, unknown, z.core.$ZodTypeInternals<EmailSender, unknown>>;
|
|
15
16
|
EMAIL_SENDER: z.ZodCustom<EmailSenderBinding, EmailSenderBinding>;
|
|
16
17
|
EMAIL_SCHEDULER: z.ZodType<{
|
|
@@ -80,6 +81,7 @@ export declare const emailHostEnv: import("@pithy-sh/core/src/workflow/hostEnv")
|
|
|
80
81
|
EMAIL_SUPPRESSIONS: z.ZodType<D1Database, unknown, z.core.$ZodTypeInternals<D1Database, unknown>>;
|
|
81
82
|
SECRETS: z.ZodType<D1Database, unknown, z.core.$ZodTypeInternals<D1Database, unknown>>;
|
|
82
83
|
SECRETS_ENCRYPTION_KEYS: z.ZodUnion<readonly [z.ZodString, z.ZodType<SecretBinding, unknown, z.core.$ZodTypeInternals<SecretBinding, unknown>>]>;
|
|
84
|
+
EMAIL_LINK_SIGNING_KEY: z.ZodUnion<readonly [z.ZodString, z.ZodType<SecretBinding, unknown, z.core.$ZodTypeInternals<SecretBinding, unknown>>]>;
|
|
83
85
|
EMAIL: z.ZodType<EmailSender, unknown, z.core.$ZodTypeInternals<EmailSender, unknown>>;
|
|
84
86
|
EMAIL_SENDER: z.ZodCustom<EmailSenderBinding, EmailSenderBinding>;
|
|
85
87
|
EMAIL_SCHEDULER: z.ZodType<{
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"hostEnv.d.ts","sourceRoot":"","sources":["../../src/workflows/hostEnv.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;
|
|
1
|
+
{"version":3,"file":"hostEnv.d.ts","sourceRoot":"","sources":["../../src/workflows/hostEnv.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAgFzD,sGAAsG;AACtG,eAAO,MAAM,YAAY;;;;;;;;;kBA+BiB,OAAO,CAAC,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4D6C,CAAC;AACxG,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,kGAAkG;AAClG,KAAK,kBAAkB,GAAG;IACxB,MAAM,CAAC,OAAO,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,EAAE,CAAA;SAAE,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClF,GAAG,qBAAqB,CAAC;AAO1B;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;;;;;;;kBAhFiB,OAAO,CAAC,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsHxD,CAAC"}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { EMAIL_LINK_SIGNING_KEY, EMAIL_LINK_SIGNING_KEY_BINDING } from "../crypto/signingKey.js";
|
|
3
4
|
import { EmailTheme, defaultTheme } from "../templates/theme.js";
|
|
4
5
|
import { z } from "zod";
|
|
5
6
|
import { defineHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
@@ -34,8 +35,18 @@ import { defineHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
|
34
35
|
* Node-safe on purpose. No `cloudflare:` import and no filesystem, so `pithy doctor` can import this
|
|
35
36
|
* without executing the Worker — the same constraint `@pithy-sh/core`'s host modules carry.
|
|
36
37
|
*/
|
|
37
|
-
/**
|
|
38
|
-
|
|
38
|
+
/**
|
|
39
|
+
* The command that writes every provisioned value here. Stated once so nine action lines cannot drift.
|
|
40
|
+
*
|
|
41
|
+
* No `--env`: it spans every declared environment in one run and declares no such flag, and a flag a
|
|
42
|
+
* command does not declare is refused (#594) — so a remedy naming one is a remedy that cannot be followed.
|
|
43
|
+
*/
|
|
44
|
+
const PROVISION = "pithy email provision";
|
|
45
|
+
/**
|
|
46
|
+
* The command that writes both host secrets below. No `--env`, for the same reason: `pithy secrets provision`
|
|
47
|
+
* provisions every declared environment in one run and declares no such flag.
|
|
48
|
+
*/
|
|
49
|
+
const SECRETS_PROVISION = "pithy secrets provision";
|
|
39
50
|
/** A binding `pithy email provision` wires into the resolved `wrangler.jsonc`. */
|
|
40
51
|
const binding = (name) => ({
|
|
41
52
|
kind: "binding",
|
|
@@ -76,8 +87,9 @@ const tunedNumber = (fallback) => z.coerce.number().int().positive().default(fal
|
|
|
76
87
|
const EmailHostEnv = z.object({
|
|
77
88
|
DB: d1Binding("The app database holding this environment's email jobs and events").describe("The app D1 database. The `pithy_email_jobs` and `pithy_email_events` tables live here, beside the adopter's own data. Bound by `pithy email provision`, which fills the id for the environment being deployed."),
|
|
78
89
|
EMAIL_SUPPRESSIONS: d1Binding("The shared suppression database every environment of this project binds").describe("The durable suppression D1 database — one per project, bound identically in every environment, so an unsubscribe or a hard bounce applies everywhere the project sends from. Named `<project>-global-email-suppressions`."),
|
|
79
|
-
SECRETS: d1Binding("The per-environment secrets database
|
|
90
|
+
SECRETS: d1Binding("The per-environment secrets database").describe("The per-environment secrets D1 database, bound on every prebuilt host that reads through `@pithy-sh/secrets`. The link-signing key is not in it: that is a Secrets Store entry, below (#596)."),
|
|
80
91
|
SECRETS_ENCRYPTION_KEYS: z.union([z.string().min(1), callable("get", "The master key binding")]).describe("The master key that decrypts the secrets database — a Cloudflare Secrets Store binding in a deployed environment, and the same name as a plain string in `.dev.vars` locally. The one secret read outside the `secretsStore` accessor, because it is what makes the accessor work."),
|
|
92
|
+
[EMAIL_LINK_SIGNING_KEY_BINDING]: z.union([z.string().min(1), callable("get", "The link-signing key binding")]).describe("The key every tracking and unsubscribe link is signed with — a Cloudflare Secrets Store entry for this environment, bound as `EMAIL_LINK_SIGNING_KEY`, and the same entry the app Worker verifies those links against. Locally it is the same name in `.dev.vars`. Without it no link can be signed, and a marketing send cannot render."),
|
|
81
93
|
EMAIL: callable("send", "The Cloudflare Email Service send binding").describe("The Cloudflare Email Service `send_email` binding — the only thing in the kit that puts a message on the wire. `wrangler dev` simulates it locally; `remote: true` (the default under `pithy dev`) sends for real from the developer's machine."),
|
|
82
94
|
EMAIL_SENDER: z.custom((value) => isCallable(value, "create") && isCallable(value, "get"), { error: "The send Workflow binding — it must both start an instance and answer about one." }).describe("This host's own send Workflow, same-script. Two calls, and both matter: `create` starts a batch, and `get` is how the scheduler asks whether the instance a stranded row names is still alive before re-driving it."),
|
|
83
95
|
EMAIL_SCHEDULER: callable("create", "The scheduler Workflow binding").describe("This host's own scheduler Workflow, same-script. Fired by the every-minute cron; it finds due jobs and fans them out into send batches."),
|
|
@@ -124,7 +136,12 @@ const emailHostEnv = defineHostEnv({
|
|
|
124
136
|
SECRETS_ENCRYPTION_KEYS: {
|
|
125
137
|
kind: "secret",
|
|
126
138
|
name: "SECRETS_ENCRYPTION_KEYS",
|
|
127
|
-
command:
|
|
139
|
+
command: SECRETS_PROVISION
|
|
140
|
+
},
|
|
141
|
+
[EMAIL_LINK_SIGNING_KEY_BINDING]: {
|
|
142
|
+
kind: "secret",
|
|
143
|
+
name: EMAIL_LINK_SIGNING_KEY,
|
|
144
|
+
command: SECRETS_PROVISION
|
|
128
145
|
},
|
|
129
146
|
EMAIL: binding("EMAIL"),
|
|
130
147
|
EMAIL_SENDER: binding("EMAIL_SENDER"),
|
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
|
|
4
4
|
import type { D1Database, ExecutionContext } from "@cloudflare/workers-types";
|
|
5
|
-
import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
|
|
5
|
+
import type { SecretBinding, SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
|
|
6
|
+
import { EMAIL_LINK_SIGNING_KEY_BINDING } from "../crypto/signingKey";
|
|
6
7
|
import type { SendWorkflowBinding } from "../send/enqueue";
|
|
7
8
|
import type { EmailSender } from "../send/sender";
|
|
8
9
|
import type { SendWorkflowInstances } from "./instances";
|
|
@@ -39,6 +40,8 @@ import { type BatchSendReport } from "./sendBatch";
|
|
|
39
40
|
export interface EmailWorkerEnv extends SecretsStoreEnv {
|
|
40
41
|
/** The app database the per-environment jobs/events tables live in. */
|
|
41
42
|
DB: D1Database;
|
|
43
|
+
/** The link-signing key: this environment's Secrets Store entry, or its `.dev.vars` string locally (#596). */
|
|
44
|
+
[EMAIL_LINK_SIGNING_KEY_BINDING]: SecretBinding | string;
|
|
42
45
|
/** The shared, durable suppression database. */
|
|
43
46
|
EMAIL_SUPPRESSIONS: D1Database;
|
|
44
47
|
/** The Cloudflare Email Service send binding. */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/workflows/worker.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE/F,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAG9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;
|
|
1
|
+
{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/workflows/worker.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE/F,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAG9E,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAEzF,OAAO,EAAE,8BAA8B,EAA4C,MAAM,sBAAsB,CAAC;AAGhH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAKlD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,KAAK,eAAe,EAAoC,MAAM,aAAa,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,uEAAuE;IACvE,EAAE,EAAE,UAAU,CAAC;IACf,8GAA8G;IAC9G,CAAC,8BAA8B,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IACzD,gDAAgD;IAChD,kBAAkB,EAAE,UAAU,CAAC;IAC/B,iDAAiD;IACjD,KAAK,EAAE,WAAW,CAAC;IACnB,gGAAgG;IAChG,YAAY,EAAE,mBAAmB,GAAG,qBAAqB,CAAC;IAC1D,yDAAyD;IACzD,eAAe,EAAE;QAAE,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC;IAChD,+GAA+G;IAC/G,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,CAAC,UAAU,EAAE,kBAAkB,MAAM,EAAE,GAAG,OAAO,CAAC;IAClD,QAAQ,EAAE,MAAM,CAAC;IAEjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AA2ED;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,kBAAkB,CAAC,cAAc,EAAE;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;IAI9E,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAM3G;CACF;AAED,0FAA0F;AAC1F,qBAAa,sBAAuB,SAAQ,kBAAkB,CAAC,cAAc,EAAE,OAAO,CAAC;IACtE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpF;CACF;;IAGC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,SAAS,cAAc,OAAO,OAAO,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAOzE;;;;;;;;OAQG;IACG,KAAK,UAAU,OAAO,OAAO,cAAc,OAAO,gBAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pithy-sh/email",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.5",
|
|
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.2.
|
|
45
|
+
"@pithy-sh/core": "^0.7.0",
|
|
46
|
+
"@pithy-sh/secrets": "^0.2.5",
|
|
47
47
|
"hono": "^4.13.2",
|
|
48
48
|
"kysely": "^0.29.0",
|
|
49
49
|
"zod": "^4.4.0"
|
package/src/capability.ts
CHANGED
|
@@ -12,6 +12,7 @@ import {
|
|
|
12
12
|
type EmailSuppressionDatabase,
|
|
13
13
|
emailDatabase,
|
|
14
14
|
emailSuppressionDatabase,
|
|
15
|
+
emailSuppressionsRetainedTables,
|
|
15
16
|
emailSuppressionTables,
|
|
16
17
|
emailTables,
|
|
17
18
|
} from "./data/tables";
|
|
@@ -262,6 +263,10 @@ export function email(config: EmailConfigInput): EmailCapability {
|
|
|
262
263
|
migrations: {
|
|
263
264
|
"0001_suppressions": email_0001_suppressions,
|
|
264
265
|
},
|
|
266
|
+
// Every address that bounced, complained or unsubscribed. Dropping it is not a schema change — the
|
|
267
|
+
// next send goes to people who asked not to be mailed, and the list cannot be rebuilt from anywhere.
|
|
268
|
+
// Declared retained, so no `down` runs against it while it holds rows unless counted (#588).
|
|
269
|
+
retained: emailSuppressionsRetainedTables,
|
|
265
270
|
},
|
|
266
271
|
},
|
|
267
272
|
/**
|
package/src/crypto/signingKey.ts
CHANGED
|
@@ -1,31 +1,55 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
|
+
import { secretBindingName } from "@pithy-sh/secrets/src/env/bindingName";
|
|
4
5
|
import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
|
|
5
6
|
import { defineSecretRegistry } from "@pithy-sh/secrets/src/registry";
|
|
6
7
|
import type { VersionedSecret } from "@pithy-sh/secrets/src/secretsStore";
|
|
7
8
|
import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
|
|
8
9
|
|
|
9
10
|
/**
|
|
10
|
-
* The link-signing key
|
|
11
|
-
* by name through its own minimal registry — `secretsStore` reads the same
|
|
12
|
-
*
|
|
11
|
+
* The link-signing key: a rotatable secret in the **Cloudflare Secrets Store**, one entry per environment.
|
|
12
|
+
* Email resolves it by name through its own minimal registry — `secretsStore` reads the same binding
|
|
13
|
+
* whichever registry names it, so email never needs the project-wide registry to sign or verify a link.
|
|
13
14
|
*/
|
|
14
15
|
export const EMAIL_LINK_SIGNING_KEY = "email-link-signing-key";
|
|
15
16
|
|
|
17
|
+
/**
|
|
18
|
+
* The binding a Worker reads the link-signing key through: `EMAIL_LINK_SIGNING_KEY` (#603). Derived, never
|
|
19
|
+
* spelled — the stanza `pithy secrets provision` writes and the reader in `@pithy-sh/secrets` both call
|
|
20
|
+
* `secretBindingName`, and so does this.
|
|
21
|
+
*/
|
|
22
|
+
export const EMAIL_LINK_SIGNING_KEY_BINDING = secretBindingName(EMAIL_LINK_SIGNING_KEY);
|
|
23
|
+
|
|
16
24
|
/** The minimal registry email uses to resolve its signing key. Rotatable so old links verify after rotation. */
|
|
17
25
|
export const emailSigningRegistry = defineSecretRegistry({
|
|
18
|
-
// Mintable for dev: the key signs links this app both mints and verifies, so any random string
|
|
19
|
-
// serves. Nothing else names it, so without `devValue` the first tracked link is the first anyone
|
|
20
|
-
// hears of it — and by then the mail is in an inbox.
|
|
21
26
|
[EMAIL_LINK_SIGNING_KEY]: {
|
|
22
|
-
|
|
23
|
-
|
|
27
|
+
// **`cf-secrets-store`, because of all the kit's secrets this is the one whose loss outlives the
|
|
28
|
+
// system (#596).** Lose a session secret and everyone signs in again; lose this and every link already
|
|
29
|
+
// in somebody's inbox stops verifying, and nothing can reissue mail that was sent. As a `d1` row it sat
|
|
30
|
+
// inside the vault — where a rollback, a `seed --redo` or a teardown agreed to by an operator reaches —
|
|
31
|
+
// and on 2026-09-14 a staging rollback took it. A Secrets Store entry lives outside every D1, so none
|
|
32
|
+
// of those can.
|
|
33
|
+
backend: "cf-secrets-store",
|
|
34
|
+
// **`environment`, never `global` — decided on #596.** Every link points at the origin that minted it,
|
|
35
|
+
// so it is verified by the environment that signed it, and nothing needs a staging link to verify in
|
|
36
|
+
// production. A shared key would make the boundary decorative: a staging-minted unsubscribe would be a
|
|
37
|
+
// valid write into the suppression list both environments bind, recorded as production's. One entry
|
|
38
|
+
// per environment, none shared. (The token's `aud` claim holds the same line if an entry is ever
|
|
39
|
+
// misconfigured as shared — see `crypto/token.ts`.)
|
|
40
|
+
//
|
|
41
|
+
// `global` on `d1` was also the failure mode the move removes: N copies under N master keys that must
|
|
42
|
+
// stay identical, where losing one could only be repaired by destroying all of them.
|
|
43
|
+
scope: "environment",
|
|
24
44
|
rotatable: true,
|
|
25
45
|
valueType: "text",
|
|
46
|
+
// Mintable for dev: the key signs links this app both mints and verifies, so any random string
|
|
47
|
+
// serves. Nothing else names it, so without `devValue` the first tracked link is the first anyone
|
|
48
|
+
// hears of it — and by then the mail is in an inbox.
|
|
26
49
|
devValue: "random",
|
|
27
50
|
// Arbitrary in production for the same reason it is arbitrary in dev: this app mints the links and
|
|
28
|
-
// this app verifies them. So it is `minted` in every environment
|
|
51
|
+
// this app verifies them. So it is `minted` in every environment — `pithy secrets provision` creates
|
|
52
|
+
// the entry when it is absent and never replaces one — and `local` to replace.
|
|
29
53
|
origin: { kind: "minted", recipe: { kind: "random", bytes: 32, encoding: "base64url" } },
|
|
30
54
|
rotation: { kind: "local" },
|
|
31
55
|
},
|
package/src/crypto/token.ts
CHANGED
|
@@ -11,6 +11,14 @@ import { EmailInvalidTokenError } from "../error/errors";
|
|
|
11
11
|
* acts. The signing secret is a **rotatable** key from `@pithy-sh/secrets`; every token records the
|
|
12
12
|
* key version (`kid`) it was signed with, so a link in a months-old email still verifies against the
|
|
13
13
|
* retained version set after a rotation — and is rejected once that version is pruned.
|
|
14
|
+
*
|
|
15
|
+
* **A token also names the origin it was minted for (`aud`), and only that origin may act on it (#596).**
|
|
16
|
+
* A link points at the environment that minted it, so nothing about the product needs a staging token to
|
|
17
|
+
* verify on production. The key is per environment, and that alone would keep them apart — for exactly as
|
|
18
|
+
* long as nobody misconfigures one as shared. The claim is what makes that misconfiguration harmless rather
|
|
19
|
+
* than a staging token that 302s through production's domain, records a staging job into production's
|
|
20
|
+
* events, and writes a staging unsubscribe into the suppression list both environments bind, stamped as
|
|
21
|
+
* production's. The key authorizes; the audience says where.
|
|
14
22
|
*/
|
|
15
23
|
|
|
16
24
|
const encoder = new TextEncoder();
|
|
@@ -21,11 +29,20 @@ export const TokenKind = z
|
|
|
21
29
|
.describe("Which callback a token authorizes: a tracked link `click`, an open-pixel `open`, or an `unsubscribe`.");
|
|
22
30
|
export type TokenKind = z.output<typeof TokenKind>;
|
|
23
31
|
|
|
24
|
-
/** The signed claims a callback token carries. `kid`/`exp`/`v` are set by `mintToken`; the rest are caller claims. */
|
|
32
|
+
/** The signed claims a callback token carries. `kid`/`exp`/`v`/`aud` are set by `mintToken`; the rest are caller claims. */
|
|
25
33
|
export const CallbackToken = z
|
|
26
34
|
.object({
|
|
27
|
-
v: z
|
|
35
|
+
v: z
|
|
36
|
+
.literal(2)
|
|
37
|
+
.describe(
|
|
38
|
+
"Token format version, so the scheme can evolve without ambiguity. `2` added `aud`; a `1` token names no audience and is refused.",
|
|
39
|
+
),
|
|
28
40
|
kid: z.string().describe("The signing-key version this token was signed with; selects the key to verify against."),
|
|
41
|
+
aud: z
|
|
42
|
+
.string()
|
|
43
|
+
.describe(
|
|
44
|
+
"The origin this token was minted for — the scheme, host and port its links point at. It verifies at that origin and nowhere else.",
|
|
45
|
+
),
|
|
29
46
|
kind: TokenKind.describe("Which callback this token authorizes."),
|
|
30
47
|
jobId: z.string().describe("The `pithy_email_jobs.id` this token is bound to."),
|
|
31
48
|
recipient: z.string().describe("The recipient address the callback is recorded against."),
|
|
@@ -44,7 +61,23 @@ export const CallbackToken = z
|
|
|
44
61
|
export type CallbackToken = z.output<typeof CallbackToken>;
|
|
45
62
|
|
|
46
63
|
/** The caller-supplied claims for a token — everything except the fields `mintToken` fills in. */
|
|
47
|
-
export type TokenClaims = Omit<CallbackToken, "v" | "kid" | "exp">;
|
|
64
|
+
export type TokenClaims = Omit<CallbackToken, "v" | "kid" | "exp" | "aud">;
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* The audience a URL names: its origin, and nothing else.
|
|
68
|
+
*
|
|
69
|
+
* One function for both sides, so a minting side that kept a path or a trailing slash and a verifying side
|
|
70
|
+
* that did not cannot come to two strings for one place. A URL that will not parse is refused as an invalid
|
|
71
|
+
* token rather than thrown as a `TypeError`: on the verifying side it is the request's own URL, and on the
|
|
72
|
+
* minting side it is `BASE_URL`, which the host has already validated as a URL.
|
|
73
|
+
*/
|
|
74
|
+
export function tokenAudience(url: string): string {
|
|
75
|
+
try {
|
|
76
|
+
return new URL(url).origin;
|
|
77
|
+
} catch (cause) {
|
|
78
|
+
throw new EmailInvalidTokenError({ detail: "token audience is not a URL" }, { cause });
|
|
79
|
+
}
|
|
80
|
+
}
|
|
48
81
|
|
|
49
82
|
function base64UrlEncode(bytes: Uint8Array): string {
|
|
50
83
|
let binary = "";
|
|
@@ -74,13 +107,21 @@ async function importKey(secret: string): Promise<CryptoKey> {
|
|
|
74
107
|
*/
|
|
75
108
|
export async function mintToken(
|
|
76
109
|
claims: TokenClaims,
|
|
77
|
-
options: {
|
|
110
|
+
options: {
|
|
111
|
+
key: string;
|
|
112
|
+
kid: string;
|
|
113
|
+
expiresAt: Date;
|
|
114
|
+
/** Any URL on the origin the links point at — `BASE_URL`. Reduced to its origin by {@link tokenAudience}. */
|
|
115
|
+
audience: string;
|
|
116
|
+
},
|
|
78
117
|
): Promise<string> {
|
|
79
118
|
const payload: CallbackToken = {
|
|
80
|
-
|
|
119
|
+
...claims,
|
|
120
|
+
// After the caller's claims, so nothing spread in can overwrite what this function is the authority on.
|
|
121
|
+
v: 2,
|
|
81
122
|
kid: options.kid,
|
|
123
|
+
aud: tokenAudience(options.audience),
|
|
82
124
|
exp: Math.floor(options.expiresAt.getTime() / 1000),
|
|
83
|
-
...claims,
|
|
84
125
|
};
|
|
85
126
|
const payloadB64 = base64UrlEncode(encoder.encode(JSON.stringify(payload)));
|
|
86
127
|
const key = await importKey(options.key);
|
|
@@ -91,14 +132,23 @@ export async function mintToken(
|
|
|
91
132
|
/**
|
|
92
133
|
* Verify a token against the valid signing-key version set (`@pithy-sh/secrets`' `getVersions` shape)
|
|
93
134
|
* and return its claims. Rejects — as `email/invalid_token` — a malformed token, an unknown/pruned
|
|
94
|
-
* `kid`, a bad signature (constant-time via `crypto.subtle.verify`),
|
|
95
|
-
* is deliberate: structure, then signature, then
|
|
96
|
-
* check.
|
|
135
|
+
* `kid`, a bad signature (constant-time via `crypto.subtle.verify`), a token minted for another origin,
|
|
136
|
+
* or an expired token. The order is deliberate: structure, then signature, then audience, then expiry,
|
|
137
|
+
* so a forged token never reaches a claim check.
|
|
138
|
+
*
|
|
139
|
+
* `audience` is **required**, and is the URL the token arrived on — the request's own. A verifier that
|
|
140
|
+
* could omit it would be a verifier that accepts every origin, which is the hole the claim closes.
|
|
141
|
+
*
|
|
142
|
+
* **What the check cannot see:** where the caller got the URL. It compares against the string it is handed,
|
|
143
|
+
* so a caller that passed a value read out of the token, or a header a client controls, would pass every
|
|
144
|
+
* token. `http/callbacks.ts` hands it the request's own URL, and its route test plants a staging token on
|
|
145
|
+
* each route to hold that; a new verifying caller needs the same.
|
|
97
146
|
*/
|
|
98
147
|
export async function verifyToken(
|
|
99
148
|
token: string,
|
|
100
149
|
keys: { versions: Record<string, string> },
|
|
101
150
|
now: Date,
|
|
151
|
+
audience: string,
|
|
102
152
|
): Promise<CallbackToken> {
|
|
103
153
|
const parts = token.split(".");
|
|
104
154
|
if (parts.length !== 2 || !parts[0] || !parts[1]) {
|
|
@@ -140,6 +190,13 @@ export async function verifyToken(
|
|
|
140
190
|
throw new EmailInvalidTokenError({ detail: "token signature did not verify" });
|
|
141
191
|
}
|
|
142
192
|
|
|
193
|
+
const expected = tokenAudience(audience);
|
|
194
|
+
if (parsed.data.aud !== expected) {
|
|
195
|
+
throw new EmailInvalidTokenError({
|
|
196
|
+
detail: `token was minted for '${parsed.data.aud}' and presented at '${expected}'`,
|
|
197
|
+
});
|
|
198
|
+
}
|
|
199
|
+
|
|
143
200
|
if (parsed.data.exp * 1000 <= now.getTime()) {
|
|
144
201
|
throw new EmailInvalidTokenError({ detail: "token has expired" });
|
|
145
202
|
}
|
package/src/data/tables.ts
CHANGED
|
@@ -28,6 +28,16 @@ export type EmailTables = typeof emailTables;
|
|
|
28
28
|
export const emailSuppressionTables = {
|
|
29
29
|
pithyEmailSuppressions: EmailSuppression,
|
|
30
30
|
};
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* The suppression list, declared **retained**: every address that bounced, complained or unsubscribed, which
|
|
34
|
+
* cannot be rebuilt from anywhere. One constant for the capability's declaration (#588) and for the CLI's
|
|
35
|
+
* teardown, which counts it before deleting the database (#591) — a second copy that drifted would count
|
|
36
|
+
* nothing and delete the list.
|
|
37
|
+
*/
|
|
38
|
+
export const emailSuppressionsRetainedTables = [
|
|
39
|
+
"pithyEmailSuppressions",
|
|
40
|
+
] as const satisfies readonly (keyof typeof emailSuppressionTables)[];
|
|
31
41
|
export type EmailSuppressionTables = typeof emailSuppressionTables;
|
|
32
42
|
|
|
33
43
|
/** The typed Kysely database over the per-environment email tables (jobs + events). */
|