@mccaskie-labs/workbench-config 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @mccaskie-labs/workbench-config
 
+## 0.1.9
+
+### Patch Changes
+
+- Ship the email and email-sending manifests (step 4.9): `capabilities.email` (POST /v1/email/send and workbench-email) and `capabilities["email-sending"]` (cf_email_sending_onboard and cf_email_sending_status), both built.
+
 ## 0.1.8
 
 ### Patch Changes

package/capabilities/email-sending.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "./schema.json",
+  "format": 1,
+  "component": "email-sending",
+  "title": "Sending domains and sender addresses",
+  "summary": "Control onboards a domain in the project's namespace to Cloudflare Email Sending in the projects account, with its bounce, SPF, DKIM and DMARC records checked over DNS-over-HTTPS, and allows sender addresses on it. The Gateway sends from those addresses only.",
+  "status": "built",
+  "surfaces": {
+    "tools": ["cf_email_sending_onboard", "cf_email_sending_status", "gw_sender_add", "gw_sender_list"]
+  },
+  "limits": [
+    { "id": "email-sending.domains-per-zone", "value": 30, "unit": "domains", "per": "zone, Email Sending and Email Routing together", "enforced_by": "control" }
+  ],
+  "actions": [
+    { "tool": "cf_email_sending_onboard", "gate": "free", "ships": "4" },
+    { "tool": "cf_email_sending_status", "gate": "free", "ships": "4" },
+    { "tool": "gw_sender_add", "gate": "free", "ships": "4" },
+    { "tool": "gw_sender_list", "gate": "free", "ships": "4" }
+  ],
+  "errors": [
+    { "code": "out_of_scope", "http": 403, "retryable": false, "meaning": "A domain outside the project's namespace, or a sender on a domain the project hasn't onboarded" },
+    { "code": "name_taken", "http": 409, "retryable": false, "meaning": "The domain or address is already onboarded or allowed outside this project; Control never adopts" },
+    { "code": "record_conflict", "http": 409, "retryable": false, "meaning": "A DNS record in the way that Control won't change (another SPF, DMARC, MX or CNAME)" },
+    { "code": "missing_permission", "http": 403, "retryable": false, "meaning": "Control's Cloudflare token lacks Email Sending (edit)" }
+  ],
+  "rules": [
+    { "id": "email-sending.namespace-only", "kind": "must", "text": "Onboard a domain in the project's own namespace, for example mail.<id>.mccaskielabs.app. Project-owned zones such as wbprobe.com follow cf_zone_attach (step 6.1).", "enforced_by": "control", "probe": "email-sending.onboard" },
+    { "id": "email-sending.onboard-before-sender", "kind": "must", "text": "Onboard the domain before adding senders on it. gw_sender_add refuses a domain the project hasn't onboarded.", "enforced_by": "control", "probe": "email-sending.sender-add" },
+    { "id": "email-sending.never-adopt", "kind": "must_not", "text": "Expect Control to take over a domain onboarded by hand. It refuses with name_taken.", "enforced_by": "control", "probe": "email-sending.onboard" },
+    { "id": "email-sending.verified-over-doh", "kind": "must", "text": "Treat a domain as ready only when cf_email_sending_status says ready: every expected record is in the zone and visible over DNS-over-HTTPS.", "enforced_by": "control", "probe": "email-sending.status" }
+  ],
+  "probes": [
+    { "id": "email-sending.onboard", "half": "drill", "expect": "pass", "cost_hint_usd": 0, "note": "cf_email_sending_onboard on mail.<id>.mccaskielabs.app; a second call changes nothing" },
+    { "id": "email-sending.status", "half": "drill", "expect": "pass", "cost_hint_usd": 0 },
+    { "id": "email-sending.sender-add", "half": "drill", "expect": "pass", "cost_hint_usd": 0, "note": "Then a runtime send from the new address (email.send.transactional)" },
+    { "id": "email-sending.out-of-scope", "half": "drill", "expect": "refused_as_expected", "refusal": "out_of_scope", "cost_hint_usd": 0, "note": "Another project's namespace" }
+  ]
+}

package/capabilities/email-sending.md

@@ -0,0 +1,9 @@
+# Email sending domains
+
+A project sends from addresses on a domain Control onboarded for it. Today that is a domain in the project's namespace in `mccaskielabs.app`, usually `mail.<id>.mccaskielabs.app`. Project-owned zones such as `wbprobe.com` follow `cf_zone_attach` in step 6.1.
+
+1. `cf_email_sending_onboard domain=mail.<id>.mccaskielabs.app` creates the Email Sending subdomain in the projects account, adds the records Cloudflare expects (the `cf-bounce` MX and SPF, and DKIM) and the domain's own DMARC record (`p=reject; adkim=s; aspf=r`), records them, and checks each over DNS-over-HTTPS. A record in the way stops it; it changes nothing it didn't make.
+2. `cf_email_sending_status` says `ready` once every record is visible. Records can take a few minutes.
+3. `gw_sender_add address=hello@mail.<id>.mccaskielabs.app` allows the address. The Gateway accepts it within a minute.
+
+The DNS records are ordinary `dns_record` rows for the project, so removing one is `cf_dns_delete` (two-step).

package/capabilities/email.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "./schema.json",
+  "format": 1,
+  "component": "email",
+  "title": "Transactional email through the Gateway",
+  "summary": "Apps send transactional mail with workbench-email, or POST /v1/email/send directly. The Gateway checks the sender and recipients, keeps idempotency keys for 24 hours, meters every send, and hands the message to Cloudflare Email Sending. Apps hold no email credential.",
+  "status": "built",
+  "surfaces": {
+    "gateway": ["POST /v1/email/send"],
+    "package": ["createMailer", "selectTransport", "Mailer.send", "captureSink", "WorkbenchEmailError"]
+  },
+  "config": [
+    { "name": "WORKBENCH_GATEWAY_KEY", "required": true, "secret": true, "environments": ["staging", "production"], "description": "Project key with the email scope, delivered as a Worker secret by gw_key_issue" },
+    { "name": "WORKBENCH_ENV", "required": true, "secret": false, "environments": ["development", "staging", "production"], "description": "Chooses the transport: capture in development, the Gateway elsewhere" },
+    { "name": "WORKBENCH_EMAIL_LIVE", "required": false, "secret": false, "default": "0", "environments": ["development"], "description": "1 sends real mail from development through the Gateway (a development key can only mail Robert)" }
+  ],
+  "limits": [
+    { "id": "email.recipients", "value": 50, "unit": "recipients", "per": "message (to, cc and bcc together)", "enforced_by": "gateway", "refusal": "invalid_request" },
+    { "id": "email.attachments", "value": 32, "unit": "attachments", "per": "message", "enforced_by": "gateway", "refusal": "invalid_request" },
+    { "id": "email.message-size", "value": 26214400, "unit": "bytes", "per": "message, attachments as base64", "enforced_by": "gateway", "refusal": "invalid_request" },
+    { "id": "email.subject-length", "value": 998, "unit": "characters", "per": "message", "enforced_by": "gateway", "refusal": "invalid_request" },
+    { "id": "email.idempotency-window", "value": 24, "unit": "hours", "per": "Idempotency-Key", "enforced_by": "database" },
+    { "id": "email.upstream-timeout", "value": 30, "unit": "seconds", "per": "request", "enforced_by": "gateway", "refusal": "upstream_timeout" }
+  ],
+  "errors": [
+    { "code": "sender_not_allowed", "http": 403, "retryable": false, "meaning": "from isn't one of the project's senders (gw_sender_add)" },
+    { "code": "recipient_not_allowed", "http": 403, "retryable": false, "meaning": "A development key sending to anyone but Workbench's allowlisted addresses" },
+    { "code": "invalid_request", "http": 400, "retryable": false, "meaning": "A malformed message, a limit passed, or an Idempotency-Key reused with a different message (422)" },
+    { "code": "not_available", "http": 501, "retryable": false, "meaning": "type bulk, until Amazon SES is built" },
+    { "code": "budget_exceeded", "http": 402, "retryable": false, "meaning": "Enforced monthly budget reached" },
+    { "code": "rate_limited", "http": 429, "retryable": true, "meaning": "Too many requests, Cloudflare's quota, or (409) a send with the same Idempotency-Key still in progress" },
+    { "code": "upstream_error", "http": 502, "retryable": true, "meaning": "Cloudflare Email Sending failed; nothing was sent" },
+    { "code": "upstream_timeout", "http": 504, "retryable": true, "meaning": "Cloudflare didn't answer within 30 seconds; the mail may or may not have gone" }
+  ],
+  "rules": [
+    { "id": "email.text-always", "kind": "must", "text": "Send a text part with every mail, even when there is HTML.", "enforced_by": "gateway", "probe": "email.send.transactional" },
+    { "id": "email.idempotency-key", "kind": "must", "text": "Give an idempotencyKey to any send a retry could repeat (invites, receipts, resets). A repeat within 24 hours returns the first result and sends nothing.", "enforced_by": "review", "probe": "email.send.idempotent-repeat" },
+    { "id": "email.attachments-as-bytes", "kind": "must", "text": "Pass attachments as bytes (Uint8Array), and give an inline image a contentId that the HTML references as cid:.", "enforced_by": "types", "probe": "email.send.inline-image" },
+    { "id": "email.allowed-sender", "kind": "must", "text": "Send only from an address added with gw_sender_add on a domain onboarded with cf_email_sending_onboard.", "enforced_by": "gateway", "probe": "email.send.sender-not-allowed" },
+    { "id": "email.no-capture-outside-dev", "kind": "must_not", "text": "Use the capture transport outside development. createMailer throws when WORKBENCH_ENV is staging or production.", "enforced_by": "types", "probe": "email.capture-refused-in-staging" },
+    { "id": "email.dev-key-allowlist", "kind": "must_not", "text": "Expect a development key to mail anyone but Robert. The Gateway refuses other recipients before the budget.", "enforced_by": "gateway", "probe": "email.send.dev-recipient-refused" },
+    { "id": "email.transactional-only", "kind": "must_not", "text": "Send bulk or marketing mail. type bulk is refused with not_available until Amazon SES is built.", "enforced_by": "gateway", "probe": "email.send.transactional" }
+  ],
+  "examples": [
+    {
+      "id": "email.example.send",
+      "title": "Send a transactional mail with an inline logo",
+      "lang": "ts",
+      "probe": "email.send.inline-image",
+      "code": "const env = workbenchEnv(process.env)\nconst mailer = createMailer({ env, transport: selectTransport(env), from: { address: 'hello@mail.example.com', name: 'Example' }, gateway: { key: process.env.WORKBENCH_GATEWAY_KEY! } })\nawait mailer.send({ to: user.email, subject: 'Welcome', text, html: '<img src=\"cid:logo\"> ...', template: 'welcome', idempotencyKey: `welcome:${user.id}`, attachments: [{ filename: 'logo.png', mimeType: 'image/png', bytes: logo, contentId: 'logo' }] })"
+    }
+  ],
+  "probes": [
+    { "id": "email.send.transactional", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0.00035, "note": "To Robert; check that it arrives" },
+    { "id": "email.send.inline-image", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.00035, "note": "Robert checks the image renders" },
+    { "id": "email.send.idempotent-repeat", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.00035, "note": "The repeat answers replayed: true and no second mail arrives" },
+    { "id": "email.send.dev-recipient-refused", "half": "runtime", "expect": "refused_as_expected", "refusal": "recipient_not_allowed", "cost_hint_usd": 0 },
+    { "id": "email.send.sender-not-allowed", "half": "runtime", "expect": "refused_as_expected", "refusal": "sender_not_allowed", "cost_hint_usd": 0 },
+    { "id": "email.capture-refused-in-staging", "half": "runtime", "expect": "pass", "cost_hint_usd": 0, "note": "createMailer with transport capture and WORKBENCH_ENV=staging throws invalid_config" }
+  ]
+}

package/capabilities/email.md

@@ -0,0 +1,23 @@
+# Email
+
+Apps send transactional mail with `createMailer` from `@mccaskie-labs/workbench-email`, or `POST /v1/email/send` directly. The Gateway holds the sending credential; the app holds only its Gateway key, which needs the `email` scope.
+
+## Transports
+
+`selectTransport(env)` picks `capture` in development and `gateway` in staging and production. Captured mail is written to `.mail/` as `.eml` files (Node) or logged (workerd), and never sent. Set `WORKBENCH_EMAIL_LIVE=1` to send for real from development; a development key can still only mail Robert. Constructing the capture transport in staging or production throws.
+
+## Senders
+
+`from` must be an address added with `gw_sender_add`, on a domain onboarded to Cloudflare Email Sending with `cf_email_sending_onboard`. Anything else is refused with `sender_not_allowed` before a send.
+
+## Idempotency
+
+Send `idempotencyKey` for anything a retry could repeat. Within 24 hours the same key and message return the first result with `replayed: true`, and nothing is sent again. The same key with a different message is refused (422). A send that failed frees its key, so a retry with it goes out.
+
+## Attachments
+
+Bytes, not base64 strings. Give an inline image a `contentId` and reference it in the HTML as `cid:<id>`. At most 32 attachments and 25 MiB a message.
+
+## What a send returns
+
+`messageId`, `reachedTheInternet` (true only when Cloudflare took the mail), `requestId` (matches a usage row) and, from the Gateway, the recipients Cloudflare delivered, queued or bounced. Every error has `reachedTheInternet: false`. Each send is charged at US$0.35 per 1,000 recipients.

package/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "68923c8c9776";
+export declare const MANIFEST_VERSION: "ffb5a8a16ad1";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -410,6 +410,209 @@ export declare const capabilities: {
             readonly note: "sb_query on production with a write returns a confirmation, not a result";
         }];
     };
+    readonly email: {
+        readonly $schema: "./schema.json";
+        readonly format: 1;
+        readonly component: "email";
+        readonly title: "Transactional email through the Gateway";
+        readonly summary: "Apps send transactional mail with workbench-email, or POST /v1/email/send directly. The Gateway checks the sender and recipients, keeps idempotency keys for 24 hours, meters every send, and hands the message to Cloudflare Email Sending. Apps hold no email credential.";
+        readonly status: "built";
+        readonly surfaces: {
+            readonly gateway: readonly ["POST /v1/email/send"];
+            readonly package: readonly ["createMailer", "selectTransport", "Mailer.send", "captureSink", "WorkbenchEmailError"];
+        };
+        readonly config: readonly [{
+            readonly name: "WORKBENCH_GATEWAY_KEY";
+            readonly required: true;
+            readonly secret: true;
+            readonly environments: readonly ["staging", "production"];
+            readonly description: "Project key with the email scope, delivered as a Worker secret by gw_key_issue";
+        }, {
+            readonly name: "WORKBENCH_ENV";
+            readonly required: true;
+            readonly secret: false;
+            readonly environments: readonly ["development", "staging", "production"];
+            readonly description: "Chooses the transport: capture in development, the Gateway elsewhere";
+        }, {
+            readonly name: "WORKBENCH_EMAIL_LIVE";
+            readonly required: false;
+            readonly secret: false;
+            readonly default: "0";
+            readonly environments: readonly ["development"];
+            readonly description: "1 sends real mail from development through the Gateway (a development key can only mail Robert)";
+        }];
+        readonly limits: readonly [{
+            readonly id: "email.recipients";
+            readonly value: 50;
+            readonly unit: "recipients";
+            readonly per: "message (to, cc and bcc together)";
+            readonly enforced_by: "gateway";
+            readonly refusal: "invalid_request";
+        }, {
+            readonly id: "email.attachments";
+            readonly value: 32;
+            readonly unit: "attachments";
+            readonly per: "message";
+            readonly enforced_by: "gateway";
+            readonly refusal: "invalid_request";
+        }, {
+            readonly id: "email.message-size";
+            readonly value: 26214400;
+            readonly unit: "bytes";
+            readonly per: "message, attachments as base64";
+            readonly enforced_by: "gateway";
+            readonly refusal: "invalid_request";
+        }, {
+            readonly id: "email.subject-length";
+            readonly value: 998;
+            readonly unit: "characters";
+            readonly per: "message";
+            readonly enforced_by: "gateway";
+            readonly refusal: "invalid_request";
+        }, {
+            readonly id: "email.idempotency-window";
+            readonly value: 24;
+            readonly unit: "hours";
+            readonly per: "Idempotency-Key";
+            readonly enforced_by: "database";
+        }, {
+            readonly id: "email.upstream-timeout";
+            readonly value: 30;
+            readonly unit: "seconds";
+            readonly per: "request";
+            readonly enforced_by: "gateway";
+            readonly refusal: "upstream_timeout";
+        }];
+        readonly errors: readonly [{
+            readonly code: "sender_not_allowed";
+            readonly http: 403;
+            readonly retryable: false;
+            readonly meaning: "from isn't one of the project's senders (gw_sender_add)";
+        }, {
+            readonly code: "recipient_not_allowed";
+            readonly http: 403;
+            readonly retryable: false;
+            readonly meaning: "A development key sending to anyone but Workbench's allowlisted addresses";
+        }, {
+            readonly code: "invalid_request";
+            readonly http: 400;
+            readonly retryable: false;
+            readonly meaning: "A malformed message, a limit passed, or an Idempotency-Key reused with a different message (422)";
+        }, {
+            readonly code: "not_available";
+            readonly http: 501;
+            readonly retryable: false;
+            readonly meaning: "type bulk, until Amazon SES is built";
+        }, {
+            readonly code: "budget_exceeded";
+            readonly http: 402;
+            readonly retryable: false;
+            readonly meaning: "Enforced monthly budget reached";
+        }, {
+            readonly code: "rate_limited";
+            readonly http: 429;
+            readonly retryable: true;
+            readonly meaning: "Too many requests, Cloudflare's quota, or (409) a send with the same Idempotency-Key still in progress";
+        }, {
+            readonly code: "upstream_error";
+            readonly http: 502;
+            readonly retryable: true;
+            readonly meaning: "Cloudflare Email Sending failed; nothing was sent";
+        }, {
+            readonly code: "upstream_timeout";
+            readonly http: 504;
+            readonly retryable: true;
+            readonly meaning: "Cloudflare didn't answer within 30 seconds; the mail may or may not have gone";
+        }];
+        readonly rules: readonly [{
+            readonly id: "email.text-always";
+            readonly kind: "must";
+            readonly text: "Send a text part with every mail, even when there is HTML.";
+            readonly enforced_by: "gateway";
+            readonly probe: "email.send.transactional";
+        }, {
+            readonly id: "email.idempotency-key";
+            readonly kind: "must";
+            readonly text: "Give an idempotencyKey to any send a retry could repeat (invites, receipts, resets). A repeat within 24 hours returns the first result and sends nothing.";
+            readonly enforced_by: "review";
+            readonly probe: "email.send.idempotent-repeat";
+        }, {
+            readonly id: "email.attachments-as-bytes";
+            readonly kind: "must";
+            readonly text: "Pass attachments as bytes (Uint8Array), and give an inline image a contentId that the HTML references as cid:.";
+            readonly enforced_by: "types";
+            readonly probe: "email.send.inline-image";
+        }, {
+            readonly id: "email.allowed-sender";
+            readonly kind: "must";
+            readonly text: "Send only from an address added with gw_sender_add on a domain onboarded with cf_email_sending_onboard.";
+            readonly enforced_by: "gateway";
+            readonly probe: "email.send.sender-not-allowed";
+        }, {
+            readonly id: "email.no-capture-outside-dev";
+            readonly kind: "must_not";
+            readonly text: "Use the capture transport outside development. createMailer throws when WORKBENCH_ENV is staging or production.";
+            readonly enforced_by: "types";
+            readonly probe: "email.capture-refused-in-staging";
+        }, {
+            readonly id: "email.dev-key-allowlist";
+            readonly kind: "must_not";
+            readonly text: "Expect a development key to mail anyone but Robert. The Gateway refuses other recipients before the budget.";
+            readonly enforced_by: "gateway";
+            readonly probe: "email.send.dev-recipient-refused";
+        }, {
+            readonly id: "email.transactional-only";
+            readonly kind: "must_not";
+            readonly text: "Send bulk or marketing mail. type bulk is refused with not_available until Amazon SES is built.";
+            readonly enforced_by: "gateway";
+            readonly probe: "email.send.transactional";
+        }];
+        readonly examples: readonly [{
+            readonly id: "email.example.send";
+            readonly title: "Send a transactional mail with an inline logo";
+            readonly lang: "ts";
+            readonly code: "const env = workbenchEnv(process.env)\nconst mailer = createMailer({ env, transport: selectTransport(env), from: { address: 'hello@mail.example.com', name: 'Example' }, gateway: { key: process.env.WORKBENCH_GATEWAY_KEY! } })\nawait mailer.send({ to: user.email, subject: 'Welcome', text, html: '<img src=\"cid:logo\"> ...', template: 'welcome', idempotencyKey: `welcome:${user.id}`, attachments: [{ filename: 'logo.png', mimeType: 'image/png', bytes: logo, contentId: 'logo' }] })";
+            readonly probe: "email.send.inline-image";
+        }];
+        readonly probes: readonly [{
+            readonly id: "email.send.transactional";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0.00035;
+            readonly note: "To Robert; check that it arrives";
+        }, {
+            readonly id: "email.send.inline-image";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0.00035;
+            readonly note: "Robert checks the image renders";
+        }, {
+            readonly id: "email.send.idempotent-repeat";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0.00035;
+            readonly note: "The repeat answers replayed: true and no second mail arrives";
+        }, {
+            readonly id: "email.send.dev-recipient-refused";
+            readonly half: "runtime";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "recipient_not_allowed";
+            readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "email.send.sender-not-allowed";
+            readonly half: "runtime";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "sender_not_allowed";
+            readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "email.capture-refused-in-staging";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0;
+            readonly note: "createMailer with transport capture and WORKBENCH_ENV=staging throws invalid_config";
+        }];
+    };
     readonly "email-inbound": {
         readonly $schema: "./schema.json";
         readonly format: 1;
@@ -511,6 +714,112 @@ export declare const capabilities: {
             readonly note: "cf_email_routing_rule_delete returns a confirmation and changes nothing until Robert approves";
         }];
     };
+    readonly "email-sending": {
+        readonly $schema: "./schema.json";
+        readonly format: 1;
+        readonly component: "email-sending";
+        readonly title: "Sending domains and sender addresses";
+        readonly summary: "Control onboards a domain in the project's namespace to Cloudflare Email Sending in the projects account, with its bounce, SPF, DKIM and DMARC records checked over DNS-over-HTTPS, and allows sender addresses on it. The Gateway sends from those addresses only.";
+        readonly status: "built";
+        readonly surfaces: {
+            readonly tools: readonly ["cf_email_sending_onboard", "cf_email_sending_status", "gw_sender_add", "gw_sender_list"];
+        };
+        readonly limits: readonly [{
+            readonly id: "email-sending.domains-per-zone";
+            readonly value: 30;
+            readonly unit: "domains";
+            readonly per: "zone, Email Sending and Email Routing together";
+            readonly enforced_by: "control";
+        }];
+        readonly actions: readonly [{
+            readonly tool: "cf_email_sending_onboard";
+            readonly gate: "free";
+            readonly ships: "4";
+        }, {
+            readonly tool: "cf_email_sending_status";
+            readonly gate: "free";
+            readonly ships: "4";
+        }, {
+            readonly tool: "gw_sender_add";
+            readonly gate: "free";
+            readonly ships: "4";
+        }, {
+            readonly tool: "gw_sender_list";
+            readonly gate: "free";
+            readonly ships: "4";
+        }];
+        readonly errors: readonly [{
+            readonly code: "out_of_scope";
+            readonly http: 403;
+            readonly retryable: false;
+            readonly meaning: "A domain outside the project's namespace, or a sender on a domain the project hasn't onboarded";
+        }, {
+            readonly code: "name_taken";
+            readonly http: 409;
+            readonly retryable: false;
+            readonly meaning: "The domain or address is already onboarded or allowed outside this project; Control never adopts";
+        }, {
+            readonly code: "record_conflict";
+            readonly http: 409;
+            readonly retryable: false;
+            readonly meaning: "A DNS record in the way that Control won't change (another SPF, DMARC, MX or CNAME)";
+        }, {
+            readonly code: "missing_permission";
+            readonly http: 403;
+            readonly retryable: false;
+            readonly meaning: "Control's Cloudflare token lacks Email Sending (edit)";
+        }];
+        readonly rules: readonly [{
+            readonly id: "email-sending.namespace-only";
+            readonly kind: "must";
+            readonly text: "Onboard a domain in the project's own namespace, for example mail.<id>.mccaskielabs.app. Project-owned zones such as wbprobe.com follow cf_zone_attach (step 6.1).";
+            readonly enforced_by: "control";
+            readonly probe: "email-sending.onboard";
+        }, {
+            readonly id: "email-sending.onboard-before-sender";
+            readonly kind: "must";
+            readonly text: "Onboard the domain before adding senders on it. gw_sender_add refuses a domain the project hasn't onboarded.";
+            readonly enforced_by: "control";
+            readonly probe: "email-sending.sender-add";
+        }, {
+            readonly id: "email-sending.never-adopt";
+            readonly kind: "must_not";
+            readonly text: "Expect Control to take over a domain onboarded by hand. It refuses with name_taken.";
+            readonly enforced_by: "control";
+            readonly probe: "email-sending.onboard";
+        }, {
+            readonly id: "email-sending.verified-over-doh";
+            readonly kind: "must";
+            readonly text: "Treat a domain as ready only when cf_email_sending_status says ready: every expected record is in the zone and visible over DNS-over-HTTPS.";
+            readonly enforced_by: "control";
+            readonly probe: "email-sending.status";
+        }];
+        readonly probes: readonly [{
+            readonly id: "email-sending.onboard";
+            readonly half: "drill";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0;
+            readonly note: "cf_email_sending_onboard on mail.<id>.mccaskielabs.app; a second call changes nothing";
+        }, {
+            readonly id: "email-sending.status";
+            readonly half: "drill";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0;
+        }, {
+            readonly id: "email-sending.sender-add";
+            readonly half: "drill";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0;
+            readonly note: "Then a runtime send from the new address (email.send.transactional)";
+        }, {
+            readonly id: "email-sending.out-of-scope";
+            readonly half: "drill";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "out_of_scope";
+            readonly cost_hint_usd: 0;
+            readonly note: "Another project's namespace";
+        }];
+    };
     readonly gateway: {
         readonly $schema: "./schema.json";
         readonly format: 1;

package/dist/capabilities.gen.js

@@ -1,6 +1,6 @@
 // Generated by `npm run capabilities:build` from capabilities/*.json. Do not edit.
 // check:capabilities fails in Checks when this file is stale.
-export const MANIFEST_VERSION = "68923c8c9776";
+export const MANIFEST_VERSION = "ffb5a8a16ad1";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -570,6 +570,263 @@ export const capabilities = {
             }
         ]
     },
+    "email": {
+        "$schema": "./schema.json",
+        "format": 1,
+        "component": "email",
+        "title": "Transactional email through the Gateway",
+        "summary": "Apps send transactional mail with workbench-email, or POST /v1/email/send directly. The Gateway checks the sender and recipients, keeps idempotency keys for 24 hours, meters every send, and hands the message to Cloudflare Email Sending. Apps hold no email credential.",
+        "status": "built",
+        "surfaces": {
+            "gateway": [
+                "POST /v1/email/send"
+            ],
+            "package": [
+                "createMailer",
+                "selectTransport",
+                "Mailer.send",
+                "captureSink",
+                "WorkbenchEmailError"
+            ]
+        },
+        "config": [
+            {
+                "name": "WORKBENCH_GATEWAY_KEY",
+                "required": true,
+                "secret": true,
+                "environments": [
+                    "staging",
+                    "production"
+                ],
+                "description": "Project key with the email scope, delivered as a Worker secret by gw_key_issue"
+            },
+            {
+                "name": "WORKBENCH_ENV",
+                "required": true,
+                "secret": false,
+                "environments": [
+                    "development",
+                    "staging",
+                    "production"
+                ],
+                "description": "Chooses the transport: capture in development, the Gateway elsewhere"
+            },
+            {
+                "name": "WORKBENCH_EMAIL_LIVE",
+                "required": false,
+                "secret": false,
+                "default": "0",
+                "environments": [
+                    "development"
+                ],
+                "description": "1 sends real mail from development through the Gateway (a development key can only mail Robert)"
+            }
+        ],
+        "limits": [
+            {
+                "id": "email.recipients",
+                "value": 50,
+                "unit": "recipients",
+                "per": "message (to, cc and bcc together)",
+                "enforced_by": "gateway",
+                "refusal": "invalid_request"
+            },
+            {
+                "id": "email.attachments",
+                "value": 32,
+                "unit": "attachments",
+                "per": "message",
+                "enforced_by": "gateway",
+                "refusal": "invalid_request"
+            },
+            {
+                "id": "email.message-size",
+                "value": 26214400,
+                "unit": "bytes",
+                "per": "message, attachments as base64",
+                "enforced_by": "gateway",
+                "refusal": "invalid_request"
+            },
+            {
+                "id": "email.subject-length",
+                "value": 998,
+                "unit": "characters",
+                "per": "message",
+                "enforced_by": "gateway",
+                "refusal": "invalid_request"
+            },
+            {
+                "id": "email.idempotency-window",
+                "value": 24,
+                "unit": "hours",
+                "per": "Idempotency-Key",
+                "enforced_by": "database"
+            },
+            {
+                "id": "email.upstream-timeout",
+                "value": 30,
+                "unit": "seconds",
+                "per": "request",
+                "enforced_by": "gateway",
+                "refusal": "upstream_timeout"
+            }
+        ],
+        "errors": [
+            {
+                "code": "sender_not_allowed",
+                "http": 403,
+                "retryable": false,
+                "meaning": "from isn't one of the project's senders (gw_sender_add)"
+            },
+            {
+                "code": "recipient_not_allowed",
+                "http": 403,
+                "retryable": false,
+                "meaning": "A development key sending to anyone but Workbench's allowlisted addresses"
+            },
+            {
+                "code": "invalid_request",
+                "http": 400,
+                "retryable": false,
+                "meaning": "A malformed message, a limit passed, or an Idempotency-Key reused with a different message (422)"
+            },
+            {
+                "code": "not_available",
+                "http": 501,
+                "retryable": false,
+                "meaning": "type bulk, until Amazon SES is built"
+            },
+            {
+                "code": "budget_exceeded",
+                "http": 402,
+                "retryable": false,
+                "meaning": "Enforced monthly budget reached"
+            },
+            {
+                "code": "rate_limited",
+                "http": 429,
+                "retryable": true,
+                "meaning": "Too many requests, Cloudflare's quota, or (409) a send with the same Idempotency-Key still in progress"
+            },
+            {
+                "code": "upstream_error",
+                "http": 502,
+                "retryable": true,
+                "meaning": "Cloudflare Email Sending failed; nothing was sent"
+            },
+            {
+                "code": "upstream_timeout",
+                "http": 504,
+                "retryable": true,
+                "meaning": "Cloudflare didn't answer within 30 seconds; the mail may or may not have gone"
+            }
+        ],
+        "rules": [
+            {
+                "id": "email.text-always",
+                "kind": "must",
+                "text": "Send a text part with every mail, even when there is HTML.",
+                "enforced_by": "gateway",
+                "probe": "email.send.transactional"
+            },
+            {
+                "id": "email.idempotency-key",
+                "kind": "must",
+                "text": "Give an idempotencyKey to any send a retry could repeat (invites, receipts, resets). A repeat within 24 hours returns the first result and sends nothing.",
+                "enforced_by": "review",
+                "probe": "email.send.idempotent-repeat"
+            },
+            {
+                "id": "email.attachments-as-bytes",
+                "kind": "must",
+                "text": "Pass attachments as bytes (Uint8Array), and give an inline image a contentId that the HTML references as cid:.",
+                "enforced_by": "types",
+                "probe": "email.send.inline-image"
+            },
+            {
+                "id": "email.allowed-sender",
+                "kind": "must",
+                "text": "Send only from an address added with gw_sender_add on a domain onboarded with cf_email_sending_onboard.",
+                "enforced_by": "gateway",
+                "probe": "email.send.sender-not-allowed"
+            },
+            {
+                "id": "email.no-capture-outside-dev",
+                "kind": "must_not",
+                "text": "Use the capture transport outside development. createMailer throws when WORKBENCH_ENV is staging or production.",
+                "enforced_by": "types",
+                "probe": "email.capture-refused-in-staging"
+            },
+            {
+                "id": "email.dev-key-allowlist",
+                "kind": "must_not",
+                "text": "Expect a development key to mail anyone but Robert. The Gateway refuses other recipients before the budget.",
+                "enforced_by": "gateway",
+                "probe": "email.send.dev-recipient-refused"
+            },
+            {
+                "id": "email.transactional-only",
+                "kind": "must_not",
+                "text": "Send bulk or marketing mail. type bulk is refused with not_available until Amazon SES is built.",
+                "enforced_by": "gateway",
+                "probe": "email.send.transactional"
+            }
+        ],
+        "examples": [
+            {
+                "id": "email.example.send",
+                "title": "Send a transactional mail with an inline logo",
+                "lang": "ts",
+                "code": "const env = workbenchEnv(process.env)\nconst mailer = createMailer({ env, transport: selectTransport(env), from: { address: 'hello@mail.example.com', name: 'Example' }, gateway: { key: process.env.WORKBENCH_GATEWAY_KEY! } })\nawait mailer.send({ to: user.email, subject: 'Welcome', text, html: '<img src=\"cid:logo\"> ...', template: 'welcome', idempotencyKey: `welcome:${user.id}`, attachments: [{ filename: 'logo.png', mimeType: 'image/png', bytes: logo, contentId: 'logo' }] })",
+                "probe": "email.send.inline-image"
+            }
+        ],
+        "probes": [
+            {
+                "id": "email.send.transactional",
+                "half": "runtime",
+                "expect": "pass",
+                "smoke": true,
+                "cost_hint_usd": 0.00035,
+                "note": "To Robert; check that it arrives"
+            },
+            {
+                "id": "email.send.inline-image",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0.00035,
+                "note": "Robert checks the image renders"
+            },
+            {
+                "id": "email.send.idempotent-repeat",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0.00035,
+                "note": "The repeat answers replayed: true and no second mail arrives"
+            },
+            {
+                "id": "email.send.dev-recipient-refused",
+                "half": "runtime",
+                "expect": "refused_as_expected",
+                "refusal": "recipient_not_allowed",
+                "cost_hint_usd": 0
+            },
+            {
+                "id": "email.send.sender-not-allowed",
+                "half": "runtime",
+                "expect": "refused_as_expected",
+                "refusal": "sender_not_allowed",
+                "cost_hint_usd": 0
+            },
+            {
+                "id": "email.capture-refused-in-staging",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0,
+                "note": "createMailer with transport capture and WORKBENCH_ENV=staging throws invalid_config"
+            }
+        ]
+    },
     "email-inbound": {
         "$schema": "./schema.json",
         "format": 1,
@@ -698,6 +955,139 @@ export const capabilities = {
             }
         ]
     },
+    "email-sending": {
+        "$schema": "./schema.json",
+        "format": 1,
+        "component": "email-sending",
+        "title": "Sending domains and sender addresses",
+        "summary": "Control onboards a domain in the project's namespace to Cloudflare Email Sending in the projects account, with its bounce, SPF, DKIM and DMARC records checked over DNS-over-HTTPS, and allows sender addresses on it. The Gateway sends from those addresses only.",
+        "status": "built",
+        "surfaces": {
+            "tools": [
+                "cf_email_sending_onboard",
+                "cf_email_sending_status",
+                "gw_sender_add",
+                "gw_sender_list"
+            ]
+        },
+        "limits": [
+            {
+                "id": "email-sending.domains-per-zone",
+                "value": 30,
+                "unit": "domains",
+                "per": "zone, Email Sending and Email Routing together",
+                "enforced_by": "control"
+            }
+        ],
+        "actions": [
+            {
+                "tool": "cf_email_sending_onboard",
+                "gate": "free",
+                "ships": "4"
+            },
+            {
+                "tool": "cf_email_sending_status",
+                "gate": "free",
+                "ships": "4"
+            },
+            {
+                "tool": "gw_sender_add",
+                "gate": "free",
+                "ships": "4"
+            },
+            {
+                "tool": "gw_sender_list",
+                "gate": "free",
+                "ships": "4"
+            }
+        ],
+        "errors": [
+            {
+                "code": "out_of_scope",
+                "http": 403,
+                "retryable": false,
+                "meaning": "A domain outside the project's namespace, or a sender on a domain the project hasn't onboarded"
+            },
+            {
+                "code": "name_taken",
+                "http": 409,
+                "retryable": false,
+                "meaning": "The domain or address is already onboarded or allowed outside this project; Control never adopts"
+            },
+            {
+                "code": "record_conflict",
+                "http": 409,
+                "retryable": false,
+                "meaning": "A DNS record in the way that Control won't change (another SPF, DMARC, MX or CNAME)"
+            },
+            {
+                "code": "missing_permission",
+                "http": 403,
+                "retryable": false,
+                "meaning": "Control's Cloudflare token lacks Email Sending (edit)"
+            }
+        ],
+        "rules": [
+            {
+                "id": "email-sending.namespace-only",
+                "kind": "must",
+                "text": "Onboard a domain in the project's own namespace, for example mail.<id>.mccaskielabs.app. Project-owned zones such as wbprobe.com follow cf_zone_attach (step 6.1).",
+                "enforced_by": "control",
+                "probe": "email-sending.onboard"
+            },
+            {
+                "id": "email-sending.onboard-before-sender",
+                "kind": "must",
+                "text": "Onboard the domain before adding senders on it. gw_sender_add refuses a domain the project hasn't onboarded.",
+                "enforced_by": "control",
+                "probe": "email-sending.sender-add"
+            },
+            {
+                "id": "email-sending.never-adopt",
+                "kind": "must_not",
+                "text": "Expect Control to take over a domain onboarded by hand. It refuses with name_taken.",
+                "enforced_by": "control",
+                "probe": "email-sending.onboard"
+            },
+            {
+                "id": "email-sending.verified-over-doh",
+                "kind": "must",
+                "text": "Treat a domain as ready only when cf_email_sending_status says ready: every expected record is in the zone and visible over DNS-over-HTTPS.",
+                "enforced_by": "control",
+                "probe": "email-sending.status"
+            }
+        ],
+        "probes": [
+            {
+                "id": "email-sending.onboard",
+                "half": "drill",
+                "expect": "pass",
+                "cost_hint_usd": 0,
+                "note": "cf_email_sending_onboard on mail.<id>.mccaskielabs.app; a second call changes nothing"
+            },
+            {
+                "id": "email-sending.status",
+                "half": "drill",
+                "expect": "pass",
+                "cost_hint_usd": 0
+            },
+            {
+                "id": "email-sending.sender-add",
+                "half": "drill",
+                "expect": "pass",
+                "cost_hint_usd": 0,
+                "note": "Then a runtime send from the new address (email.send.transactional)"
+            },
+            {
+                "id": "email-sending.out-of-scope",
+                "half": "drill",
+                "expect": "refused_as_expected",
+                "refusal": "out_of_scope",
+                "cost_hint_usd": 0,
+                "note": "Another project's namespace"
+            }
+        ]
+    },
     "gateway": {
         "$schema": "./schema.json",
         "format": 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-config",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Workbench app configuration: WORKBENCH_ENV, typed variables that fail by name, secrets that are never printed, and the capabilities manifest.",
   "license": "UNLICENSED",
   "type": "module",