@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.
Files changed (46) hide show
  1. package/dist/capability.d.ts.map +1 -1
  2. package/dist/capability.js +3 -2
  3. package/dist/crypto/signingKey.d.ts +11 -5
  4. package/dist/crypto/signingKey.d.ts.map +1 -1
  5. package/dist/crypto/signingKey.js +13 -6
  6. package/dist/crypto/token.d.ts +27 -7
  7. package/dist/crypto/token.d.ts.map +1 -1
  8. package/dist/crypto/token.js +45 -10
  9. package/dist/data/tables.d.ts +7 -0
  10. package/dist/data/tables.d.ts.map +1 -1
  11. package/dist/data/tables.js +8 -1
  12. package/dist/http/callbacks.d.ts +17 -3
  13. package/dist/http/callbacks.d.ts.map +1 -1
  14. package/dist/http/callbacks.js +23 -11
  15. package/dist/provision/provisionEmail.d.ts +35 -10
  16. package/dist/provision/provisionEmail.d.ts.map +1 -1
  17. package/dist/provision/provisionEmail.js +27 -11
  18. package/dist/provision/resolveEmailConfig.d.ts +2 -2
  19. package/dist/provision/resolveEmailConfig.d.ts.map +1 -1
  20. package/dist/provision/resolveEmailConfig.js +3 -0
  21. package/dist/provision/settingsCheck.d.ts +2 -2
  22. package/dist/provision/settingsCheck.d.ts.map +1 -1
  23. package/dist/provision/settingsCheck.js +41 -16
  24. package/dist/templates/engine.d.ts.map +1 -1
  25. package/dist/templates/engine.js +2 -1
  26. package/dist/version.generated.d.ts +1 -1
  27. package/dist/version.generated.js +1 -1
  28. package/dist/workflows/hostEnv.d.ts +2 -0
  29. package/dist/workflows/hostEnv.d.ts.map +1 -1
  30. package/dist/workflows/hostEnv.js +21 -4
  31. package/dist/workflows/worker.d.ts +4 -1
  32. package/dist/workflows/worker.d.ts.map +1 -1
  33. package/package.json +3 -3
  34. package/src/capability.ts +5 -0
  35. package/src/crypto/signingKey.ts +33 -9
  36. package/src/crypto/token.ts +66 -9
  37. package/src/data/tables.ts +10 -0
  38. package/src/http/callbacks.ts +45 -11
  39. package/src/provision/provisionEmail.ts +53 -13
  40. package/src/provision/resolveEmailConfig.ts +14 -2
  41. package/src/provision/settingsCheck.ts +51 -19
  42. package/src/templates/engine.ts +2 -1
  43. package/src/version.generated.ts +1 -1
  44. package/src/workflows/hostEnv.ts +27 -5
  45. package/src/workflows/worker.ts +4 -2
  46. 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;AACtE,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;AAEtE,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,kGAAkG;IAClG,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,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,CA6B7B"}
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 a
25
- * value. Each costs one Cloudflare call, each is skipped whole when the account cannot be reached, and
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;AAKhD,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;AA4LD,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAK5E"}
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: `Run \`pithy email provision --env ${lastEnvironment(context)}\`. Nothing is suppressed until it exists.`
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
- if (await context.account.secret({
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,CA8DvB"}
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"}
@@ -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.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.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;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAqEzD,sGAAsG;AACtG,eAAO,MAAM,YAAY;;;;;;;;kBA0BiB,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAiHxD,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
- /** The command that writes every provisioned value here. Stated once so nine action lines cannot drift. */
38
- const PROVISION = "pithy email provision --env <env>";
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 the link-signing key is read from").describe("The per-environment secrets D1 database. The link-signing key is stored here as an encrypted row and read through `@pithy-sh/secrets`; without it, tracking and unsubscribe links cannot be signed."),
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: "pithy secrets provision --env <env>"
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;AAK1E,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,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"}
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",
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.6.1",
46
- "@pithy-sh/secrets": "^0.2.3",
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
  /**
@@ -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 lives in `@pithy-sh/secrets` as a rotatable, global secret. Email resolves it
11
- * by name through its own minimal registry — `secretsStore` reads the same encrypted D1 row regardless
12
- * of which registry names it, so email never needs the project-wide registry to sign or verify a link.
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
- backend: "d1",
23
- scope: "global",
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, and `local` to replace.
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
  },
@@ -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.literal(1).describe("Token format version, so the scheme can evolve without ambiguity."),
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: { key: string; kid: string; expiresAt: Date },
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
- v: 1,
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`), or an expired token. The order
95
- * is deliberate: structure, then signature, then expiry, so a forged token never reaches the expiry
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
  }
@@ -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). */