@pithy-sh/email 0.3.2 → 0.3.4
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 +5 -5
- package/dist/crypto/signingKey.d.ts.map +1 -1
- package/dist/crypto/signingKey.js +5 -5
- 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 +25 -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 +13 -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/dist/capability.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAE7F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EACL,KAAK,wBAAwB,
|
|
1
|
+
{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAE7F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EACL,KAAK,wBAAwB,EAM9B,MAAM,eAAe,CAAC;AAMvB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAgB,MAAM,gBAAgB,CAAC;AACrF,OAAO,EAAE,KAAK,cAAc,EAAsB,MAAM,sBAAsB,CAAC;AAE/E,OAAO,EAAe,KAAK,UAAU,EAAgB,MAAM,mBAAmB,CAAC;AAI/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,EAAE,EAAE,UAAU,CAAC;IACf;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,UAAU,CAAC;CACjC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,kGAAkG;AAClG,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiC8B,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D,2FAA2F;AAC3F,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,WAAW,EAAE,eAAe,CAAC;IAC7B,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,WAAW,EAAE,mBAAmB,CAAC;IACjC;;;;;OAKG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/E;;;;;;;;;;;;;OAaG;IACH,YAAY,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,wBAAwB,CAAC;IACjE;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,MAAM,cAAc,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAkN/D;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
|
package/dist/capability.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
-
import { emailDatabase, emailSuppressionDatabase, emailSuppressionTables, emailTables } from "./data/tables.js";
|
|
3
|
+
import { emailDatabase, emailSuppressionDatabase, emailSuppressionTables, emailSuppressionsRetainedTables, emailTables } from "./data/tables.js";
|
|
4
4
|
import { createBounceHandler } from "./bounce/handler.js";
|
|
5
5
|
import { emailSigningRegistry } from "./crypto/signingKey.js";
|
|
6
6
|
import { EMAIL_MESSAGES, kitEmailLayers } from "./templates/messages.js";
|
|
@@ -146,7 +146,8 @@ function email(config) {
|
|
|
146
146
|
binding: "EMAIL_SUPPRESSIONS",
|
|
147
147
|
tables: emailSuppressionTables,
|
|
148
148
|
migrationOrder: 100,
|
|
149
|
-
migrations: { "0001_suppressions": email_0001_suppressions }
|
|
149
|
+
migrations: { "0001_suppressions": email_0001_suppressions },
|
|
150
|
+
retained: emailSuppressionsRetainedTables
|
|
150
151
|
}
|
|
151
152
|
},
|
|
152
153
|
/**
|
|
@@ -3,16 +3,16 @@
|
|
|
3
3
|
import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
|
|
4
4
|
import type { VersionedSecret } from "@pithy-sh/secrets/src/secretsStore";
|
|
5
5
|
/**
|
|
6
|
-
* The link-signing key
|
|
7
|
-
* by name through its own minimal registry — `secretsStore` reads the same
|
|
8
|
-
*
|
|
6
|
+
* The link-signing key: a rotatable secret in the **Cloudflare Secrets Store**, one entry per environment.
|
|
7
|
+
* Email resolves it by name through its own minimal registry — `secretsStore` reads the same binding
|
|
8
|
+
* whichever registry names it, so email never needs the project-wide registry to sign or verify a link.
|
|
9
9
|
*/
|
|
10
10
|
export declare const EMAIL_LINK_SIGNING_KEY = "email-link-signing-key";
|
|
11
11
|
/** The minimal registry email uses to resolve its signing key. Rotatable so old links verify after rotation. */
|
|
12
12
|
export declare const emailSigningRegistry: {
|
|
13
13
|
readonly "email-link-signing-key": {
|
|
14
|
-
readonly backend: "
|
|
15
|
-
readonly scope: "
|
|
14
|
+
readonly backend: "cf-secrets-store";
|
|
15
|
+
readonly scope: "environment";
|
|
16
16
|
readonly rotatable: true;
|
|
17
17
|
readonly valueType: "text";
|
|
18
18
|
readonly devValue: "random";
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"signingKey.d.ts","sourceRoot":"","sources":["../../src/crypto/signingKey.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAG1E;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAE/D,gHAAgH;AAChH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;
|
|
1
|
+
{"version":3,"file":"signingKey.d.ts","sourceRoot":"","sources":["../../src/crypto/signingKey.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAG1E;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAE/D,gHAAgH;AAChH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;CA+B/B,CAAC;AAEH;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,eAAe,CAAC,CAAC,OAAO,oBAAoB,CAAC,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAAC,CAGxF"}
|
|
@@ -4,15 +4,15 @@ import { defineSecretRegistry } from "@pithy-sh/secrets/src/registry";
|
|
|
4
4
|
import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
|
|
5
5
|
//#region src/crypto/signingKey.ts
|
|
6
6
|
/**
|
|
7
|
-
* The link-signing key
|
|
8
|
-
* by name through its own minimal registry — `secretsStore` reads the same
|
|
9
|
-
*
|
|
7
|
+
* The link-signing key: a rotatable secret in the **Cloudflare Secrets Store**, one entry per environment.
|
|
8
|
+
* Email resolves it by name through its own minimal registry — `secretsStore` reads the same binding
|
|
9
|
+
* whichever registry names it, so email never needs the project-wide registry to sign or verify a link.
|
|
10
10
|
*/
|
|
11
11
|
const EMAIL_LINK_SIGNING_KEY = "email-link-signing-key";
|
|
12
12
|
/** The minimal registry email uses to resolve its signing key. Rotatable so old links verify after rotation. */
|
|
13
13
|
const emailSigningRegistry = defineSecretRegistry({ [EMAIL_LINK_SIGNING_KEY]: {
|
|
14
|
-
backend: "
|
|
15
|
-
scope: "
|
|
14
|
+
backend: "cf-secrets-store",
|
|
15
|
+
scope: "environment",
|
|
16
16
|
rotatable: true,
|
|
17
17
|
valueType: "text",
|
|
18
18
|
devValue: "random",
|
package/dist/crypto/token.d.ts
CHANGED
|
@@ -7,10 +7,11 @@ export declare const TokenKind: z.ZodEnum<{
|
|
|
7
7
|
unsubscribe: "unsubscribe";
|
|
8
8
|
}>;
|
|
9
9
|
export type TokenKind = z.output<typeof TokenKind>;
|
|
10
|
-
/** The signed claims a callback token carries. `kid`/`exp`/`v` are set by `mintToken`; the rest are caller claims. */
|
|
10
|
+
/** The signed claims a callback token carries. `kid`/`exp`/`v`/`aud` are set by `mintToken`; the rest are caller claims. */
|
|
11
11
|
export declare const CallbackToken: z.ZodObject<{
|
|
12
|
-
v: z.ZodLiteral<
|
|
12
|
+
v: z.ZodLiteral<2>;
|
|
13
13
|
kid: z.ZodString;
|
|
14
|
+
aud: z.ZodString;
|
|
14
15
|
kind: z.ZodEnum<{
|
|
15
16
|
click: "click";
|
|
16
17
|
open: "open";
|
|
@@ -25,7 +26,16 @@ export declare const CallbackToken: z.ZodObject<{
|
|
|
25
26
|
}, z.core.$strip>;
|
|
26
27
|
export type CallbackToken = z.output<typeof CallbackToken>;
|
|
27
28
|
/** The caller-supplied claims for a token — everything except the fields `mintToken` fills in. */
|
|
28
|
-
export type TokenClaims = Omit<CallbackToken, "v" | "kid" | "exp">;
|
|
29
|
+
export type TokenClaims = Omit<CallbackToken, "v" | "kid" | "exp" | "aud">;
|
|
30
|
+
/**
|
|
31
|
+
* The audience a URL names: its origin, and nothing else.
|
|
32
|
+
*
|
|
33
|
+
* One function for both sides, so a minting side that kept a path or a trailing slash and a verifying side
|
|
34
|
+
* that did not cannot come to two strings for one place. A URL that will not parse is refused as an invalid
|
|
35
|
+
* token rather than thrown as a `TypeError`: on the verifying side it is the request's own URL, and on the
|
|
36
|
+
* minting side it is `BASE_URL`, which the host has already validated as a URL.
|
|
37
|
+
*/
|
|
38
|
+
export declare function tokenAudience(url: string): string;
|
|
29
39
|
/**
|
|
30
40
|
* Mint a signed token. The claims plus `kid`/`exp`/`v` are JSON-encoded and base64url-packed, then
|
|
31
41
|
* HMAC-SHA-256 signed with `key`. The token is `<payload>.<signature>`; `kid` rides inside the signed
|
|
@@ -35,15 +45,25 @@ export declare function mintToken(claims: TokenClaims, options: {
|
|
|
35
45
|
key: string;
|
|
36
46
|
kid: string;
|
|
37
47
|
expiresAt: Date;
|
|
48
|
+
/** Any URL on the origin the links point at — `BASE_URL`. Reduced to its origin by {@link tokenAudience}. */
|
|
49
|
+
audience: string;
|
|
38
50
|
}): Promise<string>;
|
|
39
51
|
/**
|
|
40
52
|
* Verify a token against the valid signing-key version set (`@pithy-sh/secrets`' `getVersions` shape)
|
|
41
53
|
* and return its claims. Rejects — as `email/invalid_token` — a malformed token, an unknown/pruned
|
|
42
|
-
* `kid`, a bad signature (constant-time via `crypto.subtle.verify`),
|
|
43
|
-
* is deliberate: structure, then signature, then
|
|
44
|
-
* check.
|
|
54
|
+
* `kid`, a bad signature (constant-time via `crypto.subtle.verify`), a token minted for another origin,
|
|
55
|
+
* or an expired token. The order is deliberate: structure, then signature, then audience, then expiry,
|
|
56
|
+
* so a forged token never reaches a claim check.
|
|
57
|
+
*
|
|
58
|
+
* `audience` is **required**, and is the URL the token arrived on — the request's own. A verifier that
|
|
59
|
+
* could omit it would be a verifier that accepts every origin, which is the hole the claim closes.
|
|
60
|
+
*
|
|
61
|
+
* **What the check cannot see:** where the caller got the URL. It compares against the string it is handed,
|
|
62
|
+
* so a caller that passed a value read out of the token, or a header a client controls, would pass every
|
|
63
|
+
* token. `http/callbacks.ts` hands it the request's own URL, and its route test plants a staging token on
|
|
64
|
+
* each route to hold that; a new verifying caller needs the same.
|
|
45
65
|
*/
|
|
46
66
|
export declare function verifyToken(token: string, keys: {
|
|
47
67
|
versions: Record<string, string>;
|
|
48
|
-
}, now: Date): Promise<CallbackToken>;
|
|
68
|
+
}, now: Date, audience: string): Promise<CallbackToken>;
|
|
49
69
|
//# sourceMappingURL=token.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/crypto/token.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;
|
|
1
|
+
{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/crypto/token.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB,eAAO,MAAM,SAAS;;;;EAE8F,CAAC;AACrH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD,4HAA4H;AAC5H,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;iBA2BmE,CAAC;AAC9F,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,kGAAkG;AAClG,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC,CAAC;AAE3E;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMjD;AAuBD;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE;IACP,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,IAAI,CAAC;IAChB,6GAA6G;IAC7G,QAAQ,EAAE,MAAM,CAAC;CAClB,GACA,OAAO,CAAC,MAAM,CAAC,CAajB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EAC1C,GAAG,EAAE,IAAI,EACT,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,aAAa,CAAC,CAqDxB"}
|
package/dist/crypto/token.js
CHANGED
|
@@ -10,6 +10,14 @@ import { z } from "zod";
|
|
|
10
10
|
* acts. The signing secret is a **rotatable** key from `@pithy-sh/secrets`; every token records the
|
|
11
11
|
* key version (`kid`) it was signed with, so a link in a months-old email still verifies against the
|
|
12
12
|
* retained version set after a rotation — and is rejected once that version is pruned.
|
|
13
|
+
*
|
|
14
|
+
* **A token also names the origin it was minted for (`aud`), and only that origin may act on it (#596).**
|
|
15
|
+
* A link points at the environment that minted it, so nothing about the product needs a staging token to
|
|
16
|
+
* verify on production. The key is per environment, and that alone would keep them apart — for exactly as
|
|
17
|
+
* long as nobody misconfigures one as shared. The claim is what makes that misconfiguration harmless rather
|
|
18
|
+
* than a staging token that 302s through production's domain, records a staging job into production's
|
|
19
|
+
* events, and writes a staging unsubscribe into the suppression list both environments bind, stamped as
|
|
20
|
+
* production's. The key authorizes; the audience says where.
|
|
13
21
|
*/
|
|
14
22
|
const encoder = new TextEncoder();
|
|
15
23
|
const decoder = new TextDecoder();
|
|
@@ -18,10 +26,11 @@ const TokenKind = z.enum([
|
|
|
18
26
|
"open",
|
|
19
27
|
"unsubscribe"
|
|
20
28
|
]).describe("Which callback a token authorizes: a tracked link `click`, an open-pixel `open`, or an `unsubscribe`.");
|
|
21
|
-
/** The signed claims a callback token carries. `kid`/`exp`/`v` are set by `mintToken`; the rest are caller claims. */
|
|
29
|
+
/** The signed claims a callback token carries. `kid`/`exp`/`v`/`aud` are set by `mintToken`; the rest are caller claims. */
|
|
22
30
|
const CallbackToken = z.object({
|
|
23
|
-
v: z.literal(
|
|
31
|
+
v: z.literal(2).describe("Token format version, so the scheme can evolve without ambiguity. `2` added `aud`; a `1` token names no audience and is refused."),
|
|
24
32
|
kid: z.string().describe("The signing-key version this token was signed with; selects the key to verify against."),
|
|
33
|
+
aud: z.string().describe("The origin this token was minted for — the scheme, host and port its links point at. It verifies at that origin and nowhere else."),
|
|
25
34
|
kind: TokenKind.describe("Which callback this token authorizes."),
|
|
26
35
|
jobId: z.string().describe("The `pithy_email_jobs.id` this token is bound to."),
|
|
27
36
|
recipient: z.string().describe("The recipient address the callback is recorded against."),
|
|
@@ -30,6 +39,21 @@ const CallbackToken = z.object({
|
|
|
30
39
|
linkLabel: z.string().optional().describe("For a `click` token, the link's identity/label, recorded for attribution."),
|
|
31
40
|
campaignId: z.string().optional().describe("The marketing campaign this token is attributed to, when applicable.")
|
|
32
41
|
}).describe("The signed claims carried by an email callback token (click/open/unsubscribe).");
|
|
42
|
+
/**
|
|
43
|
+
* The audience a URL names: its origin, and nothing else.
|
|
44
|
+
*
|
|
45
|
+
* One function for both sides, so a minting side that kept a path or a trailing slash and a verifying side
|
|
46
|
+
* that did not cannot come to two strings for one place. A URL that will not parse is refused as an invalid
|
|
47
|
+
* token rather than thrown as a `TypeError`: on the verifying side it is the request's own URL, and on the
|
|
48
|
+
* minting side it is `BASE_URL`, which the host has already validated as a URL.
|
|
49
|
+
*/
|
|
50
|
+
function tokenAudience(url) {
|
|
51
|
+
try {
|
|
52
|
+
return new URL(url).origin;
|
|
53
|
+
} catch (cause) {
|
|
54
|
+
throw new EmailInvalidTokenError({ detail: "token audience is not a URL" }, { cause });
|
|
55
|
+
}
|
|
56
|
+
}
|
|
33
57
|
function base64UrlEncode(bytes) {
|
|
34
58
|
let binary = "";
|
|
35
59
|
for (const byte of bytes) binary += String.fromCharCode(byte);
|
|
@@ -55,10 +79,11 @@ async function importKey(secret) {
|
|
|
55
79
|
*/
|
|
56
80
|
async function mintToken(claims, options) {
|
|
57
81
|
const payload = {
|
|
58
|
-
|
|
82
|
+
...claims,
|
|
83
|
+
v: 2,
|
|
59
84
|
kid: options.kid,
|
|
60
|
-
|
|
61
|
-
|
|
85
|
+
aud: tokenAudience(options.audience),
|
|
86
|
+
exp: Math.floor(options.expiresAt.getTime() / 1e3)
|
|
62
87
|
};
|
|
63
88
|
const payloadB64 = base64UrlEncode(encoder.encode(JSON.stringify(payload)));
|
|
64
89
|
const key = await importKey(options.key);
|
|
@@ -67,11 +92,19 @@ async function mintToken(claims, options) {
|
|
|
67
92
|
/**
|
|
68
93
|
* Verify a token against the valid signing-key version set (`@pithy-sh/secrets`' `getVersions` shape)
|
|
69
94
|
* and return its claims. Rejects — as `email/invalid_token` — a malformed token, an unknown/pruned
|
|
70
|
-
* `kid`, a bad signature (constant-time via `crypto.subtle.verify`),
|
|
71
|
-
* is deliberate: structure, then signature, then
|
|
72
|
-
* check.
|
|
95
|
+
* `kid`, a bad signature (constant-time via `crypto.subtle.verify`), a token minted for another origin,
|
|
96
|
+
* or an expired token. The order is deliberate: structure, then signature, then audience, then expiry,
|
|
97
|
+
* so a forged token never reaches a claim check.
|
|
98
|
+
*
|
|
99
|
+
* `audience` is **required**, and is the URL the token arrived on — the request's own. A verifier that
|
|
100
|
+
* could omit it would be a verifier that accepts every origin, which is the hole the claim closes.
|
|
101
|
+
*
|
|
102
|
+
* **What the check cannot see:** where the caller got the URL. It compares against the string it is handed,
|
|
103
|
+
* so a caller that passed a value read out of the token, or a header a client controls, would pass every
|
|
104
|
+
* token. `http/callbacks.ts` hands it the request's own URL, and its route test plants a staging token on
|
|
105
|
+
* each route to hold that; a new verifying caller needs the same.
|
|
73
106
|
*/
|
|
74
|
-
async function verifyToken(token, keys, now) {
|
|
107
|
+
async function verifyToken(token, keys, now, audience) {
|
|
75
108
|
const parts = token.split(".");
|
|
76
109
|
if (parts.length !== 2 || !parts[0] || !parts[1]) throw new EmailInvalidTokenError({ detail: "token is not in <payload>.<signature> form" });
|
|
77
110
|
const [payloadB64, signatureB64] = parts;
|
|
@@ -94,8 +127,10 @@ async function verifyToken(token, keys, now) {
|
|
|
94
127
|
throw new EmailInvalidTokenError({ detail: "token signature could not be decoded" }, { cause });
|
|
95
128
|
}
|
|
96
129
|
if (!valid) throw new EmailInvalidTokenError({ detail: "token signature did not verify" });
|
|
130
|
+
const expected = tokenAudience(audience);
|
|
131
|
+
if (parsed.data.aud !== expected) throw new EmailInvalidTokenError({ detail: `token was minted for '${parsed.data.aud}' and presented at '${expected}'` });
|
|
97
132
|
if (parsed.data.exp * 1e3 <= now.getTime()) throw new EmailInvalidTokenError({ detail: "token has expired" });
|
|
98
133
|
return parsed.data;
|
|
99
134
|
}
|
|
100
135
|
//#endregion
|
|
101
|
-
export { CallbackToken, TokenKind, mintToken, verifyToken };
|
|
136
|
+
export { CallbackToken, TokenKind, mintToken, tokenAudience, verifyToken };
|
package/dist/data/tables.d.ts
CHANGED
|
@@ -104,6 +104,13 @@ export declare const emailSuppressionTables: {
|
|
|
104
104
|
expiresAt: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodCodec<import("zod").ZodUnion<readonly [import("zod").ZodNumber, import("zod").ZodString, import("zod").ZodDate]>, import("zod").ZodDate>>>;
|
|
105
105
|
}, import("zod/v4/core").$strip>;
|
|
106
106
|
};
|
|
107
|
+
/**
|
|
108
|
+
* The suppression list, declared **retained**: every address that bounced, complained or unsubscribed, which
|
|
109
|
+
* cannot be rebuilt from anywhere. One constant for the capability's declaration (#588) and for the CLI's
|
|
110
|
+
* teardown, which counts it before deleting the database (#591) — a second copy that drifted would count
|
|
111
|
+
* nothing and delete the list.
|
|
112
|
+
*/
|
|
113
|
+
export declare const emailSuppressionsRetainedTables: readonly ["pithyEmailSuppressions"];
|
|
107
114
|
export type EmailSuppressionTables = typeof emailSuppressionTables;
|
|
108
115
|
/** The typed Kysely database over the per-environment email tables (jobs + events). */
|
|
109
116
|
export type EmailDatabase = Kysely<DatabaseSchema<EmailTables>>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/data/tables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKrC;;;;;;;GAOG;AAEH,yDAAyD;AACzD,eAAO,MAAM,WAAW;IACtB,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IACd,gBAAgB;;;;;;;;;;;;;;;;;;;;CACjB,CAAC;AACF,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC;AAE7C,4FAA4F;AAC5F,eAAO,MAAM,sBAAsB;IACjC,sBAAsB;;;;;;;;;;;;;;;CACvB,CAAC;
|
|
1
|
+
{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/data/tables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKrC;;;;;;;GAOG;AAEH,yDAAyD;AACzD,eAAO,MAAM,WAAW;IACtB,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IACd,gBAAgB;;;;;;;;;;;;;;;;;;;;CACjB,CAAC;AACF,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC;AAE7C,4FAA4F;AAC5F,eAAO,MAAM,sBAAsB;IACjC,sBAAsB;;;;;;;;;;;;;;;CACvB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,qCAEyB,CAAC;AACtE,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC;AAEnE,uFAAuF;AACvF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC;AAEhE,mEAAmE;AACnE,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,cAAc,CAAC,sBAAsB,CAAC,CAAC,CAAC;AAEtF,sGAAsG;AACtG,wBAAgB,aAAa,CAAC,EAAE,EAAE,UAAU,GAAG,aAAa,CAE3D;AAED,mFAAmF;AACnF,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,UAAU,GAAG,wBAAwB,CAEjF"}
|
package/dist/data/tables.js
CHANGED
|
@@ -20,6 +20,13 @@ const emailTables = {
|
|
|
20
20
|
};
|
|
21
21
|
/** The global suppression table, on the dedicated durable `EMAIL_SUPPRESSIONS` database. */
|
|
22
22
|
const emailSuppressionTables = { pithyEmailSuppressions: EmailSuppression };
|
|
23
|
+
/**
|
|
24
|
+
* The suppression list, declared **retained**: every address that bounced, complained or unsubscribed, which
|
|
25
|
+
* cannot be rebuilt from anywhere. One constant for the capability's declaration (#588) and for the CLI's
|
|
26
|
+
* teardown, which counts it before deleting the database (#591) — a second copy that drifted would count
|
|
27
|
+
* nothing and delete the list.
|
|
28
|
+
*/
|
|
29
|
+
const emailSuppressionsRetainedTables = ["pithyEmailSuppressions"];
|
|
23
30
|
/** Build the per-environment email database from the app `DB` binding (CamelCasePlugin installed). */
|
|
24
31
|
function emailDatabase(d1) {
|
|
25
32
|
return createDatabase(d1, emailTables);
|
|
@@ -29,4 +36,4 @@ function emailSuppressionDatabase(d1) {
|
|
|
29
36
|
return createDatabase(d1, emailSuppressionTables);
|
|
30
37
|
}
|
|
31
38
|
//#endregion
|
|
32
|
-
export { emailDatabase, emailSuppressionDatabase, emailSuppressionTables, emailTables };
|
|
39
|
+
export { emailDatabase, emailSuppressionDatabase, emailSuppressionTables, emailSuppressionsRetainedTables, emailTables };
|
package/dist/http/callbacks.d.ts
CHANGED
|
@@ -7,17 +7,31 @@ import { type EmailDatabase, type EmailSuppressionDatabase } from "../data/table
|
|
|
7
7
|
export interface SigningKeys {
|
|
8
8
|
versions: Record<string, string>;
|
|
9
9
|
}
|
|
10
|
+
/**
|
|
11
|
+
* Where a token was presented: the URL of the request carrying it. The token's `aud` has to name this
|
|
12
|
+
* origin, so a link minted by one environment cannot act on another's routes even under a shared key.
|
|
13
|
+
*
|
|
14
|
+
* The request's own URL rather than `email({ baseUrl })`: that config value is one string composed for
|
|
15
|
+
* whichever environment the config was loaded under, while the request is, by construction, at the origin
|
|
16
|
+
* this Worker is serving.
|
|
17
|
+
*/
|
|
18
|
+
export interface CallbackRequest {
|
|
19
|
+
/** The raw callback token from the path. */
|
|
20
|
+
token: string;
|
|
21
|
+
/** The URL the request arrived on. Only its origin is compared. */
|
|
22
|
+
url: string;
|
|
23
|
+
}
|
|
10
24
|
/** Handle a click: record it, then 302-redirect to the signed http(s) destination. */
|
|
11
|
-
export declare function handleClick(db: EmailDatabase, keys: SigningKeys,
|
|
25
|
+
export declare function handleClick(db: EmailDatabase, keys: SigningKeys, request: CallbackRequest, now: Date): Promise<Response>;
|
|
12
26
|
/** Handle an open: record it, return the 1×1 pixel. */
|
|
13
|
-
export declare function handleOpen(db: EmailDatabase, keys: SigningKeys,
|
|
27
|
+
export declare function handleOpen(db: EmailDatabase, keys: SigningKeys, request: CallbackRequest, now: Date): Promise<Response>;
|
|
14
28
|
/**
|
|
15
29
|
* Handle an unsubscribe: suppress the address (shared DB), record the opt-out event (app DB), confirm.
|
|
16
30
|
* An optional `reason` — supplied by the app's own unsubscribe/preferences flow via the `?reason=` query
|
|
17
31
|
* param — is stored on the suppression `detail` and the event, so a project can capture *why* someone
|
|
18
32
|
* opted out using its own logic. It is length-bounded so the link can't be used to stuff the column.
|
|
19
33
|
*/
|
|
20
|
-
export declare function handleUnsubscribe(db: EmailDatabase, suppressionDb: EmailSuppressionDatabase, keys: SigningKeys,
|
|
34
|
+
export declare function handleUnsubscribe(db: EmailDatabase, suppressionDb: EmailSuppressionDatabase, keys: SigningKeys, request: CallbackRequest, now: Date, reason?: string, environment?: string): Promise<Response>;
|
|
21
35
|
/** Mount the click/open/unsubscribe callback routes under `${CALLBACK_BASE}` on the app's Hono router. */
|
|
22
36
|
export declare function registerCallbacks(app: Hono<PithyHonoEnv>): void;
|
|
23
37
|
//# sourceMappingURL=callbacks.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"callbacks.d.ts","sourceRoot":"","sources":["../../src/http/callbacks.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAGjC,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAG9B,MAAM,gBAAgB,CAAC;
|
|
1
|
+
{"version":3,"file":"callbacks.d.ts","sourceRoot":"","sources":["../../src/http/callbacks.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAGjC,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAG9B,MAAM,gBAAgB,CAAC;AA4CxB,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAQD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;CACb;AAgBD,sFAAsF;AACtF,wBAAsB,WAAW,CAC/B,EAAE,EAAE,aAAa,EACjB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,QAAQ,CAAC,CAmBnB;AAED,uDAAuD;AACvD,wBAAsB,UAAU,CAC9B,EAAE,EAAE,aAAa,EACjB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,QAAQ,CAAC,CAgBnB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,aAAa,EACjB,aAAa,EAAE,wBAAwB,EACvC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,IAAI,EACT,MAAM,CAAC,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,QAAQ,CAAC,CAuBnB;AAED,0GAA0G;AAC1G,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,IAAI,CAyC/D"}
|
package/dist/http/callbacks.js
CHANGED
|
@@ -15,14 +15,14 @@ import { validationHook } from "@pithy-sh/core/src/http/validation";
|
|
|
15
15
|
/** A 1×1 transparent PNG — the open-tracking pixel body. */
|
|
16
16
|
const PIXEL = Uint8Array.from(atob("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg=="), (c) => c.charCodeAt(0));
|
|
17
17
|
/** Verify a token and assert its kind, or throw `email/invalid_token`. */
|
|
18
|
-
async function verify(keys,
|
|
19
|
-
const claims = await verifyToken(token, keys, now);
|
|
18
|
+
async function verify(keys, request, expected, now) {
|
|
19
|
+
const claims = await verifyToken(request.token, keys, now, request.url);
|
|
20
20
|
if (claims.kind !== expected) throw new EmailInvalidTokenError({ detail: `token kind '${claims.kind}' does not match callback '${expected}'` });
|
|
21
21
|
return claims;
|
|
22
22
|
}
|
|
23
23
|
/** Handle a click: record it, then 302-redirect to the signed http(s) destination. */
|
|
24
|
-
async function handleClick(db, keys,
|
|
25
|
-
const claims = await verify(keys,
|
|
24
|
+
async function handleClick(db, keys, request, now) {
|
|
25
|
+
const claims = await verify(keys, request, "click", now);
|
|
26
26
|
const destination = claims.destination ?? "";
|
|
27
27
|
if (!/^https?:\/\//i.test(destination)) throw new EmailInvalidTokenError({ detail: "click token has no http(s) destination" });
|
|
28
28
|
await recordEvent(db, {
|
|
@@ -39,8 +39,11 @@ async function handleClick(db, keys, token, now) {
|
|
|
39
39
|
});
|
|
40
40
|
}
|
|
41
41
|
/** Handle an open: record it, return the 1×1 pixel. */
|
|
42
|
-
async function handleOpen(db, keys,
|
|
43
|
-
const claims = await verify(keys,
|
|
42
|
+
async function handleOpen(db, keys, request, now) {
|
|
43
|
+
const claims = await verify(keys, {
|
|
44
|
+
...request,
|
|
45
|
+
token: request.token.replace(/\.png$/i, "")
|
|
46
|
+
}, "open", now);
|
|
44
47
|
await recordEvent(db, {
|
|
45
48
|
jobId: claims.jobId,
|
|
46
49
|
recipient: normalizeAddress(claims.recipient),
|
|
@@ -61,8 +64,8 @@ async function handleOpen(db, keys, token, now) {
|
|
|
61
64
|
* param — is stored on the suppression `detail` and the event, so a project can capture *why* someone
|
|
62
65
|
* opted out using its own logic. It is length-bounded so the link can't be used to stuff the column.
|
|
63
66
|
*/
|
|
64
|
-
async function handleUnsubscribe(db, suppressionDb, keys,
|
|
65
|
-
const claims = await verify(keys,
|
|
67
|
+
async function handleUnsubscribe(db, suppressionDb, keys, request, now, reason, environment) {
|
|
68
|
+
const claims = await verify(keys, request, "unsubscribe", now);
|
|
66
69
|
const recipient = normalizeAddress(claims.recipient);
|
|
67
70
|
const detail = reason ? reason.slice(0, 200) : "unsubscribe link";
|
|
68
71
|
await suppress(suppressionDb, {
|
|
@@ -96,16 +99,25 @@ function registerCallbacks(app) {
|
|
|
96
99
|
};
|
|
97
100
|
app.get(`${CALLBACK_BASE}/c/:token`, zValidator("param", CallbackTokenParam, validationHook), async (c) => {
|
|
98
101
|
const { db, keys } = await setup(c.env);
|
|
99
|
-
return handleClick(db, keys,
|
|
102
|
+
return handleClick(db, keys, {
|
|
103
|
+
token: c.req.valid("param").token,
|
|
104
|
+
url: c.req.url
|
|
105
|
+
}, /* @__PURE__ */ new Date());
|
|
100
106
|
});
|
|
101
107
|
app.get(`${CALLBACK_BASE}/o/:token`, zValidator("param", CallbackTokenParam, validationHook), async (c) => {
|
|
102
108
|
const { db, keys } = await setup(c.env);
|
|
103
|
-
return handleOpen(db, keys,
|
|
109
|
+
return handleOpen(db, keys, {
|
|
110
|
+
token: c.req.valid("param").token,
|
|
111
|
+
url: c.req.url
|
|
112
|
+
}, /* @__PURE__ */ new Date());
|
|
104
113
|
});
|
|
105
114
|
app.on(["GET", "POST"], `${CALLBACK_BASE}/u/:token`, zValidator("param", CallbackTokenParam, validationHook), zValidator("query", UnsubscribeQuery, validationHook), async (c) => {
|
|
106
115
|
const env = c.env;
|
|
107
116
|
const { db, suppressionDb, keys } = await setup(env);
|
|
108
|
-
return handleUnsubscribe(db, suppressionDb, keys,
|
|
117
|
+
return handleUnsubscribe(db, suppressionDb, keys, {
|
|
118
|
+
token: c.req.valid("param").token,
|
|
119
|
+
url: c.req.url
|
|
120
|
+
}, /* @__PURE__ */ new Date(), c.req.valid("query").reason, env.ENVIRONMENT);
|
|
109
121
|
});
|
|
110
122
|
}
|
|
111
123
|
//#endregion
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
+
import { type RetainedRows } from "@pithy-sh/core/src/migrations/retained";
|
|
3
4
|
import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
|
|
4
|
-
import { type ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
|
|
5
|
+
import { type DeprovisionTarget, type ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
|
|
5
6
|
/**
|
|
6
7
|
* The provisioning orchestration for the email capability — the live counterpart to `pithy add email`'s
|
|
7
8
|
* config wiring. It stands up the durable infrastructure the rest of the capability assumes: the
|
|
@@ -21,7 +22,7 @@ import { type ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
|
|
|
21
22
|
*
|
|
22
23
|
* **Operator prerequisites (out of band, like the secrets store):** the sending domain must be onboarded
|
|
23
24
|
* onto Cloudflare Email Service, one Email Routing rule must point bounce/complaint mail at the production
|
|
24
|
-
* app worker, and the link-signing key must exist (`pithy secrets
|
|
25
|
+
* app worker, and the link-signing key must exist (`pithy secrets provision` creates each environment's Secrets Store entry). These
|
|
25
26
|
* are one-time account/DNS actions provisioning does not own.
|
|
26
27
|
*/
|
|
27
28
|
/** The capability segment every email-owned name carries — the migration namespace and error domain too. */
|
|
@@ -136,12 +137,23 @@ export interface EmailProvisionResult {
|
|
|
136
137
|
export declare function provisionEmail(provisioner: EmailProvisioner, environments: DeclaredEnvironments | readonly string[]): Promise<EmailProvisionResult>;
|
|
137
138
|
/** The teardown seam — the inverse of {@link EmailProvisioner}. Every step idempotent (a missing resource is a no-op). */
|
|
138
139
|
export interface EmailDeprovisioner {
|
|
140
|
+
/**
|
|
141
|
+
* The rows the suppression list holds, named by its database — empty when the database is absent. Read-only.
|
|
142
|
+
* What a teardown counts before it deletes the list (#591).
|
|
143
|
+
*/
|
|
144
|
+
countSuppressionRetained(): Promise<RetainedRows[]>;
|
|
145
|
+
/**
|
|
146
|
+
* Whether the env's email worker is deployed. Read-only. What a teardown asks of every *other* environment
|
|
147
|
+
* before it deletes the list they share (#591).
|
|
148
|
+
*/
|
|
149
|
+
hasWorker(env: ManagedEnvironment): Promise<boolean>;
|
|
139
150
|
/** Delete the env's email worker. Idempotent (a missing worker is a no-op). */
|
|
140
151
|
deleteWorker(env: ManagedEnvironment): Promise<void>;
|
|
141
152
|
/**
|
|
142
153
|
* Delete the shared suppression D1. **Destructive** — the global suppression list is lost, so every
|
|
143
154
|
* environment forgets who unsubscribed or hard-bounced — so the orchestration only calls it when
|
|
144
|
-
* explicitly asked. Idempotent.
|
|
155
|
+
* explicitly asked. Idempotent. A live implementation refuses while the list holds more rows than the
|
|
156
|
+
* operator agreed to destroy.
|
|
145
157
|
*/
|
|
146
158
|
deleteSuppressionDatabase(): Promise<void>;
|
|
147
159
|
}
|
|
@@ -149,15 +161,28 @@ export interface EmailDeprovisioner {
|
|
|
149
161
|
export interface EmailDeprovisionOptions {
|
|
150
162
|
/** Also delete the shared suppression database. Off by default; only a full destroy sets it. */
|
|
151
163
|
deleteSuppression?: boolean;
|
|
164
|
+
/**
|
|
165
|
+
* The operator's count of suppressed addresses to destroy — `--destroy-retained <n>`. With
|
|
166
|
+
* `deleteSuppression`, it must equal the rows the list holds; absent, only an empty list is deleted.
|
|
167
|
+
*/
|
|
168
|
+
destroyRetained?: number;
|
|
152
169
|
}
|
|
153
170
|
/**
|
|
154
|
-
* Tear down
|
|
155
|
-
*
|
|
156
|
-
*
|
|
171
|
+
* Tear down **one named environment's** email infrastructure, reversing {@link provisionEmail} for it.
|
|
172
|
+
*
|
|
173
|
+
* In order, and the order is the contract:
|
|
174
|
+
*
|
|
175
|
+
* 1. Resolve the target (`@pithy-sh/secrets`' `deprovisionTarget`) — refused with nothing read when none was
|
|
176
|
+
* named, or one the project does not declare. This used to walk every declared environment, so a run meant
|
|
177
|
+
* for staging removed production's email worker with it (#591).
|
|
178
|
+
* 2. With `deleteSuppression` only: refuse while any other declared environment still runs an email worker
|
|
179
|
+
* (`assertSharedLeavesLast`). The list is one per project, and a staging teardown must not take production's.
|
|
180
|
+
* 3. Count the list, and refuse unless the operator counted the same (`assertRetainedAgreed`, #588's guard).
|
|
181
|
+
* 4. Delete the environment's worker (it binds the list), then — only when asked — the list.
|
|
157
182
|
*
|
|
158
|
-
*
|
|
159
|
-
* environment is provisioned; an environment this skipped would be one the project deploys to with no
|
|
160
|
-
* resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
|
|
183
|
+
* Idempotent end to end: a missing worker or database is a no-op.
|
|
161
184
|
*/
|
|
162
|
-
export declare function deprovisionEmail(deprovisioner: EmailDeprovisioner,
|
|
185
|
+
export declare function deprovisionEmail(deprovisioner: EmailDeprovisioner, target: DeprovisionTarget, options?: EmailDeprovisionOptions): Promise<{
|
|
186
|
+
env: ManagedEnvironment;
|
|
187
|
+
}>;
|
|
163
188
|
//# sourceMappingURL=provisionEmail.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"provisionEmail.d.ts","sourceRoot":"","sources":["../../src/provision/provisionEmail.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAKlF,OAAO,
|
|
1
|
+
{"version":3,"file":"provisionEmail.d.ts","sourceRoot":"","sources":["../../src/provision/provisionEmail.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,wCAAwC,CAAC;AACjG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAKlF,OAAO,EAEL,KAAK,iBAAiB,EAEtB,KAAK,kBAAkB,EAExB,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,4GAA4G;AAC5G,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC,kGAAkG;AAClG,eAAO,MAAM,0BAA0B,uBAAuB,CAAC;AAW/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAEhF;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,6GAA6G;IAC7G,yBAAyB,IAAI,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,8GAA8G;IAC9G,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,sHAAsH;IACtH,YAAY,CAAC,GAAG,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF;;;;;OAKG;IACH,iBAAiB,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,kCAAkC;AAClC,MAAM,WAAW,oBAAoB;IACnC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,kGAAkG;IAClG,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CACjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,gBAAgB,EAC7B,YAAY,EAAE,oBAAoB,GAAG,SAAS,MAAM,EAAE,GACrD,OAAO,CAAC,oBAAoB,CAAC,CAc/B;AAED,0HAA0H;AAC1H,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,wBAAwB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACpD;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD,+EAA+E;IAC/E,YAAY,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD;;;;;OAKG;IACH,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,+GAA+G;AAC/G,MAAM,WAAW,uBAAuB;IACtC,gGAAgG;IAChG,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,aAAa,EAAE,kBAAkB,EACjC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC;IAAE,GAAG,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAgBtC"}
|
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
|
-
import { GLOBAL_SCOPE } from "@pithy-sh/core/src/naming/environment";
|
|
4
3
|
import { bindingResourceName } from "@pithy-sh/core/src/naming/provisionScope";
|
|
4
|
+
import { assertRetainedAgreed } from "@pithy-sh/core/src/migrations/retained";
|
|
5
|
+
import { GLOBAL_SCOPE } from "@pithy-sh/core/src/naming/environment";
|
|
5
6
|
import { resourceName } from "@pithy-sh/core/src/naming/resource";
|
|
6
7
|
import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
|
|
7
|
-
import { managedEnvironments } from "@pithy-sh/secrets/src/scope";
|
|
8
|
+
import { assertSharedLeavesLast, deprovisionTarget, managedEnvironments } from "@pithy-sh/secrets/src/scope";
|
|
8
9
|
//#region src/provision/provisionEmail.ts
|
|
9
10
|
/**
|
|
10
11
|
* The provisioning orchestration for the email capability — the live counterpart to `pithy add email`'s
|
|
@@ -25,7 +26,7 @@ import { managedEnvironments } from "@pithy-sh/secrets/src/scope";
|
|
|
25
26
|
*
|
|
26
27
|
* **Operator prerequisites (out of band, like the secrets store):** the sending domain must be onboarded
|
|
27
28
|
* onto Cloudflare Email Service, one Email Routing rule must point bounce/complaint mail at the production
|
|
28
|
-
* app worker, and the link-signing key must exist (`pithy secrets
|
|
29
|
+
* app worker, and the link-signing key must exist (`pithy secrets provision` creates each environment's Secrets Store entry). These
|
|
29
30
|
* are one-time account/DNS actions provisioning does not own.
|
|
30
31
|
*/
|
|
31
32
|
/** The capability segment every email-owned name carries — the migration namespace and error domain too. */
|
|
@@ -134,17 +135,32 @@ async function provisionEmail(provisioner, environments) {
|
|
|
134
135
|
};
|
|
135
136
|
}
|
|
136
137
|
/**
|
|
137
|
-
* Tear down
|
|
138
|
-
*
|
|
139
|
-
*
|
|
138
|
+
* Tear down **one named environment's** email infrastructure, reversing {@link provisionEmail} for it.
|
|
139
|
+
*
|
|
140
|
+
* In order, and the order is the contract:
|
|
141
|
+
*
|
|
142
|
+
* 1. Resolve the target (`@pithy-sh/secrets`' `deprovisionTarget`) — refused with nothing read when none was
|
|
143
|
+
* named, or one the project does not declare. This used to walk every declared environment, so a run meant
|
|
144
|
+
* for staging removed production's email worker with it (#591).
|
|
145
|
+
* 2. With `deleteSuppression` only: refuse while any other declared environment still runs an email worker
|
|
146
|
+
* (`assertSharedLeavesLast`). The list is one per project, and a staging teardown must not take production's.
|
|
147
|
+
* 3. Count the list, and refuse unless the operator counted the same (`assertRetainedAgreed`, #588's guard).
|
|
148
|
+
* 4. Delete the environment's worker (it binds the list), then — only when asked — the list.
|
|
140
149
|
*
|
|
141
|
-
*
|
|
142
|
-
* environment is provisioned; an environment this skipped would be one the project deploys to with no
|
|
143
|
-
* resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
|
|
150
|
+
* Idempotent end to end: a missing worker or database is a no-op.
|
|
144
151
|
*/
|
|
145
|
-
async function deprovisionEmail(deprovisioner,
|
|
146
|
-
|
|
152
|
+
async function deprovisionEmail(deprovisioner, target, options = {}) {
|
|
153
|
+
const env = deprovisionTarget(target);
|
|
154
|
+
if (options.deleteSuppression) {
|
|
155
|
+
await assertSharedLeavesLast(env, target.declared, (other) => deprovisioner.hasWorker(other), [{
|
|
156
|
+
what: "the suppression list",
|
|
157
|
+
flag: "--suppression"
|
|
158
|
+
}]);
|
|
159
|
+
assertRetainedAgreed(await deprovisioner.countSuppressionRetained(), options.destroyRetained, "anything was deleted");
|
|
160
|
+
}
|
|
161
|
+
await deprovisioner.deleteWorker(env);
|
|
147
162
|
if (options.deleteSuppression) await deprovisioner.deleteSuppressionDatabase();
|
|
163
|
+
return { env };
|
|
148
164
|
}
|
|
149
165
|
//#endregion
|
|
150
166
|
export { EMAIL_CAPABILITY, EMAIL_SUPPRESSIONS_BINDING, bounceRoutingRuleName, deprovisionEmail, emailWorkerName, provisionEmail, suppressionDatabaseName };
|
|
@@ -78,9 +78,9 @@ export interface EmailConfigParams {
|
|
|
78
78
|
appDatabaseId: string;
|
|
79
79
|
/** The shared suppression database id (same in every environment). */
|
|
80
80
|
suppressionDatabaseId: string;
|
|
81
|
-
/** This environment's secrets database id (`<project>-<env>-secrets`)
|
|
81
|
+
/** This environment's secrets database id (`<project>-<env>-secrets`). The signing key is not in it (#596). */
|
|
82
82
|
secretsDatabaseId: string;
|
|
83
|
-
/** The CF Secrets Store id holding the per-env master key. */
|
|
83
|
+
/** The CF Secrets Store id holding the per-env master key and the per-env link-signing key. */
|
|
84
84
|
storeId: string;
|
|
85
85
|
/** The app worker's public base URL for this environment — callback links are built against it. */
|
|
86
86
|
baseUrl: string;
|
|
@@ -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,CAsC7B"}
|