@pithy-sh/email 0.3.11 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +5 -1
- package/dist/http/callbacks.d.ts.map +1 -1
- package/dist/http/callbacks.js +26 -5
- package/dist/http/routes.d.ts +1 -1
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +42 -10
- package/dist/provision/provisionEmail.d.ts +7 -1
- package/dist/provision/provisionEmail.d.ts.map +1 -1
- package/dist/provision/provisionEmail.js +2 -1
- package/dist/provision/settingsCheck.d.ts.map +1 -1
- package/dist/provision/settingsCheck.js +44 -7
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.d.ts.map +1 -1
- package/dist/version.generated.js +1 -1
- package/dist/workflows/hostEnv.d.ts +41 -0
- package/dist/workflows/hostEnv.d.ts.map +1 -1
- package/dist/workflows/hostEnv.js +14 -7
- package/package.json +5 -5
- package/src/capability.ts +2 -1
- package/src/http/callbacks.ts +41 -12
- package/src/http/routes.ts +49 -11
- package/src/http/schemas.ts +1 -1
- package/src/provision/provisionEmail.ts +9 -4
- package/src/provision/settingsCheck.ts +48 -9
- package/src/version.generated.ts +1 -1
- package/src/workflows/hostEnv.ts +13 -6
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;
|
|
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;AAG7F,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,CAqN/D;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
|
package/dist/capability.js
CHANGED
|
@@ -19,6 +19,7 @@ import { PACKAGE_NAME, PACKAGE_VERSION } from "./version.generated.js";
|
|
|
19
19
|
import { EmailScheduleParams, EmailSendParams } from "./workflows/params.js";
|
|
20
20
|
import { z } from "zod";
|
|
21
21
|
import { defineCapability } from "@pithy-sh/core/src/capability/capability";
|
|
22
|
+
import { pithyCommandOf } from "@pithy-sh/core/src/cli/command";
|
|
22
23
|
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
23
24
|
//#region src/capability.ts
|
|
24
25
|
/**
|
|
@@ -221,7 +222,10 @@ function email(config) {
|
|
|
221
222
|
const binding = env.EMAIL_SUPPRESSIONS;
|
|
222
223
|
if (!binding) throw new InternalError({
|
|
223
224
|
message: "The suppression list is not available.",
|
|
224
|
-
action:
|
|
225
|
+
action: `Run \`${pithyCommandOf("add", {
|
|
226
|
+
args: ["email"],
|
|
227
|
+
flags: { "--with-prerequisites": true }
|
|
228
|
+
}, { runtime: true })}\` to provision it, or bind the EMAIL_SUPPRESSIONS D1 database.`,
|
|
225
229
|
detail: "email.suppressions() was called with an env carrying no `EMAIL_SUPPRESSIONS` D1 binding."
|
|
226
230
|
});
|
|
227
231
|
return emailSuppressionDatabase(binding);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"callbacks.d.ts","sourceRoot":"","sources":["../../src/http/callbacks.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"callbacks.d.ts","sourceRoot":"","sources":["../../src/http/callbacks.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAI7E,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,CAsE/D"}
|
package/dist/http/callbacks.js
CHANGED
|
@@ -9,8 +9,8 @@ import { verifyToken } from "../crypto/token.js";
|
|
|
9
9
|
import { CALLBACK_BASE } from "../templates/engine.js";
|
|
10
10
|
import { CallbackTokenParam, UnsubscribeQuery } from "./schemas.js";
|
|
11
11
|
import { normalizeAddress } from "@pithy-sh/core/src/address/address";
|
|
12
|
-
import {
|
|
13
|
-
import {
|
|
12
|
+
import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
|
|
13
|
+
import { validate } from "@pithy-sh/core/src/http/validation";
|
|
14
14
|
//#region src/http/callbacks.ts
|
|
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));
|
|
@@ -97,21 +97,42 @@ function registerCallbacks(app) {
|
|
|
97
97
|
keys: { versions: keys.versions }
|
|
98
98
|
};
|
|
99
99
|
};
|
|
100
|
-
app.get(`${CALLBACK_BASE}/c/:token`,
|
|
100
|
+
app.get(`${CALLBACK_BASE}/c/:token`, describeRoute({
|
|
101
|
+
summary: "Record a click on a tracked link, then send the reader on to it.",
|
|
102
|
+
description: "Public: the HMAC signature on the token is the only gate. A forged, altered, or expired token answers `email/invalid_token` (400) before anything is recorded, and the destination is the http(s) URL signed into the token, never one from the request.",
|
|
103
|
+
verification: "public",
|
|
104
|
+
responses: { 302: { description: "A redirect to the link's destination, carried in `Location`." } }
|
|
105
|
+
}), validate("param", CallbackTokenParam), async (c) => {
|
|
101
106
|
const { db, keys } = await setup(c.env);
|
|
102
107
|
return handleClick(db, keys, {
|
|
103
108
|
token: c.req.valid("param").token,
|
|
104
109
|
url: c.req.url
|
|
105
110
|
}, /* @__PURE__ */ new Date());
|
|
106
111
|
});
|
|
107
|
-
app.get(`${CALLBACK_BASE}/o/:token`,
|
|
112
|
+
app.get(`${CALLBACK_BASE}/o/:token`, describeRoute({
|
|
113
|
+
summary: "Record that an email was opened.",
|
|
114
|
+
description: "Public: the HMAC signature on the token is the only gate. The token may carry the `.png` suffix mail clients expect on an image URL.",
|
|
115
|
+
verification: "public",
|
|
116
|
+
responses: { 200: {
|
|
117
|
+
description: "A 1×1 transparent PNG, never cached.",
|
|
118
|
+
contentType: "image/png"
|
|
119
|
+
} }
|
|
120
|
+
}), validate("param", CallbackTokenParam), async (c) => {
|
|
108
121
|
const { db, keys } = await setup(c.env);
|
|
109
122
|
return handleOpen(db, keys, {
|
|
110
123
|
token: c.req.valid("param").token,
|
|
111
124
|
url: c.req.url
|
|
112
125
|
}, /* @__PURE__ */ new Date());
|
|
113
126
|
});
|
|
114
|
-
app.on(["GET", "POST"], `${CALLBACK_BASE}/u/:token`,
|
|
127
|
+
app.on(["GET", "POST"], `${CALLBACK_BASE}/u/:token`, describeRoute({
|
|
128
|
+
summary: "Unsubscribe the recipient from everything but the mail they ask for.",
|
|
129
|
+
description: "Public: the HMAC signature on the token is the only gate. Answers GET for the link in the message and POST for one-click unsubscribe. The address joins the suppression list shared by every environment.",
|
|
130
|
+
verification: "public",
|
|
131
|
+
responses: { 200: {
|
|
132
|
+
description: "A short HTML page confirming the opt-out.",
|
|
133
|
+
contentType: "text/html"
|
|
134
|
+
} }
|
|
135
|
+
}), validate("param", CallbackTokenParam), validate("query", UnsubscribeQuery), async (c) => {
|
|
115
136
|
const env = c.env;
|
|
116
137
|
const { db, suppressionDb, keys } = await setup(env);
|
|
117
138
|
return handleUnsubscribe(db, suppressionDb, keys, {
|
package/dist/http/routes.d.ts
CHANGED
|
@@ -49,7 +49,7 @@ export interface EmailRouteDeclaration {
|
|
|
49
49
|
* Every management route, and how it is gated.
|
|
50
50
|
*
|
|
51
51
|
* Exported so a test can assert against the declaration rather than against a middleware count. A count
|
|
52
|
-
* proves that *something* runs before the handler — a bare `
|
|
52
|
+
* proves that *something* runs before the handler — a bare `validate` satisfies it — and cannot prove
|
|
53
53
|
* *what*. `routeContract.test.ts` checks this list against the paths Hono actually registered, in both
|
|
54
54
|
* directions, so a route added without an entry and an entry without a route both fail.
|
|
55
55
|
*/
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAKrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAEjF,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AA+B1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,yGAAyG;AACzG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,qBAAqB,EAY9D,CAAC;AAaF,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAiDD,yFAAyF;AACzF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CA+T5G"}
|
package/dist/http/routes.js
CHANGED
|
@@ -8,18 +8,20 @@ import { EmailAuditActions } from "../audit/actions.js";
|
|
|
8
8
|
import { getJob, listJobs } from "../jobs/read.js";
|
|
9
9
|
import { retryJob } from "../jobs/retry.js";
|
|
10
10
|
import { emailSenderBinding } from "../send/senderBinding.js";
|
|
11
|
+
import { EmailJobResponse, EmailJobRetryResponse, EmailJobsResponse, EmailSuppressResponse, EmailSuppressionsResponse, EmailUnsuppressResponse } from "./responses.js";
|
|
11
12
|
import { jobDetailView, jobListView, suppressionView } from "./view.js";
|
|
12
13
|
import { ConflictError, InternalError, NotFoundError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
|
|
13
14
|
import { normalizeAddress } from "@pithy-sh/core/src/address/address";
|
|
14
|
-
import {
|
|
15
|
-
import {
|
|
15
|
+
import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
|
|
16
|
+
import { validate } from "@pithy-sh/core/src/http/validation";
|
|
16
17
|
import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
|
|
18
|
+
import { migrateStep } from "@pithy-sh/core/src/migrations/migrateStep";
|
|
17
19
|
//#region src/http/routes.ts
|
|
18
20
|
/**
|
|
19
21
|
* Every management route, and how it is gated.
|
|
20
22
|
*
|
|
21
23
|
* Exported so a test can assert against the declaration rather than against a middleware count. A count
|
|
22
|
-
* proves that *something* runs before the handler — a bare `
|
|
24
|
+
* proves that *something* runs before the handler — a bare `validate` satisfies it — and cannot prove
|
|
23
25
|
* *what*. `routeContract.test.ts` checks this list against the paths Hono actually registered, in both
|
|
24
26
|
* directions, so a route added without an entry and an entry without a route both fail.
|
|
25
27
|
*/
|
|
@@ -72,7 +74,7 @@ function d1(c, binding) {
|
|
|
72
74
|
const found = c.env[binding];
|
|
73
75
|
if (!found) throw new InternalError({
|
|
74
76
|
message: "Email is not fully configured on this Worker.",
|
|
75
|
-
action: `Bind a D1 database named ${binding} in wrangler.jsonc, then
|
|
77
|
+
action: `Bind a D1 database named ${binding} in wrangler.jsonc, then ${migrateStep(c.env)}.`,
|
|
76
78
|
detail: `the email management routes require a \`${binding}\` D1 binding; none was present on env`
|
|
77
79
|
});
|
|
78
80
|
return found;
|
|
@@ -105,7 +107,12 @@ function registerEmailAdminRoutes(options) {
|
|
|
105
107
|
const base = options.basePath;
|
|
106
108
|
const clock = options.now ?? (() => /* @__PURE__ */ new Date());
|
|
107
109
|
return (app) => {
|
|
108
|
-
app.get(`${base}/jobs`,
|
|
110
|
+
app.get(`${base}/jobs`, describeRoute({
|
|
111
|
+
summary: "Page through the send log.",
|
|
112
|
+
verification: "control-plane",
|
|
113
|
+
scopes: [EMAIL_JOBS_READ_SCOPE],
|
|
114
|
+
responses: { 200: EmailJobsResponse }
|
|
115
|
+
}), requireControlPlane(EMAIL_JOBS_READ_SCOPE), validate("query", JobsQuery), async (c) => {
|
|
109
116
|
const query = c.req.valid("query");
|
|
110
117
|
const who = caller(c);
|
|
111
118
|
const page = await listJobs(jobs(c), query);
|
|
@@ -128,7 +135,12 @@ function registerEmailAdminRoutes(options) {
|
|
|
128
135
|
nextCursor: page.nextCursor
|
|
129
136
|
});
|
|
130
137
|
});
|
|
131
|
-
app.get(`${base}/jobs/:id`,
|
|
138
|
+
app.get(`${base}/jobs/:id`, describeRoute({
|
|
139
|
+
summary: "Read one email job in full, recipient included.",
|
|
140
|
+
verification: "control-plane",
|
|
141
|
+
scopes: [EMAIL_JOBS_READ_SCOPE],
|
|
142
|
+
responses: { 200: EmailJobResponse }
|
|
143
|
+
}), requireControlPlane(EMAIL_JOBS_READ_SCOPE), validate("param", JobIdParam), async (c) => {
|
|
132
144
|
const { id } = c.req.valid("param");
|
|
133
145
|
const who = caller(c);
|
|
134
146
|
const job = await getJob(jobs(c), id);
|
|
@@ -152,7 +164,12 @@ function registerEmailAdminRoutes(options) {
|
|
|
152
164
|
});
|
|
153
165
|
return c.json({ job: jobDetailView(job) });
|
|
154
166
|
});
|
|
155
|
-
app.post(`${base}/jobs/:id/retry`,
|
|
167
|
+
app.post(`${base}/jobs/:id/retry`, describeRoute({
|
|
168
|
+
summary: "Queue a job to send again.",
|
|
169
|
+
verification: "control-plane",
|
|
170
|
+
scopes: [EMAIL_JOBS_RETRY_SCOPE],
|
|
171
|
+
responses: { 200: EmailJobRetryResponse }
|
|
172
|
+
}), requireControlPlane(EMAIL_JOBS_RETRY_SCOPE), validate("param", JobIdParam), async (c) => {
|
|
156
173
|
const { id } = c.req.valid("param");
|
|
157
174
|
const who = caller(c);
|
|
158
175
|
const now = clock();
|
|
@@ -184,7 +201,12 @@ function registerEmailAdminRoutes(options) {
|
|
|
184
201
|
dispatched: result.dispatched
|
|
185
202
|
});
|
|
186
203
|
});
|
|
187
|
-
app.get(`${base}/suppressions`,
|
|
204
|
+
app.get(`${base}/suppressions`, describeRoute({
|
|
205
|
+
summary: "Page through the suppression list, or look one address up.",
|
|
206
|
+
verification: "control-plane",
|
|
207
|
+
scopes: [EMAIL_SUPPRESSIONS_READ_SCOPE],
|
|
208
|
+
responses: { 200: EmailSuppressionsResponse }
|
|
209
|
+
}), requireControlPlane(EMAIL_SUPPRESSIONS_READ_SCOPE), validate("query", SuppressionsQuery), async (c) => {
|
|
188
210
|
const query = c.req.valid("query");
|
|
189
211
|
const who = caller(c);
|
|
190
212
|
const now = clock();
|
|
@@ -209,7 +231,12 @@ function registerEmailAdminRoutes(options) {
|
|
|
209
231
|
nextCursor: page.nextCursor
|
|
210
232
|
});
|
|
211
233
|
});
|
|
212
|
-
app.post(`${base}/suppressions`,
|
|
234
|
+
app.post(`${base}/suppressions`, describeRoute({
|
|
235
|
+
summary: "Block an address by hand.",
|
|
236
|
+
verification: "control-plane",
|
|
237
|
+
scopes: [EMAIL_SUPPRESSIONS_WRITE_SCOPE],
|
|
238
|
+
responses: { 200: EmailSuppressResponse }
|
|
239
|
+
}), requireControlPlane(EMAIL_SUPPRESSIONS_WRITE_SCOPE), validate("json", SuppressRequest), async (c) => {
|
|
213
240
|
const input = c.req.valid("json");
|
|
214
241
|
const who = caller(c);
|
|
215
242
|
const now = clock();
|
|
@@ -258,7 +285,12 @@ function registerEmailAdminRoutes(options) {
|
|
|
258
285
|
});
|
|
259
286
|
return c.json({ suppression: row ? suppressionView(row, now) : null }, 200);
|
|
260
287
|
});
|
|
261
|
-
app.post(`${base}/suppressions/remove`,
|
|
288
|
+
app.post(`${base}/suppressions/remove`, describeRoute({
|
|
289
|
+
summary: "Lift the block on an address.",
|
|
290
|
+
verification: "control-plane",
|
|
291
|
+
scopes: [EMAIL_SUPPRESSIONS_DELETE_SCOPE],
|
|
292
|
+
responses: { 200: EmailUnsuppressResponse }
|
|
293
|
+
}), requireControlPlane(EMAIL_SUPPRESSIONS_DELETE_SCOPE), validate("json", UnsuppressRequest), async (c) => {
|
|
262
294
|
const input = c.req.valid("json");
|
|
263
295
|
const who = caller(c);
|
|
264
296
|
const email = normalizeAddress(input.email);
|
|
@@ -91,9 +91,13 @@ export interface EmailProvisioner {
|
|
|
91
91
|
* Throws a clear, actionable error so provisioning fails fast and clean rather than mid-deploy.
|
|
92
92
|
*/
|
|
93
93
|
preflight(): Promise<void>;
|
|
94
|
-
/**
|
|
94
|
+
/**
|
|
95
|
+
* Create (or reuse) the project's suppression D1; returns its id, and whether this call created it. Idempotent.
|
|
96
|
+
* Runs once, before any env.
|
|
97
|
+
*/
|
|
95
98
|
ensureSuppressionDatabase(): Promise<{
|
|
96
99
|
databaseId: string;
|
|
100
|
+
created: boolean;
|
|
97
101
|
}>;
|
|
98
102
|
/** Run the `email_0001_suppressions` migration against the suppression D1. Idempotent (applied ones skip). */
|
|
99
103
|
migrateSuppression(databaseId: string): Promise<void>;
|
|
@@ -113,6 +117,8 @@ export interface EmailProvisioner {
|
|
|
113
117
|
/** What provisioning produced. */
|
|
114
118
|
export interface EmailProvisionResult {
|
|
115
119
|
suppressionDatabaseId: string;
|
|
120
|
+
/** Whether this run created the suppression database, or found one an earlier run made. */
|
|
121
|
+
suppressionDatabaseCreated: boolean;
|
|
116
122
|
environments: ManagedEnvironment[];
|
|
117
123
|
/** Whether the inbound routing rule was created, already present, or skipped (not configured). */
|
|
118
124
|
routing: {
|
|
@@ -1 +1 @@
|
|
|
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
|
|
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;;;OAGG;IACH,yBAAyB,IAAI,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC/E,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,2FAA2F;IAC3F,0BAA0B,EAAE,OAAO,CAAC;IACpC,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"}
|
|
@@ -121,12 +121,13 @@ function emailWorkerName(project, env) {
|
|
|
121
121
|
*/
|
|
122
122
|
async function provisionEmail(provisioner, environments) {
|
|
123
123
|
await provisioner.preflight();
|
|
124
|
-
const { databaseId } = await provisioner.ensureSuppressionDatabase();
|
|
124
|
+
const { databaseId, created } = await provisioner.ensureSuppressionDatabase();
|
|
125
125
|
await provisioner.migrateSuppression(databaseId);
|
|
126
126
|
const deployed = managedEnvironments(environments);
|
|
127
127
|
for (const env of deployed) await provisioner.deployWorker(env, databaseId);
|
|
128
128
|
return {
|
|
129
129
|
suppressionDatabaseId: databaseId,
|
|
130
|
+
suppressionDatabaseCreated: created,
|
|
130
131
|
environments: deployed,
|
|
131
132
|
routing: deployed.length > 0 ? await provisioner.ensureRoutingRule() : {
|
|
132
133
|
created: false,
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"settingsCheck.d.ts","sourceRoot":"","sources":["../../src/provision/settingsCheck.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,wCAAwC,CAAC;
|
|
1
|
+
{"version":3,"file":"settingsCheck.d.ts","sourceRoot":"","sources":["../../src/provision/settingsCheck.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAInB,MAAM,wCAAwC,CAAC;AAOhD,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;AA6PD,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAS5E"}
|
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
import { EMAIL_LINK_SIGNING_KEY, EMAIL_LINK_SIGNING_KEY_BINDING, emailSigningRegistry } from "../crypto/signingKey.js";
|
|
4
|
-
import { emailHostEnv } from "../workflows/hostEnv.js";
|
|
4
|
+
import { EMAIL_PROVISION, emailHostEnv } from "../workflows/hostEnv.js";
|
|
5
5
|
import { suppressionDatabaseName } from "./provisionEmail.js";
|
|
6
|
+
import { personDecision, pithyCommand, remedy, workerDirOf } from "@pithy-sh/core/src/cli/command";
|
|
6
7
|
import { hostEnvFindings } from "@pithy-sh/core/src/capability/settings";
|
|
7
8
|
import "@pithy-sh/core/src/naming/domains";
|
|
8
9
|
import { environmentScope } from "@pithy-sh/core/src/naming/provisionScope";
|
|
@@ -54,13 +55,39 @@ function originOf(url) {
|
|
|
54
55
|
* config object per Worker, so a `BASE_URL` that is not a URL is one edit however many environments a
|
|
55
56
|
* project declares. Three lines about one key is how a report stops being read.
|
|
56
57
|
*/
|
|
57
|
-
function localHostEnv(config) {
|
|
58
|
+
function localHostEnv(config, workerDirectory) {
|
|
58
59
|
const candidate = {
|
|
59
60
|
...stubBindings(),
|
|
60
61
|
BASE_URL: config.baseUrl,
|
|
61
62
|
...config.theme ? { EMAIL_THEME: JSON.stringify(config.theme) } : {}
|
|
62
63
|
};
|
|
63
|
-
return hostEnvFindings(checkHostEnv(emailHostEnv, candidate), null);
|
|
64
|
+
return hostEnvFindings(forWorker(checkHostEnv(emailHostEnv, candidate), workerDirectory), null);
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* **`pithy email provision` for the Worker this check ran for (#711).** It acts on one Worker, and in a project
|
|
68
|
+
* with several a bare one is refused `input/required`. Takes the Worker's `apps/` directory, which is what
|
|
69
|
+
* `--worker` takes and what that refusal lists. Not its `wrangler.jsonc` name: a scaffold deploys `apps/api` as
|
|
70
|
+
* `acme-api`.
|
|
71
|
+
*/
|
|
72
|
+
function provisionCommand(workerDirectory) {
|
|
73
|
+
return pithyCommand("email provision", { flags: { "--worker": workerDirOf({ dir: workerDirectory }) } });
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* The host's own report, with its provisioning command named for this Worker by its `apps/` directory. The host
|
|
77
|
+
* writes the bare command into its log because it cannot know the Worker; a check that does know names it, in
|
|
78
|
+
* the action and the `fix` alike.
|
|
79
|
+
*/
|
|
80
|
+
function forWorker(report, workerDirectory) {
|
|
81
|
+
return {
|
|
82
|
+
...report,
|
|
83
|
+
problems: report.problems.map((problem) => problem.provider.command === EMAIL_PROVISION ? {
|
|
84
|
+
...problem,
|
|
85
|
+
provider: {
|
|
86
|
+
...problem.provider,
|
|
87
|
+
command: provisionCommand(workerDirectory)
|
|
88
|
+
}
|
|
89
|
+
} : problem)
|
|
90
|
+
};
|
|
64
91
|
}
|
|
65
92
|
/**
|
|
66
93
|
* Whether a URL points at this machine — {@link LOCAL_ORIGIN} and every spelling of it, port or none.
|
|
@@ -141,7 +168,8 @@ async function accountFindings(config, context) {
|
|
|
141
168
|
setting: "EMAIL_SUPPRESSIONS",
|
|
142
169
|
environment: null,
|
|
143
170
|
problem: `No D1 database named ${suppressions} exists on this account.`,
|
|
144
|
-
action:
|
|
171
|
+
action: `Run \`${provisionCommand(context.workerDirectory)}\`. Nothing is suppressed until it exists.`,
|
|
172
|
+
fix: provisionCommand(context.workerDirectory)
|
|
145
173
|
});
|
|
146
174
|
for (const environment of context.environments) {
|
|
147
175
|
if (environment.name === "dev") continue;
|
|
@@ -165,6 +193,8 @@ async function accountFindings(config, context) {
|
|
|
165
193
|
* **What this sees:** a row under this registry name. A secret some other declaration moved off D1 has its
|
|
166
194
|
* own check to write, or none; nothing here walks the vault for strays, because the vault cannot be listed.
|
|
167
195
|
*/
|
|
196
|
+
/** What creates a missing link-signing entry: a provision of every environment, production included (#711). */
|
|
197
|
+
const PROVISION_SECRETS = remedy("secrets provision");
|
|
168
198
|
async function signingKeyFindings(context, environment) {
|
|
169
199
|
const findings = [];
|
|
170
200
|
const entry = environmentScope(context.project, environment).secretEntry(EMAIL_LINK_SIGNING_KEY, emailSigningRegistry[EMAIL_LINK_SIGNING_KEY].scope);
|
|
@@ -172,7 +202,8 @@ async function signingKeyFindings(context, environment) {
|
|
|
172
202
|
setting: EMAIL_LINK_SIGNING_KEY,
|
|
173
203
|
environment,
|
|
174
204
|
problem: `The link-signing key has no Secrets Store entry in ${environment}, so no tracking or unsubscribe link can be signed.`,
|
|
175
|
-
action:
|
|
205
|
+
action: PROVISION_SECRETS.say((command) => `Run \`${command}\`.`),
|
|
206
|
+
...PROVISION_SECRETS.fix === void 0 ? {} : { fix: PROVISION_SECRETS.fix }
|
|
176
207
|
});
|
|
177
208
|
if (await context.account.vaultSecret({
|
|
178
209
|
name: "email-link-signing-key",
|
|
@@ -181,7 +212,13 @@ async function signingKeyFindings(context, environment) {
|
|
|
181
212
|
setting: EMAIL_LINK_SIGNING_KEY,
|
|
182
213
|
environment,
|
|
183
214
|
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,
|
|
215
|
+
action: `Once the Secrets Store entry is bound and deployed, the D1 copy can go: ${personDecision("secrets rm", {
|
|
216
|
+
args: [EMAIL_LINK_SIGNING_KEY],
|
|
217
|
+
flags: {
|
|
218
|
+
"--env": environment,
|
|
219
|
+
"--backend": "d1"
|
|
220
|
+
}
|
|
221
|
+
})} See docs/commands/secrets.md#moving-a-secret-off-d1.`
|
|
185
222
|
});
|
|
186
223
|
return findings;
|
|
187
224
|
}
|
|
@@ -189,7 +226,7 @@ async function signingKeyFindings(context, environment) {
|
|
|
189
226
|
function emailSettings(config) {
|
|
190
227
|
return {
|
|
191
228
|
local: (context) => [
|
|
192
|
-
...localHostEnv(config),
|
|
229
|
+
...localHostEnv(config, context.workerDirectory),
|
|
193
230
|
...localForAddress(config),
|
|
194
231
|
...localBaseUrlOrigin(config, context)
|
|
195
232
|
],
|
|
@@ -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.
|
|
6
|
+
export declare const PACKAGE_VERSION = "0.4.0";
|
|
7
7
|
//# sourceMappingURL=version.generated.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,oBAAoB,CAAC;AAE9C,oFAAoF;AACpF,eAAO,MAAM,eAAe,
|
|
1
|
+
{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,oBAAoB,CAAC;AAE9C,oFAAoF;AACpF,eAAO,MAAM,eAAe,UAAU,CAAC"}
|
|
@@ -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.
|
|
7
|
+
const PACKAGE_VERSION = "0.4.0";
|
|
8
8
|
//#endregion
|
|
9
9
|
export { PACKAGE_NAME, PACKAGE_VERSION };
|
|
@@ -5,6 +5,47 @@ import type { SecretBinding } from "@pithy-sh/secrets/src/env/bindings";
|
|
|
5
5
|
import { z } from "zod";
|
|
6
6
|
import type { EmailSender } from "../send/sender";
|
|
7
7
|
import type { SendWorkflowInstances } from "./instances";
|
|
8
|
+
/**
|
|
9
|
+
* What the prebuilt email host worker reads out of its env — declared once, validated at boot, and
|
|
10
|
+
* read statically by `pithy doctor` (pithy-sh/pithy#410, #411).
|
|
11
|
+
*
|
|
12
|
+
* Nobody authors this Worker. `pithy email provision` resolves the committed template beside this
|
|
13
|
+
* file and deploys it, so every value here arrives as a binding, a var or a Secrets Store entry that
|
|
14
|
+
* a *machine* wrote — and until this module, none of it was checked. Three failures, all of them
|
|
15
|
+
* discovered as mail that did not arrive:
|
|
16
|
+
*
|
|
17
|
+
* - `BASE_URL` absent → every magic link in the batch pointed at `undefined/auth/…`.
|
|
18
|
+
* - `EMAIL_THEME` unparseable → a `JSON.parse` threw inside a render step, three retries deep,
|
|
19
|
+
* where the message reads as a template fault.
|
|
20
|
+
* - `SCHEDULER_BATCH_SIZE` written `"fifty"` → `Number(...)` gave `NaN`, the scheduler claimed
|
|
21
|
+
* nothing, and it did so on every tick, forever, without a line in the log.
|
|
22
|
+
*
|
|
23
|
+
* So the parse is the boot check: `z.output` is what the host actually runs on, which is why the
|
|
24
|
+
* coercions live in the schema rather than at the call sites. `Number(env.MAX_ATTEMPTS ?? 5)` in
|
|
25
|
+
* `worker.ts` was the shape of the bug — a default and a coercion restated at every reader, each free
|
|
26
|
+
* to disagree with the next.
|
|
27
|
+
*
|
|
28
|
+
* ## Two names, deliberately
|
|
29
|
+
*
|
|
30
|
+
* {@link EmailHostEnv} is the schema (and the type the host runs on). {@link emailHostEnv} is the
|
|
31
|
+
* *declaration*: the schema plus what fills each field, which is the object the CLI imports. The
|
|
32
|
+
* second is the one an operator's report is built from — a missing field is only actionable when
|
|
33
|
+
* something names the binding, var or command that writes it.
|
|
34
|
+
*
|
|
35
|
+
* Node-safe on purpose. No `cloudflare:` import and no filesystem, so `pithy doctor` can import this
|
|
36
|
+
* without executing the Worker — the same constraint `@pithy-sh/core`'s host modules carry.
|
|
37
|
+
*/
|
|
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
|
+
* No `--worker` either, and only here: this is the sentence the deployed host writes into its own log, and
|
|
45
|
+
* a host does not know which app Worker's `apps/` directory provisioned it. `pithy doctor` reports the same
|
|
46
|
+
* finding for a Worker it knows, and names it there (`provision/settingsCheck.ts`, #711).
|
|
47
|
+
*/
|
|
48
|
+
export declare const EMAIL_PROVISION: import("@pithy-sh/core/src/cli/command").Command;
|
|
8
49
|
/** The email host's env, as the host runs on it. Every field is coerced here, never at its reader. */
|
|
9
50
|
export declare const EmailHostEnv: z.ZodObject<{
|
|
10
51
|
DB: z.ZodType<D1Database, unknown, z.core.$ZodTypeInternals<D1Database, unknown>>;
|
|
@@ -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;
|
|
1
|
+
{"version":3,"file":"hostEnv.d.ts","sourceRoot":"","sources":["../../src/workflows/hostEnv.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,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;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,kDAA2D,CAAC;AA2CxF,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"}
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
import { EMAIL_LINK_SIGNING_KEY, EMAIL_LINK_SIGNING_KEY_BINDING } from "../crypto/signingKey.js";
|
|
4
4
|
import { EmailTheme, defaultTheme } from "../templates/theme.js";
|
|
5
5
|
import { z } from "zod";
|
|
6
|
+
import { pithyCommandOf, remedy } from "@pithy-sh/core/src/cli/command";
|
|
6
7
|
import { defineHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
7
8
|
//#region src/workflows/hostEnv.ts
|
|
8
9
|
/**
|
|
@@ -40,13 +41,19 @@ import { defineHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
|
40
41
|
*
|
|
41
42
|
* No `--env`: it spans every declared environment in one run and declares no such flag, and a flag a
|
|
42
43
|
* command does not declare is refused (#594) — so a remedy naming one is a remedy that cannot be followed.
|
|
44
|
+
*
|
|
45
|
+
* No `--worker` either, and only here: this is the sentence the deployed host writes into its own log, and
|
|
46
|
+
* a host does not know which app Worker's `apps/` directory provisioned it. `pithy doctor` reports the same
|
|
47
|
+
* finding for a Worker it knows, and names it there (`provision/settingsCheck.ts`, #711).
|
|
43
48
|
*/
|
|
44
|
-
const
|
|
49
|
+
const EMAIL_PROVISION = pithyCommandOf("email provision", {}, { runtime: true });
|
|
50
|
+
const PROVISION = EMAIL_PROVISION;
|
|
45
51
|
/**
|
|
46
|
-
*
|
|
47
|
-
* provisions every declared environment in one run and declares no such flag
|
|
52
|
+
* What writes both host secrets below, said as a person's decision. No `--env`, for the same reason: `pithy secrets
|
|
53
|
+
* provision` provisions every declared environment in one run, production included, and declares no such flag — so
|
|
54
|
+
* it is never a `Run` line for one host's secret (#711).
|
|
48
55
|
*/
|
|
49
|
-
const SECRETS_PROVISION = "
|
|
56
|
+
const SECRETS_PROVISION = remedy("secrets provision", {}, { runtime: true }).say((command) => command);
|
|
50
57
|
/** A binding `pithy email provision` wires into the resolved `wrangler.jsonc`. */
|
|
51
58
|
const binding = (name) => ({
|
|
52
59
|
kind: "binding",
|
|
@@ -136,12 +143,12 @@ const emailHostEnv = defineHostEnv({
|
|
|
136
143
|
SECRETS_ENCRYPTION_KEYS: {
|
|
137
144
|
kind: "secret",
|
|
138
145
|
name: "SECRETS_ENCRYPTION_KEYS",
|
|
139
|
-
|
|
146
|
+
decision: SECRETS_PROVISION
|
|
140
147
|
},
|
|
141
148
|
[EMAIL_LINK_SIGNING_KEY_BINDING]: {
|
|
142
149
|
kind: "secret",
|
|
143
150
|
name: EMAIL_LINK_SIGNING_KEY,
|
|
144
|
-
|
|
151
|
+
decision: SECRETS_PROVISION
|
|
145
152
|
},
|
|
146
153
|
EMAIL: binding("EMAIL"),
|
|
147
154
|
EMAIL_SENDER: binding("EMAIL_SENDER"),
|
|
@@ -163,4 +170,4 @@ const emailHostEnv = defineHostEnv({
|
|
|
163
170
|
}
|
|
164
171
|
});
|
|
165
172
|
//#endregion
|
|
166
|
-
export { EmailHostEnv, emailHostEnv };
|
|
173
|
+
export { EMAIL_PROVISION, EmailHostEnv, emailHostEnv };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pithy-sh/email",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -42,14 +42,14 @@
|
|
|
42
42
|
"postal-mime": "^3.0.0"
|
|
43
43
|
},
|
|
44
44
|
"peerDependencies": {
|
|
45
|
-
"@pithy-sh/core": "^0.
|
|
46
|
-
"@pithy-sh/secrets": "^0.
|
|
45
|
+
"@pithy-sh/core": "^0.10.0",
|
|
46
|
+
"@pithy-sh/secrets": "^0.4.0",
|
|
47
47
|
"hono": "^4.13.2",
|
|
48
48
|
"kysely": "^0.29.0",
|
|
49
49
|
"zod": "^4.4.0"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
|
52
|
-
"@cloudflare/vitest-plugin": "^1.
|
|
52
|
+
"@cloudflare/vitest-plugin": "^1.4.2",
|
|
53
53
|
"@pithy-sh/cloudflare": "workspace:*",
|
|
54
54
|
"@pithy-sh/core": "workspace:*",
|
|
55
55
|
"@pithy-sh/secrets": "workspace:*",
|
|
@@ -62,7 +62,7 @@
|
|
|
62
62
|
"tsdown": "^0.23.0",
|
|
63
63
|
"typescript": "^7.0.2",
|
|
64
64
|
"vitest": "^4.1.0",
|
|
65
|
-
"wrangler": "^4.
|
|
65
|
+
"wrangler": "^4.151.0",
|
|
66
66
|
"zod": "^4.4.0"
|
|
67
67
|
}
|
|
68
68
|
}
|
package/src/capability.ts
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
import type { D1Database } from "@cloudflare/workers-types";
|
|
5
5
|
import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
|
|
6
|
+
import { pithyCommandOf } from "@pithy-sh/core/src/cli/command";
|
|
6
7
|
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
7
8
|
import type { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
|
|
8
9
|
import { z } from "zod";
|
|
@@ -345,7 +346,7 @@ export function email(config: EmailConfigInput): EmailCapability {
|
|
|
345
346
|
if (!binding) {
|
|
346
347
|
throw new InternalError({
|
|
347
348
|
message: "The suppression list is not available.",
|
|
348
|
-
action:
|
|
349
|
+
action: `Run \`${pithyCommandOf("add", { args: ["email"], flags: { "--with-prerequisites": true } }, { runtime: true })}\` to provision it, or bind the EMAIL_SUPPRESSIONS D1 database.`,
|
|
349
350
|
detail: "email.suppressions() was called with an env carrying no `EMAIL_SUPPRESSIONS` D1 binding.",
|
|
350
351
|
});
|
|
351
352
|
}
|
package/src/http/callbacks.ts
CHANGED
|
@@ -2,10 +2,10 @@
|
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
4
|
import type { D1Database } from "@cloudflare/workers-types";
|
|
5
|
-
import { zValidator } from "@hono/zod-validator";
|
|
6
5
|
import { normalizeAddress } from "@pithy-sh/core/src/address/address";
|
|
7
6
|
import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
|
|
8
|
-
import {
|
|
7
|
+
import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
|
|
8
|
+
import { validate } from "@pithy-sh/core/src/http/validation";
|
|
9
9
|
import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
|
|
10
10
|
import type { Hono } from "hono";
|
|
11
11
|
import { resolveSigningKeys } from "../crypto/signingKey";
|
|
@@ -202,21 +202,50 @@ export function registerCallbacks(app: Hono<PithyHonoEnv>): void {
|
|
|
202
202
|
};
|
|
203
203
|
};
|
|
204
204
|
|
|
205
|
-
app.get(
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
205
|
+
app.get(
|
|
206
|
+
`${CALLBACK_BASE}/c/:token`,
|
|
207
|
+
describeRoute({
|
|
208
|
+
summary: "Record a click on a tracked link, then send the reader on to it.",
|
|
209
|
+
description:
|
|
210
|
+
"Public: the HMAC signature on the token is the only gate. A forged, altered, or expired token answers `email/invalid_token` (400) before anything is recorded, and the destination is the http(s) URL signed into the token, never one from the request.",
|
|
211
|
+
verification: "public",
|
|
212
|
+
responses: { 302: { description: "A redirect to the link's destination, carried in `Location`." } },
|
|
213
|
+
}),
|
|
214
|
+
validate("param", CallbackTokenParam),
|
|
215
|
+
async (c) => {
|
|
216
|
+
const { db, keys } = await setup(c.env as unknown as CallbackEnv);
|
|
217
|
+
return handleClick(db, keys, { token: c.req.valid("param").token, url: c.req.url }, new Date());
|
|
218
|
+
},
|
|
219
|
+
);
|
|
209
220
|
|
|
210
|
-
app.get(
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
221
|
+
app.get(
|
|
222
|
+
`${CALLBACK_BASE}/o/:token`,
|
|
223
|
+
describeRoute({
|
|
224
|
+
summary: "Record that an email was opened.",
|
|
225
|
+
description:
|
|
226
|
+
"Public: the HMAC signature on the token is the only gate. The token may carry the `.png` suffix mail clients expect on an image URL.",
|
|
227
|
+
verification: "public",
|
|
228
|
+
responses: { 200: { description: "A 1×1 transparent PNG, never cached.", contentType: "image/png" } },
|
|
229
|
+
}),
|
|
230
|
+
validate("param", CallbackTokenParam),
|
|
231
|
+
async (c) => {
|
|
232
|
+
const { db, keys } = await setup(c.env as unknown as CallbackEnv);
|
|
233
|
+
return handleOpen(db, keys, { token: c.req.valid("param").token, url: c.req.url }, new Date());
|
|
234
|
+
},
|
|
235
|
+
);
|
|
214
236
|
|
|
215
237
|
app.on(
|
|
216
238
|
["GET", "POST"],
|
|
217
239
|
`${CALLBACK_BASE}/u/:token`,
|
|
218
|
-
|
|
219
|
-
|
|
240
|
+
describeRoute({
|
|
241
|
+
summary: "Unsubscribe the recipient from everything but the mail they ask for.",
|
|
242
|
+
description:
|
|
243
|
+
"Public: the HMAC signature on the token is the only gate. Answers GET for the link in the message and POST for one-click unsubscribe. The address joins the suppression list shared by every environment.",
|
|
244
|
+
verification: "public",
|
|
245
|
+
responses: { 200: { description: "A short HTML page confirming the opt-out.", contentType: "text/html" } },
|
|
246
|
+
}),
|
|
247
|
+
validate("param", CallbackTokenParam),
|
|
248
|
+
validate("query", UnsubscribeQuery),
|
|
220
249
|
async (c) => {
|
|
221
250
|
const env = c.env as unknown as CallbackEnv;
|
|
222
251
|
const { db, suppressionDb, keys } = await setup(env);
|
package/src/http/routes.ts
CHANGED
|
@@ -2,15 +2,17 @@
|
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
4
|
import type { D1Database } from "@cloudflare/workers-types";
|
|
5
|
-
import { zValidator } from "@hono/zod-validator";
|
|
6
5
|
import { normalizeAddress } from "@pithy-sh/core/src/address/address";
|
|
7
6
|
import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
|
|
8
7
|
import type { ControlPlaneContext } from "@pithy-sh/core/src/controlPlane/context";
|
|
9
8
|
import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
|
|
10
9
|
import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
|
|
10
|
+
import type { AmbientEnv } from "@pithy-sh/core/src/env/ambient";
|
|
11
11
|
import { ConflictError, InternalError, NotFoundError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
|
|
12
|
-
import {
|
|
12
|
+
import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
|
|
13
|
+
import { validate } from "@pithy-sh/core/src/http/validation";
|
|
13
14
|
import type { VerificationStrategy } from "@pithy-sh/core/src/http/verification";
|
|
15
|
+
import { migrateStep } from "@pithy-sh/core/src/migrations/migrateStep";
|
|
14
16
|
import type { Context, Hono } from "hono";
|
|
15
17
|
import { EmailAuditActions } from "../audit/actions";
|
|
16
18
|
import {
|
|
@@ -31,7 +33,7 @@ import {
|
|
|
31
33
|
EMAIL_SUPPRESSIONS_READ_SCOPE,
|
|
32
34
|
EMAIL_SUPPRESSIONS_WRITE_SCOPE,
|
|
33
35
|
} from "./guards";
|
|
34
|
-
import
|
|
36
|
+
import {
|
|
35
37
|
EmailJobResponse,
|
|
36
38
|
EmailJobRetryResponse,
|
|
37
39
|
EmailJobsResponse,
|
|
@@ -89,7 +91,7 @@ export interface EmailRouteDeclaration {
|
|
|
89
91
|
* Every management route, and how it is gated.
|
|
90
92
|
*
|
|
91
93
|
* Exported so a test can assert against the declaration rather than against a middleware count. A count
|
|
92
|
-
* proves that *something* runs before the handler — a bare `
|
|
94
|
+
* proves that *something* runs before the handler — a bare `validate` satisfies it — and cannot prove
|
|
93
95
|
* *what*. `routeContract.test.ts` checks this list against the paths Hono actually registered, in both
|
|
94
96
|
* directions, so a route added without an entry and an entry without a route both fail.
|
|
95
97
|
*/
|
|
@@ -145,7 +147,7 @@ function d1(c: Context<PithyHonoEnv>, binding: "DB" | "EMAIL_SUPPRESSIONS"): D1D
|
|
|
145
147
|
if (!found) {
|
|
146
148
|
throw new InternalError({
|
|
147
149
|
message: "Email is not fully configured on this Worker.",
|
|
148
|
-
action: `Bind a D1 database named ${binding} in wrangler.jsonc, then
|
|
150
|
+
action: `Bind a D1 database named ${binding} in wrangler.jsonc, then ${migrateStep(c.env as AmbientEnv)}.`,
|
|
149
151
|
detail: `the email management routes require a \`${binding}\` D1 binding; none was present on env`,
|
|
150
152
|
});
|
|
151
153
|
}
|
|
@@ -190,8 +192,14 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
|
|
|
190
192
|
|
|
191
193
|
app.get(
|
|
192
194
|
`${base}/jobs`,
|
|
195
|
+
describeRoute({
|
|
196
|
+
summary: "Page through the send log.",
|
|
197
|
+
verification: "control-plane",
|
|
198
|
+
scopes: [EMAIL_JOBS_READ_SCOPE],
|
|
199
|
+
responses: { 200: EmailJobsResponse },
|
|
200
|
+
}),
|
|
193
201
|
requireControlPlane(EMAIL_JOBS_READ_SCOPE),
|
|
194
|
-
|
|
202
|
+
validate("query", JobsQuery),
|
|
195
203
|
async (c) => {
|
|
196
204
|
const query = c.req.valid("query");
|
|
197
205
|
const who = caller(c);
|
|
@@ -221,8 +229,14 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
|
|
|
221
229
|
|
|
222
230
|
app.get(
|
|
223
231
|
`${base}/jobs/:id`,
|
|
232
|
+
describeRoute({
|
|
233
|
+
summary: "Read one email job in full, recipient included.",
|
|
234
|
+
verification: "control-plane",
|
|
235
|
+
scopes: [EMAIL_JOBS_READ_SCOPE],
|
|
236
|
+
responses: { 200: EmailJobResponse },
|
|
237
|
+
}),
|
|
224
238
|
requireControlPlane(EMAIL_JOBS_READ_SCOPE),
|
|
225
|
-
|
|
239
|
+
validate("param", JobIdParam),
|
|
226
240
|
async (c) => {
|
|
227
241
|
const { id } = c.req.valid("param");
|
|
228
242
|
const who = caller(c);
|
|
@@ -254,8 +268,14 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
|
|
|
254
268
|
|
|
255
269
|
app.post(
|
|
256
270
|
`${base}/jobs/:id/retry`,
|
|
271
|
+
describeRoute({
|
|
272
|
+
summary: "Queue a job to send again.",
|
|
273
|
+
verification: "control-plane",
|
|
274
|
+
scopes: [EMAIL_JOBS_RETRY_SCOPE],
|
|
275
|
+
responses: { 200: EmailJobRetryResponse },
|
|
276
|
+
}),
|
|
257
277
|
requireControlPlane(EMAIL_JOBS_RETRY_SCOPE),
|
|
258
|
-
|
|
278
|
+
validate("param", JobIdParam),
|
|
259
279
|
async (c) => {
|
|
260
280
|
const { id } = c.req.valid("param");
|
|
261
281
|
const who = caller(c);
|
|
@@ -297,8 +317,14 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
|
|
|
297
317
|
|
|
298
318
|
app.get(
|
|
299
319
|
`${base}/suppressions`,
|
|
320
|
+
describeRoute({
|
|
321
|
+
summary: "Page through the suppression list, or look one address up.",
|
|
322
|
+
verification: "control-plane",
|
|
323
|
+
scopes: [EMAIL_SUPPRESSIONS_READ_SCOPE],
|
|
324
|
+
responses: { 200: EmailSuppressionsResponse },
|
|
325
|
+
}),
|
|
300
326
|
requireControlPlane(EMAIL_SUPPRESSIONS_READ_SCOPE),
|
|
301
|
-
|
|
327
|
+
validate("query", SuppressionsQuery),
|
|
302
328
|
async (c) => {
|
|
303
329
|
const query = c.req.valid("query");
|
|
304
330
|
const who = caller(c);
|
|
@@ -333,8 +359,14 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
|
|
|
333
359
|
|
|
334
360
|
app.post(
|
|
335
361
|
`${base}/suppressions`,
|
|
362
|
+
describeRoute({
|
|
363
|
+
summary: "Block an address by hand.",
|
|
364
|
+
verification: "control-plane",
|
|
365
|
+
scopes: [EMAIL_SUPPRESSIONS_WRITE_SCOPE],
|
|
366
|
+
responses: { 200: EmailSuppressResponse },
|
|
367
|
+
}),
|
|
336
368
|
requireControlPlane(EMAIL_SUPPRESSIONS_WRITE_SCOPE),
|
|
337
|
-
|
|
369
|
+
validate("json", SuppressRequest),
|
|
338
370
|
async (c) => {
|
|
339
371
|
const input = c.req.valid("json");
|
|
340
372
|
const who = caller(c);
|
|
@@ -425,8 +457,14 @@ export function registerEmailAdminRoutes(options: EmailAdminRoutesOptions): (app
|
|
|
425
457
|
|
|
426
458
|
app.post(
|
|
427
459
|
`${base}/suppressions/remove`,
|
|
460
|
+
describeRoute({
|
|
461
|
+
summary: "Lift the block on an address.",
|
|
462
|
+
verification: "control-plane",
|
|
463
|
+
scopes: [EMAIL_SUPPRESSIONS_DELETE_SCOPE],
|
|
464
|
+
responses: { 200: EmailUnsuppressResponse },
|
|
465
|
+
}),
|
|
428
466
|
requireControlPlane(EMAIL_SUPPRESSIONS_DELETE_SCOPE),
|
|
429
|
-
|
|
467
|
+
validate("json", UnsuppressRequest),
|
|
430
468
|
async (c) => {
|
|
431
469
|
const input = c.req.valid("json");
|
|
432
470
|
const who = caller(c);
|
package/src/http/schemas.ts
CHANGED
|
@@ -8,7 +8,7 @@ import { EmailJobStatus, SuppressionReason } from "../data/enums";
|
|
|
8
8
|
/**
|
|
9
9
|
* The request schemas for every email route — the three public callbacks and the six control-plane
|
|
10
10
|
* admin routes. Validation happens at the HTTP boundary (CLAUDE.md §Zod), declared on the route line
|
|
11
|
-
* with `
|
|
11
|
+
* with `validate(target, Schema)` — so reading `callbacks.ts` or `routes.ts` tells
|
|
12
12
|
* you what each route accepts without opening a handler.
|
|
13
13
|
*
|
|
14
14
|
* The callback schemas bound a value that already reaches the handler as free-form text. Neither tries
|
|
@@ -124,8 +124,11 @@ export interface EmailProvisioner {
|
|
|
124
124
|
* Throws a clear, actionable error so provisioning fails fast and clean rather than mid-deploy.
|
|
125
125
|
*/
|
|
126
126
|
preflight(): Promise<void>;
|
|
127
|
-
/**
|
|
128
|
-
|
|
127
|
+
/**
|
|
128
|
+
* Create (or reuse) the project's suppression D1; returns its id, and whether this call created it. Idempotent.
|
|
129
|
+
* Runs once, before any env.
|
|
130
|
+
*/
|
|
131
|
+
ensureSuppressionDatabase(): Promise<{ databaseId: string; created: boolean }>;
|
|
129
132
|
/** Run the `email_0001_suppressions` migration against the suppression D1. Idempotent (applied ones skip). */
|
|
130
133
|
migrateSuppression(databaseId: string): Promise<void>;
|
|
131
134
|
/** Deploy the prebuilt email worker for this environment, wired to the suppression DB and the env's own resources. */
|
|
@@ -142,6 +145,8 @@ export interface EmailProvisioner {
|
|
|
142
145
|
/** What provisioning produced. */
|
|
143
146
|
export interface EmailProvisionResult {
|
|
144
147
|
suppressionDatabaseId: string;
|
|
148
|
+
/** Whether this run created the suppression database, or found one an earlier run made. */
|
|
149
|
+
suppressionDatabaseCreated: boolean;
|
|
145
150
|
environments: ManagedEnvironment[];
|
|
146
151
|
/** Whether the inbound routing rule was created, already present, or skipped (not configured). */
|
|
147
152
|
routing: { created: boolean; skipped: boolean };
|
|
@@ -166,7 +171,7 @@ export async function provisionEmail(
|
|
|
166
171
|
environments: DeclaredEnvironments | readonly string[],
|
|
167
172
|
): Promise<EmailProvisionResult> {
|
|
168
173
|
await provisioner.preflight();
|
|
169
|
-
const { databaseId } = await provisioner.ensureSuppressionDatabase();
|
|
174
|
+
const { databaseId, created } = await provisioner.ensureSuppressionDatabase();
|
|
170
175
|
await provisioner.migrateSuppression(databaseId);
|
|
171
176
|
const deployed = managedEnvironments(environments);
|
|
172
177
|
for (const env of deployed) {
|
|
@@ -177,7 +182,7 @@ export async function provisionEmail(
|
|
|
177
182
|
// was never deployed, which is the window this ordering exists to close.
|
|
178
183
|
const routing =
|
|
179
184
|
deployed.length > 0 ? await provisioner.ensureRoutingRule() : { created: false, skipped: true as const };
|
|
180
|
-
return { suppressionDatabaseId: databaseId, environments: deployed, routing };
|
|
185
|
+
return { suppressionDatabaseId: databaseId, suppressionDatabaseCreated: created, environments: deployed, routing };
|
|
181
186
|
}
|
|
182
187
|
|
|
183
188
|
/** The teardown seam — the inverse of {@link EmailProvisioner}. Every step idempotent (a missing resource is a no-op). */
|
|
@@ -9,12 +9,13 @@ import type {
|
|
|
9
9
|
SettingsFinding,
|
|
10
10
|
} from "@pithy-sh/core/src/capability/settings";
|
|
11
11
|
import { hostEnvFindings } from "@pithy-sh/core/src/capability/settings";
|
|
12
|
+
import { type Command, personDecision, pithyCommand, remedy, workerDirOf } from "@pithy-sh/core/src/cli/command";
|
|
12
13
|
import { LOCAL_ORIGIN } from "@pithy-sh/core/src/naming/domains";
|
|
13
14
|
import { environmentScope, type SecretNameScope } from "@pithy-sh/core/src/naming/provisionScope";
|
|
14
|
-
import { checkHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
15
|
+
import { checkHostEnv, type HostEnvReport } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
15
16
|
import { EMAIL_LINK_SIGNING_KEY, EMAIL_LINK_SIGNING_KEY_BINDING, emailSigningRegistry } from "../crypto/signingKey";
|
|
16
17
|
import type { EmailTheme } from "../templates/theme";
|
|
17
|
-
import { emailHostEnv } from "../workflows/hostEnv";
|
|
18
|
+
import { EMAIL_PROVISION, emailHostEnv } from "../workflows/hostEnv";
|
|
18
19
|
import { suppressionDatabaseName } from "./provisionEmail";
|
|
19
20
|
|
|
20
21
|
/**
|
|
@@ -103,7 +104,7 @@ function originOf(url: string): string | null {
|
|
|
103
104
|
* config object per Worker, so a `BASE_URL` that is not a URL is one edit however many environments a
|
|
104
105
|
* project declares. Three lines about one key is how a report stops being read.
|
|
105
106
|
*/
|
|
106
|
-
function localHostEnv(config: EmailSettingsInput): SettingsFinding[] {
|
|
107
|
+
function localHostEnv(config: EmailSettingsInput, workerDirectory: string): SettingsFinding[] {
|
|
107
108
|
const candidate = {
|
|
108
109
|
...stubBindings(),
|
|
109
110
|
BASE_URL: config.baseUrl,
|
|
@@ -112,7 +113,33 @@ function localHostEnv(config: EmailSettingsInput): SettingsFinding[] {
|
|
|
112
113
|
// failure this catches.
|
|
113
114
|
...(config.theme ? { EMAIL_THEME: JSON.stringify(config.theme) } : {}),
|
|
114
115
|
};
|
|
115
|
-
return hostEnvFindings(checkHostEnv(emailHostEnv, candidate), null);
|
|
116
|
+
return hostEnvFindings(forWorker(checkHostEnv(emailHostEnv, candidate), workerDirectory), null);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* **`pithy email provision` for the Worker this check ran for (#711).** It acts on one Worker, and in a project
|
|
121
|
+
* with several a bare one is refused `input/required`. Takes the Worker's `apps/` directory, which is what
|
|
122
|
+
* `--worker` takes and what that refusal lists. Not its `wrangler.jsonc` name: a scaffold deploys `apps/api` as
|
|
123
|
+
* `acme-api`.
|
|
124
|
+
*/
|
|
125
|
+
function provisionCommand(workerDirectory: string): Command {
|
|
126
|
+
return pithyCommand("email provision", { flags: { "--worker": workerDirOf({ dir: workerDirectory }) } });
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* The host's own report, with its provisioning command named for this Worker by its `apps/` directory. The host
|
|
131
|
+
* writes the bare command into its log because it cannot know the Worker; a check that does know names it, in
|
|
132
|
+
* the action and the `fix` alike.
|
|
133
|
+
*/
|
|
134
|
+
function forWorker(report: HostEnvReport<unknown>, workerDirectory: string): HostEnvReport<unknown> {
|
|
135
|
+
return {
|
|
136
|
+
...report,
|
|
137
|
+
problems: report.problems.map((problem) =>
|
|
138
|
+
problem.provider.command === EMAIL_PROVISION
|
|
139
|
+
? { ...problem, provider: { ...problem.provider, command: provisionCommand(workerDirectory) } }
|
|
140
|
+
: problem,
|
|
141
|
+
),
|
|
142
|
+
};
|
|
116
143
|
}
|
|
117
144
|
|
|
118
145
|
/**
|
|
@@ -215,7 +242,8 @@ async function accountFindings(
|
|
|
215
242
|
problem: `No D1 database named ${suppressions} exists on this account.`,
|
|
216
243
|
// One database for the whole project, and one run creates it. `pithy email provision` spans every
|
|
217
244
|
// declared environment and takes no `--env`, so naming one here was a flag the CLI refuses (#594).
|
|
218
|
-
action:
|
|
245
|
+
action: `Run \`${provisionCommand(context.workerDirectory)}\`. Nothing is suppressed until it exists.`,
|
|
246
|
+
fix: provisionCommand(context.workerDirectory),
|
|
219
247
|
});
|
|
220
248
|
}
|
|
221
249
|
|
|
@@ -245,6 +273,9 @@ async function accountFindings(
|
|
|
245
273
|
* **What this sees:** a row under this registry name. A secret some other declaration moved off D1 has its
|
|
246
274
|
* own check to write, or none; nothing here walks the vault for strays, because the vault cannot be listed.
|
|
247
275
|
*/
|
|
276
|
+
/** What creates a missing link-signing entry: a provision of every environment, production included (#711). */
|
|
277
|
+
const PROVISION_SECRETS = remedy("secrets provision");
|
|
278
|
+
|
|
248
279
|
async function signingKeyFindings(context: SettingsAccountContext, environment: string): Promise<SettingsFinding[]> {
|
|
249
280
|
const findings: SettingsFinding[] = [];
|
|
250
281
|
const entry = environmentScope(context.project, environment).secretEntry(
|
|
@@ -256,8 +287,10 @@ async function signingKeyFindings(context: SettingsAccountContext, environment:
|
|
|
256
287
|
setting: EMAIL_LINK_SIGNING_KEY,
|
|
257
288
|
environment,
|
|
258
289
|
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
|
-
|
|
290
|
+
// No `--env`: the command spans every declared environment, production included, and takes no such flag — so
|
|
291
|
+
// for one environment's entry it is a person's decision, never a `fix` (#711).
|
|
292
|
+
action: PROVISION_SECRETS.say((command) => `Run \`${command}\`.`),
|
|
293
|
+
...(PROVISION_SECRETS.fix === undefined ? {} : { fix: PROVISION_SECRETS.fix }),
|
|
261
294
|
});
|
|
262
295
|
}
|
|
263
296
|
if (await context.account.vaultSecret({ name: EMAIL_LINK_SIGNING_KEY, environment })) {
|
|
@@ -265,7 +298,9 @@ async function signingKeyFindings(context: SettingsAccountContext, environment:
|
|
|
265
298
|
setting: EMAIL_LINK_SIGNING_KEY,
|
|
266
299
|
environment,
|
|
267
300
|
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,
|
|
301
|
+
action: `Once the Secrets Store entry is bound and deployed, the D1 copy can go: ${personDecision("secrets rm", { args: [EMAIL_LINK_SIGNING_KEY], flags: { "--env": environment, "--backend": "d1" } })} See docs/commands/secrets.md#moving-a-secret-off-d1.`,
|
|
302
|
+
// No `fix`: the removal is safe only once the entry is bound and deployed, which this check does not
|
|
303
|
+
// establish, so an agent running it as written could delete the only copy that still answers (#697).
|
|
269
304
|
});
|
|
270
305
|
}
|
|
271
306
|
return findings;
|
|
@@ -274,7 +309,11 @@ async function signingKeyFindings(context: SettingsAccountContext, environment:
|
|
|
274
309
|
/** Email's settings check, built from one composition's resolved config. Declared on the capability. */
|
|
275
310
|
export function emailSettings(config: EmailSettingsInput): CapabilitySettings {
|
|
276
311
|
return {
|
|
277
|
-
local: (context) => [
|
|
312
|
+
local: (context) => [
|
|
313
|
+
...localHostEnv(config, context.workerDirectory),
|
|
314
|
+
...localForAddress(config),
|
|
315
|
+
...localBaseUrlOrigin(config, context),
|
|
316
|
+
],
|
|
278
317
|
account: (context) => accountFindings(config, context),
|
|
279
318
|
};
|
|
280
319
|
}
|
package/src/version.generated.ts
CHANGED
package/src/workflows/hostEnv.ts
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
|
|
4
4
|
import type { D1Database } from "@cloudflare/workers-types";
|
|
5
|
+
import { pithyCommandOf, remedy } from "@pithy-sh/core/src/cli/command";
|
|
5
6
|
import { defineHostEnv, type HostEnvProvider } from "@pithy-sh/core/src/workflow/hostEnv";
|
|
6
7
|
import type { SecretBinding } from "@pithy-sh/secrets/src/env/bindings";
|
|
7
8
|
import { z } from "zod";
|
|
@@ -46,14 +47,20 @@ import type { SendWorkflowInstances } from "./instances";
|
|
|
46
47
|
*
|
|
47
48
|
* No `--env`: it spans every declared environment in one run and declares no such flag, and a flag a
|
|
48
49
|
* command does not declare is refused (#594) — so a remedy naming one is a remedy that cannot be followed.
|
|
50
|
+
*
|
|
51
|
+
* No `--worker` either, and only here: this is the sentence the deployed host writes into its own log, and
|
|
52
|
+
* a host does not know which app Worker's `apps/` directory provisioned it. `pithy doctor` reports the same
|
|
53
|
+
* finding for a Worker it knows, and names it there (`provision/settingsCheck.ts`, #711).
|
|
49
54
|
*/
|
|
50
|
-
const
|
|
55
|
+
export const EMAIL_PROVISION = pithyCommandOf("email provision", {}, { runtime: true });
|
|
56
|
+
const PROVISION = EMAIL_PROVISION;
|
|
51
57
|
|
|
52
58
|
/**
|
|
53
|
-
*
|
|
54
|
-
* provisions every declared environment in one run and declares no such flag
|
|
59
|
+
* What writes both host secrets below, said as a person's decision. No `--env`, for the same reason: `pithy secrets
|
|
60
|
+
* provision` provisions every declared environment in one run, production included, and declares no such flag — so
|
|
61
|
+
* it is never a `Run` line for one host's secret (#711).
|
|
55
62
|
*/
|
|
56
|
-
const SECRETS_PROVISION = "
|
|
63
|
+
const SECRETS_PROVISION = remedy("secrets provision", {}, { runtime: true }).say((command) => command);
|
|
57
64
|
|
|
58
65
|
/** A binding `pithy email provision` wires into the resolved `wrangler.jsonc`. */
|
|
59
66
|
const binding = (name: string): HostEnvProvider => ({ kind: "binding", name, command: PROVISION });
|
|
@@ -210,12 +217,12 @@ export const emailHostEnv = defineHostEnv({
|
|
|
210
217
|
SECRETS_ENCRYPTION_KEYS: {
|
|
211
218
|
kind: "secret",
|
|
212
219
|
name: "SECRETS_ENCRYPTION_KEYS",
|
|
213
|
-
|
|
220
|
+
decision: SECRETS_PROVISION,
|
|
214
221
|
},
|
|
215
222
|
[EMAIL_LINK_SIGNING_KEY_BINDING]: {
|
|
216
223
|
kind: "secret",
|
|
217
224
|
name: EMAIL_LINK_SIGNING_KEY,
|
|
218
|
-
|
|
225
|
+
decision: SECRETS_PROVISION,
|
|
219
226
|
},
|
|
220
227
|
EMAIL: binding("EMAIL"),
|
|
221
228
|
EMAIL_SENDER: binding("EMAIL_SENDER"),
|