@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
package/src/http/callbacks.ts
CHANGED
|
@@ -47,6 +47,10 @@ import { CallbackTokenParam, UnsubscribeQuery } from "./schemas";
|
|
|
47
47
|
* No route reads a body, the one-click POST included: RFC 8058 fixes its body to a constant, so parsing
|
|
48
48
|
* it could only ever restate what the method and the signed token already say.
|
|
49
49
|
*
|
|
50
|
+
* Every token names the origin it was minted for, and a handler refuses one presented anywhere else — see
|
|
51
|
+
* `crypto/token`'s `aud`. That is what keeps a key misconfigured as shared from letting a staging link act
|
|
52
|
+
* on production's routes.
|
|
53
|
+
*
|
|
50
54
|
* The per-request handlers take the signing-key version set directly so they are unit-testable without
|
|
51
55
|
* standing up the secrets store; `registerCallbacks` is the thin shell that resolves the keys from the
|
|
52
56
|
* worker env (via `@pithy-sh/secrets`) and the database from the `DB` binding.
|
|
@@ -66,9 +70,29 @@ const PIXEL = Uint8Array.from(
|
|
|
66
70
|
(c) => c.charCodeAt(0),
|
|
67
71
|
);
|
|
68
72
|
|
|
73
|
+
/**
|
|
74
|
+
* Where a token was presented: the URL of the request carrying it. The token's `aud` has to name this
|
|
75
|
+
* origin, so a link minted by one environment cannot act on another's routes even under a shared key.
|
|
76
|
+
*
|
|
77
|
+
* The request's own URL rather than `email({ baseUrl })`: that config value is one string composed for
|
|
78
|
+
* whichever environment the config was loaded under, while the request is, by construction, at the origin
|
|
79
|
+
* this Worker is serving.
|
|
80
|
+
*/
|
|
81
|
+
export interface CallbackRequest {
|
|
82
|
+
/** The raw callback token from the path. */
|
|
83
|
+
token: string;
|
|
84
|
+
/** The URL the request arrived on. Only its origin is compared. */
|
|
85
|
+
url: string;
|
|
86
|
+
}
|
|
87
|
+
|
|
69
88
|
/** Verify a token and assert its kind, or throw `email/invalid_token`. */
|
|
70
|
-
async function verify(
|
|
71
|
-
|
|
89
|
+
async function verify(
|
|
90
|
+
keys: SigningKeys,
|
|
91
|
+
request: CallbackRequest,
|
|
92
|
+
expected: TokenKind,
|
|
93
|
+
now: Date,
|
|
94
|
+
): Promise<CallbackToken> {
|
|
95
|
+
const claims = await verifyToken(request.token, keys, now, request.url);
|
|
72
96
|
if (claims.kind !== expected) {
|
|
73
97
|
throw new EmailInvalidTokenError({ detail: `token kind '${claims.kind}' does not match callback '${expected}'` });
|
|
74
98
|
}
|
|
@@ -76,8 +100,13 @@ async function verify(keys: SigningKeys, token: string, expected: TokenKind, now
|
|
|
76
100
|
}
|
|
77
101
|
|
|
78
102
|
/** Handle a click: record it, then 302-redirect to the signed http(s) destination. */
|
|
79
|
-
export async function handleClick(
|
|
80
|
-
|
|
103
|
+
export async function handleClick(
|
|
104
|
+
db: EmailDatabase,
|
|
105
|
+
keys: SigningKeys,
|
|
106
|
+
request: CallbackRequest,
|
|
107
|
+
now: Date,
|
|
108
|
+
): Promise<Response> {
|
|
109
|
+
const claims = await verify(keys, request, "click", now);
|
|
81
110
|
const destination = claims.destination ?? "";
|
|
82
111
|
if (!/^https?:\/\//i.test(destination)) {
|
|
83
112
|
throw new EmailInvalidTokenError({ detail: "click token has no http(s) destination" });
|
|
@@ -98,8 +127,13 @@ export async function handleClick(db: EmailDatabase, keys: SigningKeys, token: s
|
|
|
98
127
|
}
|
|
99
128
|
|
|
100
129
|
/** Handle an open: record it, return the 1×1 pixel. */
|
|
101
|
-
export async function handleOpen(
|
|
102
|
-
|
|
130
|
+
export async function handleOpen(
|
|
131
|
+
db: EmailDatabase,
|
|
132
|
+
keys: SigningKeys,
|
|
133
|
+
request: CallbackRequest,
|
|
134
|
+
now: Date,
|
|
135
|
+
): Promise<Response> {
|
|
136
|
+
const claims = await verify(keys, { ...request, token: request.token.replace(/\.png$/i, "") }, "open", now);
|
|
103
137
|
await recordEvent(
|
|
104
138
|
db,
|
|
105
139
|
{
|
|
@@ -126,12 +160,12 @@ export async function handleUnsubscribe(
|
|
|
126
160
|
db: EmailDatabase,
|
|
127
161
|
suppressionDb: EmailSuppressionDatabase,
|
|
128
162
|
keys: SigningKeys,
|
|
129
|
-
|
|
163
|
+
request: CallbackRequest,
|
|
130
164
|
now: Date,
|
|
131
165
|
reason?: string,
|
|
132
166
|
environment?: string,
|
|
133
167
|
): Promise<Response> {
|
|
134
|
-
const claims = await verify(keys,
|
|
168
|
+
const claims = await verify(keys, request, "unsubscribe", now);
|
|
135
169
|
const recipient = normalizeAddress(claims.recipient);
|
|
136
170
|
const detail = reason ? reason.slice(0, 200) : "unsubscribe link";
|
|
137
171
|
await suppress(
|
|
@@ -170,12 +204,12 @@ export function registerCallbacks(app: Hono<PithyHonoEnv>): void {
|
|
|
170
204
|
|
|
171
205
|
app.get(`${CALLBACK_BASE}/c/:token`, zValidator("param", CallbackTokenParam, validationHook), async (c) => {
|
|
172
206
|
const { db, keys } = await setup(c.env as unknown as CallbackEnv);
|
|
173
|
-
return handleClick(db, keys, c.req.valid("param").token, new Date());
|
|
207
|
+
return handleClick(db, keys, { token: c.req.valid("param").token, url: c.req.url }, new Date());
|
|
174
208
|
});
|
|
175
209
|
|
|
176
210
|
app.get(`${CALLBACK_BASE}/o/:token`, zValidator("param", CallbackTokenParam, validationHook), async (c) => {
|
|
177
211
|
const { db, keys } = await setup(c.env as unknown as CallbackEnv);
|
|
178
|
-
return handleOpen(db, keys, c.req.valid("param").token, new Date());
|
|
212
|
+
return handleOpen(db, keys, { token: c.req.valid("param").token, url: c.req.url }, new Date());
|
|
179
213
|
});
|
|
180
214
|
|
|
181
215
|
app.on(
|
|
@@ -190,7 +224,7 @@ export function registerCallbacks(app: Hono<PithyHonoEnv>): void {
|
|
|
190
224
|
db,
|
|
191
225
|
suppressionDb,
|
|
192
226
|
keys,
|
|
193
|
-
c.req.valid("param").token,
|
|
227
|
+
{ token: c.req.valid("param").token, url: c.req.url },
|
|
194
228
|
new Date(),
|
|
195
229
|
c.req.valid("query").reason,
|
|
196
230
|
env.ENVIRONMENT,
|
|
@@ -1,12 +1,19 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
|
+
import { assertRetainedAgreed, type RetainedRows } from "@pithy-sh/core/src/migrations/retained";
|
|
4
5
|
import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
|
|
5
6
|
import { GLOBAL_SCOPE } from "@pithy-sh/core/src/naming/environment";
|
|
6
7
|
import { bindingResourceName, type ProjectGlobalNaming } from "@pithy-sh/core/src/naming/provisionScope";
|
|
7
8
|
import { resourceName } from "@pithy-sh/core/src/naming/resource";
|
|
8
9
|
import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
|
|
9
|
-
import {
|
|
10
|
+
import {
|
|
11
|
+
assertSharedLeavesLast,
|
|
12
|
+
type DeprovisionTarget,
|
|
13
|
+
deprovisionTarget,
|
|
14
|
+
type ManagedEnvironment,
|
|
15
|
+
managedEnvironments,
|
|
16
|
+
} from "@pithy-sh/secrets/src/scope";
|
|
10
17
|
|
|
11
18
|
/**
|
|
12
19
|
* The provisioning orchestration for the email capability — the live counterpart to `pithy add email`'s
|
|
@@ -27,7 +34,7 @@ import { type ManagedEnvironment, managedEnvironments } from "@pithy-sh/secrets/
|
|
|
27
34
|
*
|
|
28
35
|
* **Operator prerequisites (out of band, like the secrets store):** the sending domain must be onboarded
|
|
29
36
|
* onto Cloudflare Email Service, one Email Routing rule must point bounce/complaint mail at the production
|
|
30
|
-
* app worker, and the link-signing key must exist (`pithy secrets
|
|
37
|
+
* app worker, and the link-signing key must exist (`pithy secrets provision` creates each environment's Secrets Store entry). These
|
|
31
38
|
* are one-time account/DNS actions provisioning does not own.
|
|
32
39
|
*/
|
|
33
40
|
|
|
@@ -175,12 +182,23 @@ export async function provisionEmail(
|
|
|
175
182
|
|
|
176
183
|
/** The teardown seam — the inverse of {@link EmailProvisioner}. Every step idempotent (a missing resource is a no-op). */
|
|
177
184
|
export interface EmailDeprovisioner {
|
|
185
|
+
/**
|
|
186
|
+
* The rows the suppression list holds, named by its database — empty when the database is absent. Read-only.
|
|
187
|
+
* What a teardown counts before it deletes the list (#591).
|
|
188
|
+
*/
|
|
189
|
+
countSuppressionRetained(): Promise<RetainedRows[]>;
|
|
190
|
+
/**
|
|
191
|
+
* Whether the env's email worker is deployed. Read-only. What a teardown asks of every *other* environment
|
|
192
|
+
* before it deletes the list they share (#591).
|
|
193
|
+
*/
|
|
194
|
+
hasWorker(env: ManagedEnvironment): Promise<boolean>;
|
|
178
195
|
/** Delete the env's email worker. Idempotent (a missing worker is a no-op). */
|
|
179
196
|
deleteWorker(env: ManagedEnvironment): Promise<void>;
|
|
180
197
|
/**
|
|
181
198
|
* Delete the shared suppression D1. **Destructive** — the global suppression list is lost, so every
|
|
182
199
|
* environment forgets who unsubscribed or hard-bounced — so the orchestration only calls it when
|
|
183
|
-
* explicitly asked. Idempotent.
|
|
200
|
+
* explicitly asked. Idempotent. A live implementation refuses while the list holds more rows than the
|
|
201
|
+
* operator agreed to destroy.
|
|
184
202
|
*/
|
|
185
203
|
deleteSuppressionDatabase(): Promise<void>;
|
|
186
204
|
}
|
|
@@ -189,24 +207,46 @@ export interface EmailDeprovisioner {
|
|
|
189
207
|
export interface EmailDeprovisionOptions {
|
|
190
208
|
/** Also delete the shared suppression database. Off by default; only a full destroy sets it. */
|
|
191
209
|
deleteSuppression?: boolean;
|
|
210
|
+
/**
|
|
211
|
+
* The operator's count of suppressed addresses to destroy — `--destroy-retained <n>`. With
|
|
212
|
+
* `deleteSuppression`, it must equal the rows the list holds; absent, only an empty list is deleted.
|
|
213
|
+
*/
|
|
214
|
+
destroyRetained?: number;
|
|
192
215
|
}
|
|
193
216
|
|
|
194
217
|
/**
|
|
195
|
-
* Tear down
|
|
196
|
-
*
|
|
197
|
-
*
|
|
218
|
+
* Tear down **one named environment's** email infrastructure, reversing {@link provisionEmail} for it.
|
|
219
|
+
*
|
|
220
|
+
* In order, and the order is the contract:
|
|
198
221
|
*
|
|
199
|
-
*
|
|
200
|
-
*
|
|
201
|
-
*
|
|
222
|
+
* 1. Resolve the target (`@pithy-sh/secrets`' `deprovisionTarget`) — refused with nothing read when none was
|
|
223
|
+
* named, or one the project does not declare. This used to walk every declared environment, so a run meant
|
|
224
|
+
* for staging removed production's email worker with it (#591).
|
|
225
|
+
* 2. With `deleteSuppression` only: refuse while any other declared environment still runs an email worker
|
|
226
|
+
* (`assertSharedLeavesLast`). The list is one per project, and a staging teardown must not take production's.
|
|
227
|
+
* 3. Count the list, and refuse unless the operator counted the same (`assertRetainedAgreed`, #588's guard).
|
|
228
|
+
* 4. Delete the environment's worker (it binds the list), then — only when asked — the list.
|
|
229
|
+
*
|
|
230
|
+
* Idempotent end to end: a missing worker or database is a no-op.
|
|
202
231
|
*/
|
|
203
232
|
export async function deprovisionEmail(
|
|
204
233
|
deprovisioner: EmailDeprovisioner,
|
|
205
|
-
|
|
234
|
+
target: DeprovisionTarget,
|
|
206
235
|
options: EmailDeprovisionOptions = {},
|
|
207
|
-
): Promise<
|
|
208
|
-
|
|
209
|
-
|
|
236
|
+
): Promise<{ env: ManagedEnvironment }> {
|
|
237
|
+
const env = deprovisionTarget(target);
|
|
238
|
+
// Both checks run before the worker goes, so a refusal leaves the project exactly as it was.
|
|
239
|
+
if (options.deleteSuppression) {
|
|
240
|
+
await assertSharedLeavesLast(env, target.declared, (other) => deprovisioner.hasWorker(other), [
|
|
241
|
+
{ what: "the suppression list", flag: "--suppression" },
|
|
242
|
+
]);
|
|
243
|
+
assertRetainedAgreed(
|
|
244
|
+
await deprovisioner.countSuppressionRetained(),
|
|
245
|
+
options.destroyRetained,
|
|
246
|
+
"anything was deleted",
|
|
247
|
+
);
|
|
210
248
|
}
|
|
249
|
+
await deprovisioner.deleteWorker(env);
|
|
211
250
|
if (options.deleteSuppression) await deprovisioner.deleteSuppressionDatabase();
|
|
251
|
+
return { env };
|
|
212
252
|
}
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
|
|
5
5
|
import type { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
|
|
6
|
+
import { environmentScope, type SecretNameScope } from "@pithy-sh/core/src/naming/provisionScope";
|
|
6
7
|
import type {
|
|
7
8
|
HostD1Binding,
|
|
8
9
|
HostSecretsStoreBinding,
|
|
@@ -15,6 +16,7 @@ import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
|
|
|
15
16
|
import type { WorkflowRegistry } from "@pithy-sh/core/src/workflow/spec";
|
|
16
17
|
import { masterKeySecretName } from "@pithy-sh/secrets/src/provision/provisionSecrets";
|
|
17
18
|
import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
|
|
19
|
+
import { EMAIL_LINK_SIGNING_KEY, EMAIL_LINK_SIGNING_KEY_BINDING, emailSigningRegistry } from "../crypto/signingKey";
|
|
18
20
|
import { emailCatalogVarName } from "../templates/messages";
|
|
19
21
|
import type { EmailTheme } from "../templates/theme";
|
|
20
22
|
import { EmailScheduleParams, EmailSendParams } from "../workflows/params";
|
|
@@ -143,9 +145,9 @@ export interface EmailConfigParams {
|
|
|
143
145
|
appDatabaseId: string;
|
|
144
146
|
/** The shared suppression database id (same in every environment). */
|
|
145
147
|
suppressionDatabaseId: string;
|
|
146
|
-
/** This environment's secrets database id (`<project>-<env>-secrets`)
|
|
148
|
+
/** This environment's secrets database id (`<project>-<env>-secrets`). The signing key is not in it (#596). */
|
|
147
149
|
secretsDatabaseId: string;
|
|
148
|
-
/** The CF Secrets Store id holding the per-env master key. */
|
|
150
|
+
/** The CF Secrets Store id holding the per-env master key and the per-env link-signing key. */
|
|
149
151
|
storeId: string;
|
|
150
152
|
/** The app worker's public base URL for this environment — callback links are built against it. */
|
|
151
153
|
baseUrl: string;
|
|
@@ -208,6 +210,16 @@ export function resolveEmailConfig(
|
|
|
208
210
|
secretsStoreId: storeId,
|
|
209
211
|
// The master key entry is project- and env-scoped, matching what the secrets manager wrote.
|
|
210
212
|
masterKeySecretName: masterKeySecretName(project, env),
|
|
213
|
+
// The link-signing key, at the entry `pithy secrets provision` created and bound the app Worker to —
|
|
214
|
+
// composed by the same `environmentScope(...).secretEntry` call, from the declaration's own scope, so
|
|
215
|
+
// the Worker that signs a link and the Worker that verifies it cannot be handed two different keys.
|
|
216
|
+
// Keyed by the binding the template declares; the entry keeps the registry key's name (#603).
|
|
217
|
+
secretNames: {
|
|
218
|
+
[EMAIL_LINK_SIGNING_KEY_BINDING]: environmentScope(project, env).secretEntry(
|
|
219
|
+
EMAIL_LINK_SIGNING_KEY,
|
|
220
|
+
emailSigningRegistry[EMAIL_LINK_SIGNING_KEY].scope as SecretNameScope,
|
|
221
|
+
),
|
|
222
|
+
},
|
|
211
223
|
// The theme and the catalogs travel the same way, and they have to: the host composes no
|
|
212
224
|
// capabilities, so the brand and the words are both things only a provision run can hand it.
|
|
213
225
|
vars: { EMAIL_THEME: JSON.stringify(theme), BASE_URL: baseUrl, ...emailMessagesVars(params.messages) },
|
|
@@ -10,8 +10,9 @@ import type {
|
|
|
10
10
|
} from "@pithy-sh/core/src/capability/settings";
|
|
11
11
|
import { hostEnvFindings } from "@pithy-sh/core/src/capability/settings";
|
|
12
12
|
import { LOCAL_ORIGIN } from "@pithy-sh/core/src/naming/domains";
|
|
13
|
+
import { environmentScope, type SecretNameScope } from "@pithy-sh/core/src/naming/provisionScope";
|
|
13
14
|
import { checkHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
14
|
-
import { EMAIL_LINK_SIGNING_KEY } from "../crypto/signingKey";
|
|
15
|
+
import { EMAIL_LINK_SIGNING_KEY, EMAIL_LINK_SIGNING_KEY_BINDING, emailSigningRegistry } from "../crypto/signingKey";
|
|
15
16
|
import type { EmailTheme } from "../templates/theme";
|
|
16
17
|
import { emailHostEnv } from "../workflows/hostEnv";
|
|
17
18
|
import { suppressionDatabaseName } from "./provisionEmail";
|
|
@@ -35,8 +36,8 @@ import { suppressionDatabaseName } from "./provisionEmail";
|
|
|
35
36
|
*
|
|
36
37
|
* ## The account tier asks the three things only the account knows
|
|
37
38
|
*
|
|
38
|
-
* Is the sending domain a zone here, does the suppression database exist, does the signing key have
|
|
39
|
-
*
|
|
39
|
+
* Is the sending domain a zone here, does the suppression database exist, does the signing key have its
|
|
40
|
+
* 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
|
|
40
41
|
* none of them is inferable from a file in the checkout.
|
|
41
42
|
*
|
|
42
43
|
* Nothing here writes. Every finding names the command, the config key, or the one-time dashboard action
|
|
@@ -68,6 +69,7 @@ function stubBindings(): Record<string, unknown> {
|
|
|
68
69
|
EMAIL_SUPPRESSIONS: d1,
|
|
69
70
|
SECRETS: d1,
|
|
70
71
|
SECRETS_ENCRYPTION_KEYS: "checked elsewhere",
|
|
72
|
+
[EMAIL_LINK_SIGNING_KEY_BINDING]: "checked elsewhere",
|
|
71
73
|
EMAIL: { send: () => undefined },
|
|
72
74
|
EMAIL_SENDER: { create: () => undefined, get: () => undefined },
|
|
73
75
|
EMAIL_SCHEDULER: { create: () => undefined },
|
|
@@ -186,11 +188,6 @@ function localForAddress(config: EmailSettingsInput): SettingsFinding[] {
|
|
|
186
188
|
];
|
|
187
189
|
}
|
|
188
190
|
|
|
189
|
-
/** The last declared environment — the one a project-wide remedy is named for. */
|
|
190
|
-
function lastEnvironment(context: SettingsCheckContext): string {
|
|
191
|
-
return context.environments.at(-1)?.name ?? "prod";
|
|
192
|
-
}
|
|
193
|
-
|
|
194
191
|
/** The account half: the zone, the suppression database, and the signing key. */
|
|
195
192
|
async function accountFindings(
|
|
196
193
|
config: EmailSettingsInput,
|
|
@@ -216,26 +213,61 @@ async function accountFindings(
|
|
|
216
213
|
setting: "EMAIL_SUPPRESSIONS",
|
|
217
214
|
environment: null,
|
|
218
215
|
problem: `No D1 database named ${suppressions} exists on this account.`,
|
|
219
|
-
// One database for the whole project,
|
|
220
|
-
//
|
|
221
|
-
action:
|
|
216
|
+
// One database for the whole project, and one run creates it. `pithy email provision` spans every
|
|
217
|
+
// declared environment and takes no `--env`, so naming one here was a flag the CLI refuses (#594).
|
|
218
|
+
action: "Run `pithy email provision`. Nothing is suppressed until it exists.",
|
|
222
219
|
});
|
|
223
220
|
}
|
|
224
221
|
|
|
225
222
|
for (const environment of context.environments) {
|
|
226
|
-
// `dev` has no
|
|
227
|
-
//
|
|
228
|
-
// which the runner would report as an unchecked capability rather than as this clean pass.
|
|
223
|
+
// `dev` has no Secrets Store entry and no manager Worker: its key is the generated `.dev.vars` line, and
|
|
224
|
+
// `pithy doctor`'s dev-secrets block is what reads that.
|
|
229
225
|
if (environment.name === "dev") continue;
|
|
230
|
-
|
|
226
|
+
findings.push(...(await signingKeyFindings(context, environment.name)));
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
return findings;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* Where the link-signing key is in one deployed environment, and where it should not be (#596).
|
|
234
|
+
*
|
|
235
|
+
* **Two stores, two questions, and neither answers the other.** The key is a Secrets Store entry per
|
|
236
|
+
* environment: the one `pithy secrets provision` created, at the name `environmentScope(...).secretEntry`
|
|
237
|
+
* composes from the declaration's own scope. That is the question that says whether a link can be signed.
|
|
238
|
+
*
|
|
239
|
+
* The vault question is the migration. A project provisioned before the move holds the key as a D1 row,
|
|
240
|
+
* which nothing reads now — and which the move cannot carry: the row is sealed under a master key no
|
|
241
|
+
* command can read, and every link minted from it predates the audience claim the verifier requires. So the
|
|
242
|
+
* finding says plainly that those links are gone, and names the command that removes the row once the entry
|
|
243
|
+
* is serving. The path in full is in `docs/commands/secrets.md`.
|
|
244
|
+
*
|
|
245
|
+
* **What this sees:** a row under this registry name. A secret some other declaration moved off D1 has its
|
|
246
|
+
* own check to write, or none; nothing here walks the vault for strays, because the vault cannot be listed.
|
|
247
|
+
*/
|
|
248
|
+
async function signingKeyFindings(context: SettingsAccountContext, environment: string): Promise<SettingsFinding[]> {
|
|
249
|
+
const findings: SettingsFinding[] = [];
|
|
250
|
+
const entry = environmentScope(context.project, environment).secretEntry(
|
|
251
|
+
EMAIL_LINK_SIGNING_KEY,
|
|
252
|
+
emailSigningRegistry[EMAIL_LINK_SIGNING_KEY].scope as SecretNameScope,
|
|
253
|
+
);
|
|
254
|
+
if (!(await context.account.storeEntry(entry))) {
|
|
231
255
|
findings.push({
|
|
232
256
|
setting: EMAIL_LINK_SIGNING_KEY,
|
|
233
|
-
environment
|
|
234
|
-
problem: `The link-signing key has no
|
|
235
|
-
|
|
257
|
+
environment,
|
|
258
|
+
problem: `The link-signing key has no Secrets Store entry in ${environment}, so no tracking or unsubscribe link can be signed.`,
|
|
259
|
+
// No `--env`: the command spans every declared environment, and takes no such flag.
|
|
260
|
+
action: "Run `pithy secrets provision`.",
|
|
261
|
+
});
|
|
262
|
+
}
|
|
263
|
+
if (await context.account.vaultSecret({ name: EMAIL_LINK_SIGNING_KEY, environment })) {
|
|
264
|
+
findings.push({
|
|
265
|
+
setting: EMAIL_LINK_SIGNING_KEY,
|
|
266
|
+
environment,
|
|
267
|
+
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.`,
|
|
268
|
+
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.`,
|
|
236
269
|
});
|
|
237
270
|
}
|
|
238
|
-
|
|
239
271
|
return findings;
|
|
240
272
|
}
|
|
241
273
|
|
package/src/templates/engine.ts
CHANGED
|
@@ -359,7 +359,8 @@ export async function renderEmail(
|
|
|
359
359
|
const mint = (kind: "click" | "open" | "unsubscribe", extra: { destination?: string; linkLabel?: string }) =>
|
|
360
360
|
mintToken(
|
|
361
361
|
{ kind, jobId: tracking.jobId, recipient: tracking.recipient, campaignId: tracking.campaignId, ...extra },
|
|
362
|
-
|
|
362
|
+
// The links point at `baseUrl`, so that origin is the one the token is minted for.
|
|
363
|
+
{ key: tracking.key, kid: tracking.kid, expiresAt: tracking.expiresAt, audience: tracking.baseUrl },
|
|
363
364
|
);
|
|
364
365
|
|
|
365
366
|
if (tracking.clickTracking) {
|
package/src/version.generated.ts
CHANGED
package/src/workflows/hostEnv.ts
CHANGED
|
@@ -5,6 +5,7 @@ import type { D1Database } from "@cloudflare/workers-types";
|
|
|
5
5
|
import { defineHostEnv, type HostEnvProvider } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
6
6
|
import type { SecretBinding } from "@pithy-sh/secrets/src/env/bindings";
|
|
7
7
|
import { z } from "zod";
|
|
8
|
+
import { EMAIL_LINK_SIGNING_KEY, EMAIL_LINK_SIGNING_KEY_BINDING } from "../crypto/signingKey";
|
|
8
9
|
import type { EmailSender } from "../send/sender";
|
|
9
10
|
import { defaultTheme, EmailTheme } from "../templates/theme";
|
|
10
11
|
import type { SendWorkflowInstances } from "./instances";
|
|
@@ -40,8 +41,19 @@ import type { SendWorkflowInstances } from "./instances";
|
|
|
40
41
|
* without executing the Worker — the same constraint `@pithy-sh/core`'s host modules carry.
|
|
41
42
|
*/
|
|
42
43
|
|
|
43
|
-
/**
|
|
44
|
-
|
|
44
|
+
/**
|
|
45
|
+
* The command that writes every provisioned value here. Stated once so nine action lines cannot drift.
|
|
46
|
+
*
|
|
47
|
+
* No `--env`: it spans every declared environment in one run and declares no such flag, and a flag a
|
|
48
|
+
* command does not declare is refused (#594) — so a remedy naming one is a remedy that cannot be followed.
|
|
49
|
+
*/
|
|
50
|
+
const PROVISION = "pithy email provision";
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* The command that writes both host secrets below. No `--env`, for the same reason: `pithy secrets provision`
|
|
54
|
+
* provisions every declared environment in one run and declares no such flag.
|
|
55
|
+
*/
|
|
56
|
+
const SECRETS_PROVISION = "pithy secrets provision";
|
|
45
57
|
|
|
46
58
|
/** A binding `pithy email provision` wires into the resolved `wrangler.jsonc`. */
|
|
47
59
|
const binding = (name: string): HostEnvProvider => ({ kind: "binding", name, command: PROVISION });
|
|
@@ -85,14 +97,19 @@ export const EmailHostEnv = z
|
|
|
85
97
|
EMAIL_SUPPRESSIONS: d1Binding("The shared suppression database every environment of this project binds").describe(
|
|
86
98
|
"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`.",
|
|
87
99
|
),
|
|
88
|
-
SECRETS: d1Binding("The per-environment secrets database
|
|
89
|
-
"The per-environment secrets D1 database
|
|
100
|
+
SECRETS: d1Binding("The per-environment secrets database").describe(
|
|
101
|
+
"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).",
|
|
90
102
|
),
|
|
91
103
|
SECRETS_ENCRYPTION_KEYS: z
|
|
92
104
|
.union([z.string().min(1), callable<SecretBinding>("get", "The master key binding")])
|
|
93
105
|
.describe(
|
|
94
106
|
"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.",
|
|
95
107
|
),
|
|
108
|
+
[EMAIL_LINK_SIGNING_KEY_BINDING]: z
|
|
109
|
+
.union([z.string().min(1), callable<SecretBinding>("get", "The link-signing key binding")])
|
|
110
|
+
.describe(
|
|
111
|
+
"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.",
|
|
112
|
+
),
|
|
96
113
|
EMAIL: callable<EmailSender>("send", "The Cloudflare Email Service send binding").describe(
|
|
97
114
|
"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.",
|
|
98
115
|
),
|
|
@@ -193,7 +210,12 @@ export const emailHostEnv = defineHostEnv({
|
|
|
193
210
|
SECRETS_ENCRYPTION_KEYS: {
|
|
194
211
|
kind: "secret",
|
|
195
212
|
name: "SECRETS_ENCRYPTION_KEYS",
|
|
196
|
-
command:
|
|
213
|
+
command: SECRETS_PROVISION,
|
|
214
|
+
},
|
|
215
|
+
[EMAIL_LINK_SIGNING_KEY_BINDING]: {
|
|
216
|
+
kind: "secret",
|
|
217
|
+
name: EMAIL_LINK_SIGNING_KEY,
|
|
218
|
+
command: SECRETS_PROVISION,
|
|
197
219
|
},
|
|
198
220
|
EMAIL: binding("EMAIL"),
|
|
199
221
|
EMAIL_SENDER: binding("EMAIL_SENDER"),
|
package/src/workflows/worker.ts
CHANGED
|
@@ -6,9 +6,9 @@ import { NonRetryableError } from "cloudflare:workflows";
|
|
|
6
6
|
import type { D1Database, ExecutionContext } from "@cloudflare/workers-types";
|
|
7
7
|
import { classifiedSteps } from "@pithy-sh/core/src/workflow/faults";
|
|
8
8
|
import { requireHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
9
|
-
import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
|
|
9
|
+
import type { SecretBinding, SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
|
|
10
10
|
import { configureSharedSecrets } from "@pithy-sh/secrets/src/sharedSecretsStore";
|
|
11
|
-
import { emailSigningRegistry, resolveSigningKeys } from "../crypto/signingKey";
|
|
11
|
+
import { EMAIL_LINK_SIGNING_KEY_BINDING, emailSigningRegistry, resolveSigningKeys } from "../crypto/signingKey";
|
|
12
12
|
import { emailDatabase, emailSuppressionDatabase } from "../data/tables";
|
|
13
13
|
import { mintBatchId } from "../send/batchIdentity";
|
|
14
14
|
import type { SendWorkflowBinding } from "../send/enqueue";
|
|
@@ -55,6 +55,8 @@ import { type BatchSendReport, runSendBatch, type SendBatchDeps } from "./sendBa
|
|
|
55
55
|
export interface EmailWorkerEnv extends SecretsStoreEnv {
|
|
56
56
|
/** The app database the per-environment jobs/events tables live in. */
|
|
57
57
|
DB: D1Database;
|
|
58
|
+
/** The link-signing key: this environment's Secrets Store entry, or its `.dev.vars` string locally (#596). */
|
|
59
|
+
[EMAIL_LINK_SIGNING_KEY_BINDING]: SecretBinding | string;
|
|
58
60
|
/** The shared, durable suppression database. */
|
|
59
61
|
EMAIL_SUPPRESSIONS: D1Database;
|
|
60
62
|
/** The Cloudflare Email Service send binding. */
|
|
@@ -20,7 +20,8 @@
|
|
|
20
20
|
"workers_dev": false,
|
|
21
21
|
|
|
22
22
|
// The app database — the email tables (pithy_email_jobs/events/suppressions) live here, alongside the
|
|
23
|
-
// app's own data. Plus the secrets database,
|
|
23
|
+
// app's own data. Plus the secrets database, bound as on every prebuilt host that reads through
|
|
24
|
+
// `@pithy-sh/secrets`; email's own key is no longer in it (see the Secrets Store block below).
|
|
24
25
|
"d1_databases": [
|
|
25
26
|
{ "binding": "DB", "database_name": "pithy-app", "database_id": "<filled-at-provision>" },
|
|
26
27
|
// The durable suppression database — one per PROJECT, shared across that project's environments,
|
|
@@ -42,12 +43,19 @@
|
|
|
42
43
|
// selects the local simulator instead; a deployed worker ignores the flag either way.
|
|
43
44
|
"send_email": [{ "name": "EMAIL" }],
|
|
44
45
|
|
|
45
|
-
// The master key
|
|
46
|
+
// The link-signing key, and the master key every prebuilt host binds. The link key is a Secrets Store
|
|
47
|
+
// entry per environment (pithy-sh/pithy#596) — this host signs the links and the app Worker verifies them,
|
|
48
|
+
// so both bind the one entry `pithy secrets provision` created, named by the same function.
|
|
46
49
|
"secrets_store_secrets": [
|
|
47
50
|
{
|
|
48
51
|
"binding": "SECRETS_ENCRYPTION_KEYS",
|
|
49
52
|
"store_id": "<filled-at-provision>",
|
|
50
53
|
"secret_name": "<filled-at-provision>"
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
"binding": "EMAIL_LINK_SIGNING_KEY",
|
|
57
|
+
"store_id": "<filled-at-provision>",
|
|
58
|
+
"secret_name": "<filled-at-provision>"
|
|
51
59
|
}
|
|
52
60
|
],
|
|
53
61
|
|